Mengakses registry pribadi dengan sertifikat CA pribadi

Autopilot Standard

---

Halaman ini menunjukkan cara mengizinkan workload yang berjalan di Google Kubernetes Engine (GKE) untuk mengakses registry image pribadi menggunakan kunci publik certificate authority (CA) yang mengeluarkan sertifikat untuk registry.

Cara kerjanya

Anda menyimpan kunci publik CA yang digunakan untuk menerbitkan sertifikat untuk registry pribadi di Secret Manager dan mengonfigurasi nama domain lengkap (FQDN) registry mana yang menggunakan kunci publik tersebut untuk validasi sertifikat. GKE akan otomatis mengambil kunci dan memperbarui konfigurasi registry runtime penampung selama bootstrap node. Saat Anda men-deploy workload yang menggunakan image container dari registry pribadi, langkah-langkah berikut akan terjadi:

1. Kubelet di node mencoba mengambil image dari registry pribadi.
2. Registry menampilkan sertifikat TLS sisi server.
3. Runtime penampung memvalidasi sertifikat registry secara kriptografis dan untuk memastikan bahwa FQDN cocok dengan yang Anda tentukan.
4. Jika validasi berhasil, GKE akan mengambil image dan menjadwalkan workload Anda.

Manfaat

Metode mengakses registry pribadi ini memberikan manfaat seperti berikut:

1. Meningkatkan keandalan konfigurasi runtime penampung: Menggunakan metode seperti DaemonSet untuk menetapkan konfigurasi containerd akan meningkatkan risiko terjadinya kondisi perlombaan, saat DaemonSet lain mungkin berjalan sebelum DaemonSet konfigurasi Anda.
2. Mengurangi kerentanan terhadap serangan eskalasi akses: Menghapus kebutuhan untuk menjalankan DaemonSet dengan hak istimewa yang mengubah konfigurasi runtime container Anda.
3. Mengurangi overhead pengelolaan: Secret Manager memungkinkan Anda menyimpan kunci publik CA di lokasi pusat; mengelola akses ke kunci menggunakan IAM; serta menerapkan kontrol versi dan anotasi. Untuk mengetahui informasi selengkapnya, lihat ringkasan produk Secret Manager.
4. Meningkatkan auditabilitas: Cloud Logging sudah mengumpulkan log, termasuk saat sertifikat ditambahkan ke cluster dan saat node GKE menarik image.

Harga

Dalam dokumen ini, Anda akan menggunakan komponen Google Cloud yang dapat ditagih berikut:

• GKE
• Secret Manager
• Logging: GKE membuat log audit Aktivitas Admin dan, jika diaktifkan, log audit Akses Data untuk fitur ini. Untuk mengetahui informasi tentang berbagai jenis log audit, lihat Logging audit GKE.

Untuk membuat perkiraan biaya berdasarkan proyeksi penggunaan Anda, gunakan kalkulator harga.

Sebelum memulai

Sebelum memulai, pastikan Anda telah menjalankan tugas berikut:

• Aktifkan Google Kubernetes Engine API.
Aktifkan Google Kubernetes Engine API
• Jika ingin menggunakan Google Cloud CLI untuk tugas ini, instal lalu lakukan inisialisasi gcloud CLI. Jika sebelumnya Anda telah menginstal gcloud CLI, dapatkan versi terbaru dengan menjalankan gcloud components update.
  Catatan: Untuk penginstalan gcloud CLI yang ada, pastikan untuk menyetel properti compute/region dan compute/zone. Dengan menyetel lokasi default, Anda dapat menghindari error di gcloud CLI yang seperti ini: One of [--zone, --region] must be supplied: Please specify location.

• Aktifkan API Secret Manager.

  Mengaktifkan API

• Anda harus sudah memiliki registry pribadi dan sertifikat CA pribadi untuk mengakses registry. Panduan ini tidak membahas cara menyiapkan registry pribadi atau membuat sertifikat.

Persyaratan

Untuk menggunakan kunci publik CA pribadi guna mengakses registry pribadi, Anda harus memenuhi persyaratan berikut:

• Cluster Anda harus menggunakan GKE versi 1.27.3-gke.1700 atau yang lebih baru.
• Anda harus menggunakan image node Container-Optimized OS dengan containerd, yang merupakan default untuk semua cluster GKE. Image node Ubuntu dengan containerd tidak didukung. Image node Windows Server tidak didukung.
• Node pool Anda harus memiliki cakupan akses cloud-platform agar node dapat mendownload sertifikat. Untuk mengetahui informasi selengkapnya, lihat Cakupan akses default di GKE. Dokumen ini mencakup petunjuk untuk menetapkan cakupan akses saat Anda membuat cluster atau node pool.

Batasan

Pertimbangkan batasan berikut:

• Anda tidak dapat menggunakan sertifikat CA pribadi dalam image node Ubuntu.
• Anda tidak dapat menggunakan sertifikat CA pribadi di node Windows Server.
• Setiap cluster mendukung hingga lima sertifikat CA pribadi untuk registry pribadi.
• Setiap sertifikat dapat memiliki hingga 25 nama domain yang sepenuhnya memenuhi syarat (FQDN).
• Setiap domain hanya dapat digunakan dalam satu file sertifikat. Namun, paket sertifikat didukung.
• Sertifikat harus dienkode PEM.
• Server tidak otomatis merotasi sertifikat. Untuk mengetahui informasi selengkapnya, lihat Merotasi sertifikat CA pribadi dalam dokumen ini.
• FQDN memiliki batasan berikut:
  • Panjang FQDN maksimum adalah 255 karakter, termasuk karakter khusus.
  • FQDN hanya dapat menggunakan huruf, angka, dan tanda hubung (-).
  • Punycode tidak didukung.
  • Karakter pengganti tidak didukung.

Bermigrasi dari DaemonSet konfigurasi

Di cluster GKE Standard, Anda dapat men-deploy DaemonSet dengan hak istimewa untuk mengubah konfigurasi runtime penampung. Metode ini langsung mengubah konfigurasi containerd di setiap node.

Jika Anda menggunakan DaemonSet dengan hak istimewa untuk mengonfigurasi akses ke registry pribadi, pertimbangkan hal berikut sebelum menggunakan dokumen ini:

• Menyimpan kunci publik CA pribadi di Secret Manager hanya mengonfigurasi akses ke registry pribadi. Konfigurasi terkait registry lainnya tidak didukung.

• Mengaktifkan fitur ini akan menyebabkan cluster Anda menggunakan model konfigurasi hostpath CRI containerd, yang tidak kompatibel dengan model konfigurasi sebelumnya. Jika Anda memiliki Daemonset yang mengubah konfigurasi host containerd, seperti untuk registry, mirror, atau proxy pribadi yang tidak aman, perbarui Daemonset untuk menggunakan model hostpath CRI.

  Untuk mengetahui kolom yang tersedia dalam model hostpath CRI, lihat Konfigurasi registry di repositori GitHub containerd.

  Catatan: Jika Anda menonaktifkan fitur ini nanti, node akan kembali ke model sebelumnya untuk konfigurasi registry di containerd. Anda harus mengubah DaemonSet untuk menggunakan model sebelumnya. Untuk informasi tentang model konfigurasi sebelumnya, lihat Mengonfigurasi kredensial registry.

Saat Anda mengaktifkan fitur ini, GKE akan menerapkan model konfigurasi hostpath CRI ke node baru di cluster. Node yang ada akan terus menggunakan model konfigurasi sebelumnya hingga dibuat ulang selama peristiwa seperti upgrade.

Mengupdate DaemonSet untuk mendukung kedua model konfigurasi

Untuk mengurangi risiko DaemonSet konfigurasi Anda tidak berfungsi di node yang mendukung model konfigurasi tertentu, pastikan DaemonSet Anda menggunakan model konfigurasi tertentu secara kondisional, bergantung pada file konfigurasi containerd di node. Untuk contoh DaemonSet yang menerapkan logika kondisional ini, di repositori GitHub GoogleCloudPlatform/k8s-node-tools, lihat manifes insecure-registry-config.yaml.

Menyimpan kunci publik CA Anda di Secret Manager

Simpan kunci publik CA pribadi Anda yang menerbitkan sertifikat registry pribadi Anda sebagai secret di Secret Manager. Untuk mengetahui petunjuknya, dalam dokumentasi Secret Manager, lihat Membuat secret.

Mengonfigurasi akses ke Secret Manager dari GKE

Untuk memastikan bahwa akun layanan IAM cluster memiliki izin yang diperlukan untuk mengambil secret dari Secret Manager, minta administrator untuk memberikan akun layanan IAM cluster peran IAM berikut pada secret:

• Mengakses konten secret: Secret Manager Secret Accessor (roles/secretmanager.secretAccessor)
• Mengakses metadata secret: Secret Manager Viewer (roles/secretmanager.viewer)

Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran bawaan ini berisi izin yang diperlukan untuk mengambil secret dari Secret Manager. Untuk melihat izin yang benar-benar diperlukan, luaskan bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk mengambil secret dari Secret Manager:

• resourcemanager.projects.get
• resourcemanager.projects.list
• secretmanager.secrets.get
• secretmanager.secrets.list
• secretmanager.versions.get
• secretmanager.versions.list
• secretmanager.versions.access

Administrator Anda mungkin juga dapat memberikan izin ini kepada akun layanan IAM cluster dengan peran khusus atau peran bawaan lainnya.

Jika Anda tidak mengaitkan akun layanan IAM kustom dengan cluster atau node pool, yang merupakan pendekatan yang kami rekomendasikan, cluster akan menggunakan akun layanan default Compute Engine. Jika memungkinkan, sebaiknya konfigurasikan cluster dan node pool Anda dengan akun layanan IAM dengan hak istimewa minimal. Untuk mendapatkan petunjuk, lihat Menggunakan akun layanan dengan hak istimewa terendah.

Membuat file konfigurasi runtime

Untuk mengaktifkan kemampuan menggunakan sertifikat CA pribadi untuk registry pribadi di GKE, Anda membuat file YAML untuk mengubah konfigurasi containerd.

1. Dapatkan nomor project Google Cloud Anda:

   gcloud projects describe PROJECT_ID \
       --format="value(projectNumber)"
   

   Output-nya adalah nomor project numerik Anda.

2. Simpan konfigurasi berikut sebagai containerd-configuration.yaml:

   privateRegistryAccessConfig:
     certificateAuthorityDomainConfig:
     - gcpSecretManagerCertificateConfig:
         secretURI: "projects/PROJECT_NUMBER/secrets/SECRET_NAME/versions/SECRET_VERSION"
       fqdns:
         - "FQDN1"
         - "FQDN2"
     enabled: true
   

   Ganti kode berikut:

   • PROJECT_NUMBER: nomor project yang Anda dapatkan di langkah sebelumnya.
   • SECRET_VERSION: nomor versi secret Anda di Secret Manager. Anda dapat menggunakan alias versi secara opsional, tetapi sebaiknya gunakan nomor versi untuk menghindari kompleksitas pengelolaan.
   • FQDN1, FQDN2: nama domain yang sepenuhnya memenuhi syarat (FQDN) untuk registry pribadi Anda. Anda juga dapat menggunakan alamat IPv4 jika sertifikat dikeluarkan untuk alamat tersebut, tetapi kami tidak merekomendasikannya.

Untuk deskripsi kolom ini, lihat privateRegistryAccessConfig di tabel Opsi konfigurasi containerd yang tersedia.

Menerapkan konfigurasi containerd ke cluster baru

Bagian ini menunjukkan cara menerapkan file konfigurasi containerd saat Anda membuat cluster GKE baru.

Jalankan perintah berikut:

gcloud container clusters create-auto CLUSTER_NAME \
    --location=LOCATION \
    --scopes="cloud-platform" \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

Ganti kode berikut:

• CLUSTER_NAME: nama cluster baru.
• LOCATION: lokasi Compute Engine cluster baru Anda.
• PATH_TO_CONFIG_FILE: jalur ke file konfigurasi yang Anda buat, seperti ~/containerd-configuration.yaml.

Anda dapat mengaktifkan konfigurasi registry pribadi di cluster Standar baru dengan menjalankan perintah gcloud container clusters create dengan opsi yang sama.

Menerapkan konfigurasi containerd ke cluster yang ada

Bagian ini menunjukkan cara menerapkan konfigurasi containerd ke cluster dan node yang ada.

Catatan: Memperbarui cluster dengan konfigurasi containerd akan membuat ulang node untuk menerapkan konfigurasi. Hal ini dapat menyebabkan gangguan sementara dalam menjalankan beban kerja. GKE hanya membuat ulang node jika upgrade otomatis diaktifkan. Pembuatan ulang ini mematuhi masa pemeliharaan yang Anda tetapkan. Di cluster Standard yang tidak mengaktifkan upgrade otomatis, Anda harus membuat ulang node secara manual untuk menerapkan konfigurasi.

Memeriksa cakupan akses

Cluster yang ada harus memiliki cakupan akses cloud-platform untuk menggunakan fitur ini. Bagian ini menunjukkan cara memeriksa cakupan akses dan mengupdate cluster yang ada dengan file konfigurasi registry pribadi yang baru atau dimodifikasi.

Untuk mengetahui detail tentang cakupan akses default di cluster baru, lihat Cakupan akses di GKE.

Memeriksa cakupan akses Autopilot

Jalankan perintah berikut:

gcloud container clusters describe CLUSTER_NAME \
    --location=LOCATION \
    --flatten=nodeConfig \
    --format='csv[delimiter="\\n",no-heading](oauthScopes)'

Jika cluster Anda tidak memiliki cakupan akses https://www.googleapis.com/auth/cloud-platform, buat cluster baru dengan cakupan akses ini.

Memeriksa Cakupan akses standar

Untuk memeriksa cakupan akses cluster Standard, periksa node pool:

gcloud container node-pools describe NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=LOCATION \
    --flatten=nodeConfig \
    --format='csv[delimiter="\\n",no-heading](oauthScopes)'

Ganti NODE_POOL_NAME dengan nama node pool.

Jika cluster Anda tidak memiliki cakupan akses https://www.googleapis.com/auth/cloud-platform, buat node pool baru dengan cakupan akses cloud-platform dan hapus node pool yang ada.

Mengupdate cluster untuk menggunakan file konfigurasi Anda

Jalankan perintah berikut:

gcloud container clusters update CLUSTER_NAME \
    --location=LOCATION \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

Membuat ulang node di cluster Standard

Jika cluster Standard tidak menggunakan upgrade otomatis, Anda harus membuat ulang node pool secara manual untuk menerapkan konfigurasi baru. Untuk memicu pembuatan ulang node manual, upgrade cluster ke versi GKE yang sama dengan yang sudah digunakan.

gcloud container clusters upgrade CLUSTER_NAME \
    --location=LOCATION \
    --cluster-version=VERSION

Ganti VERSION dengan versi patch GKE yang sama dengan yang sudah digunakan cluster.

Memverifikasi bahwa cluster Anda dapat mengakses registry pribadi

Jalankan perintah berikut:

gcloud container clusters describe CLUSTER_NAME \
    --location=LOCATION \
    --flatten="nodePoolDefaults.nodeConfigDefaults.containerdConfig"

Outputnya mirip dengan hal berikut ini:

    containerdConfig:
      privateRegistryAccessConfig:
        certificateAuthorityDomainConfig:
        - fqdns:
          - 203.0.113.105
          gcpSecretManagerCertificateConfig:
            secretUri: projects/123456789012/secrets/example-secret-name/versions/1
        enabled: true

Men-deploy workload yang mengakses image pribadi

Di bagian ini, Anda akan men-deploy Pod statis yang mereferensikan image dari registry pribadi.

1. Simpan manifes berikut sebagai private-registry-pod.yaml:

   apiVersion: v1
   kind: Pod
   metadata:
     name: private-registry-pod
   spec:
     containers:
     - name: private-image
       image: IMAGE_NAME
   

   Ganti IMAGE_NAME dengan nama image pribadi Anda.

2. Deploy Pod:

   kubectl create -f private-registry-pod.yaml
   

Merotasi sertifikat CA pribadi

Secret Manager dan GKE tidak dapat secara otomatis memutar sertifikat CA pribadi di Secret Manager. Untuk melakukan rotasi sertifikat, lakukan langkah-langkah berikut. Langkah-langkah ini mengharuskan Anda membuat ulang node yang ada dua kali. Sebaiknya lakukan rotasi sertifikat selama periode nonaktif terjadwal untuk meminimalkan dampak gangguan beban kerja.

1. Buat paket sertifikat berenkode PEM yang berisi sertifikat lama dan baru Anda.
2. Tambahkan paket sebagai versi secret baru di Secret Manager.
3. Perbarui kolom secretURI file konfigurasi runtime dengan nomor versi secret baru.
4. Perbarui cluster Anda untuk menggunakan versi secret baru.

5. Dapatkan stempel waktu operasi update:

   gcloud container operations list \
       --filter="operationType ~ UPDATE_CLUSTER AND targetLink ~ CLUSTER_NAME" \
       --sort-by=startTime \
       --limit=1 \
       --format='value(endTime)'
   

   Outputnya mirip dengan hal berikut ini:

   2024-01-31T09:27:30.864308964Z
   

6. Cari node yang dibuat sebelum operasi update berakhir:

   kubectl get nodes -o json | jq ".items[] |
   select(.metadata.creationTimestamp | fromdateiso8601 < $(date -d
   CLUSTER_UPDATE_TIMESTAMP +%s)) | .metadata.name"
   

   Ganti CLUSTER_UPDATE_TIMESTAMP dengan stempel waktu dari langkah sebelumnya.

   Outputnya adalah daftar nama node yang belum dibuat ulang dengan konfigurasi yang diperbarui. Jika output kosong, lanjutkan ke langkah berikutnya.

7. Buat versi baru secret Anda di Secret Manager dengan hanya sertifikat baru.

8. Ulangi langkah-langkah sebelumnya untuk mengupdate cluster, mendapatkan stempel waktu operasi, dan memverifikasi bahwa node Anda menggunakan versi secret baru.

9. Hapus versi secret lama dari Secret Manager.

Melihat log audit di Logging

Bagian ini menunjukkan cara menggunakan Logging untuk memeriksa apakah GKE menginstal versi secret Anda di node.

1. Buka halaman Logs Explorer di konsol Google Cloud:

   Buka Logs Explorer

2. Tentukan kueri berikut:

   resource.type="gce_instance"
   textPayload:"Installed certificate \\\"projects/PROJECT_NUMBER/secrets/SECRET_NAME/versions/SECRET_VERSION\\\""
   

   Jika penginstalan sertifikat Anda berhasil, outputnya akan mirip dengan berikut:

   "Installed certificate "projects/PROJECT_NUMBER/secrets/SECRET_NAME/versions/SECRET_VERSION""
   

   Jika penginstalan sertifikat Anda gagal, outputnya akan mirip dengan berikut:

   "Failed to install certificate "projects/PROJECT_NUMBER/secrets/SECRET_NAME/versions/SECRET_VERSION""
   

Praktik terbaik

Sebaiknya gunakan praktik terbaik berikut saat Anda menggunakan fitur ini:

• Jangan gunakan alias untuk versi secret Secret Manager. Gunakan nomor versi yang dibuat otomatis untuk setiap versi secret. Alias mungkin mengarah ke versi sertifikat yang berbeda dari waktu ke waktu, yang dapat menyebabkan kompleksitas dalam melacak versi tertentu yang digunakan oleh workload Anda.
• Gunakan masa pemeliharaan dan pengecualian untuk mengontrol kapan GKE dapat membuat ulang node Anda untuk menerapkan konfigurasi containerd yang diperbarui.
• Berikan akses ke secret di level secret, bukan di level project.

Menonaktifkan opsi konfigurasi containerd

Untuk menghapus konfigurasi kustom, lakukan hal berikut:

1. Perbarui file konfigurasi untuk menentukan enabled: false dalam item konfigurasi yang ingin Anda nonaktifkan dan hapus kolom lain dalam item, seperti pada contoh berikut:

   privateRegistryAccessConfig:
     enabled: false

2. Terapkan file konfigurasi yang telah diupdate ke cluster Anda. Untuk mengetahui petunjuknya, lihat Menerapkan konfigurasi containerd ke cluster yang ada.

Memecahkan masalah

Untuk mengetahui langkah-langkah pemecahan masalah, lihat Memecahkan masalah runtime container.