Akses registry pribadi dengan sertifikat CA pribadi

Autopilot Standard

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

Cara kerjanya

Anda menyimpan kunci publik CA yang digunakan untuk menerbitkan sertifikat bagi registry pribadi Anda di Secret Manager dan mengonfigurasi registry yang sepenuhnya memenuhi syarat domain untuk menggunakan kunci publik tersebut untuk validasi sertifikat. GKE otomatis mengambil kunci dan mengupdate konfigurasi registry runtime container selama bootstrap node. Saat Anda men-deploy beban kerja yang menggunakan image container dari registry pribadi Anda, langkah-langkah berikut akan terjadi:

Kubelet pada node mencoba menarik image dari registry pribadi.
Registry menampilkan sertifikat TLS sisi server.
Runtime container memvalidasi sertifikat registry secara kriptografis dan untuk memastikan bahwa FQDN cocok dengan yang Anda tentukan.
Jika validasi lulus, GKE akan mengambil image dan menjadwalkan workload Anda.

Manfaat

Metode mengakses registry pribadi ini memberikan manfaat seperti berikut:

Meningkatkan keandalan konfigurasi runtime container: Penggunaan metode seperti DaemonSets untuk menetapkan konfigurasi dalam container akan menambah risiko terjadinya kondisi race, yang memungkinkan DaemonSet lain berjalan sebelum DaemonSet konfigurasi Anda.
Mengurangi kerentanan terhadap serangan eskalasi hak istimewa: Meniadakan kebutuhan untuk menjalankan DaemonSet dengan hak istimewa yang mengubah konfigurasi runtime container Anda.
Mengurangi overhead pengelolaan: Secret Manager memungkinkan Anda menyimpan kunci publik CA di lokasi terpusat; mengelola akses ke kunci tersebut menggunakan IAM; serta menerapkan kontrol versi dan anotasi. Untuk mengetahui informasi selengkapnya, lihat Ringkasan produk Secret Manager.
Meningkatkan kemampuan audit: Cloud Logging sudah mengumpulkan log, termasuk saat sertifikat ditambahkan ke cluster dan saat node GKE menarik gambar.

Harga

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

GKE
Secret Manager
Logging: GKE menghasilkan 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 initialize 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.

Enable the Secret Manager API.
Enable the API
Anda harus sudah memiliki registry pribadi dan sertifikat CA pribadi untuk mengakses registry. Panduan ini tidak mencakup penyiapan registry pribadi atau pembuatan sertifikat.

Persyaratan

Agar dapat menggunakan kunci publik CA pribadi untuk 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 Container-Optimized OS dengan image node dalam container, yang merupakan setelan default untuk semua cluster GKE. Node image Ubuntu dengan containerd tidak didukung. Image node Windows Server tidak didukung.
Kumpulan node Anda harus memiliki cakupan akses cloud-platform agar node Anda dapat mendownload sertifikat. Untuk mengetahui informasi selengkapnya, lihat Cakupan akses default di GKE. Dokumen ini berisi petunjuk untuk menetapkan cakupan akses saat Anda membuat cluster atau kumpulan node.

Batasan

Pertimbangkan batasan berikut:

Anda tidak dapat menggunakan sertifikat CA pribadi pada image node Ubuntu.
Anda tidak dapat menggunakan sertifikat CA pribadi di node Windows Server.
Setiap cluster mendukung hingga lima sertifikat CA pribadi untuk pendaftaran 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 merotasi sertifikat secara otomatis. Untuk 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 DaemonSets konfigurasi

Di cluster GKE Standard, Anda dapat men-deploy DaemonSets dengan hak istimewa untuk mengubah konfigurasi runtime container. Metode ini secara langsung mengubah konfigurasi dalam container pada setiap node.

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

Menyimpan kunci publik CA pribadi di Secret Manager hanya mengonfigurasi access ke registry pribadi. Konfigurasi lainnya terkait registry tidak didukung.
Jika fitur ini diaktifkan, cluster Anda akan menggunakan model konfigurasi hostpath CRI dalam container, yang tidak kompatibel dengan model konfigurasi sebelumnya. Jika Anda memiliki DaemonSet yang mengubah konfigurasi host dalam container, seperti untuk registry pribadi, pencerminan, atau proxy yang tidak aman, update DaemonSets untuk menggunakan model hostpath CRI.

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

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

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

Untuk mengurangi risiko DaemonSets konfigurasi tidak berfungsi pada node yang menggunakan model konfigurasi tertentu, pastikan DaemonSets secara kondisional menggunakan model konfigurasi tertentu, bergantung pada file konfigurasi dalam container pada node. Ini adalah pendekatan yang direkomendasikan karena mencegah masalah yang disebabkan oleh model konfigurasi yang tidak kompatibel.

Menyimpan kunci publik CA Anda di Secret Manager

Simpan kunci publik CA pribadi 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

Guna memastikan bahwa akun layanan IAM cluster memiliki izin yang diperlukan untuk mengambil secret dari Secret Manager, minta administrator Anda untuk memberikan peran IAM berikut kepada akun layanan IAM cluster secara rahasia:

Mengakses konten rahasia: Aksesor Rahasia Secret Manager (roles/secretmanager.secretAccessor)
Mengakses metadata secret: Viewer Secret Manager (roles/secretmanager.viewer)

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses.

Peran yang telah ditetapkan ini berisi izin yang diperlukan untuk mengambil secret dari Secret Manager. Untuk melihat izin yang benar-benar diperlukan, perluas 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 mungkin juga dapat memberi akun layanan IAM cluster izin ini dengan peran khusus atau peran standar 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 konfigurasi cluster dan node pool dengan akun layanan IAM dengan hak istimewa minimal. Untuk mengetahui petunjuknya, lihat Menggunakan akun layanan dengan hak istimewa paling rendah.

Membuat file konfigurasi runtime

Agar dapat menggunakan sertifikat CA pribadi untuk registry pribadi di GKE, Anda perlu membuat file YAML untuk mengubah konfigurasi dalam container.

Dapatkan nomor project Google Cloud Anda:
```
gcloud projects describe PROJECT_ID \
    --format="value(projectNumber)"
```
Outputnya adalah nomor project numerik Anda.
Simpan konfigurasi berikut sebagai containerd-configuration.yaml:
```
privateRegistryAccessConfig:
enabled: true
certificateAuthorityDomainConfig:
  - gcpSecretManagerCertificateConfig:
      secretURI: "projects/PROJECT_NUMBER/secrets/SECRET_NAME/versions/SECRET_VERSION
    fqdns:
      - "FQDN1"
      - "FQDN2"
```
Ganti kode berikut:
- PROJECT_NUMBER: nomor project yang Anda dapatkan di langkah sebelumnya.
- SECRET_VERSION: nomor versi secret Anda di Secret Manager. Secara opsional, Anda dapat menggunakan alias versi, tetapi sebaiknya gunakan nomor versi untuk menghindari kompleksitas pengelolaan.
- FQDN1, FQDN2: nama domain yang sepenuhnya memenuhi syarat untuk registry pribadi Anda. Anda juga dapat menggunakan alamat IPv4 jika sertifikat diterbitkan untuk alamat tersebut, tetapi kami tidak merekomendasikannya.

Untuk deskripsi kolom ini, lihat privateRegistryAccessConfig di tabel opsi konfigurasi container yang tersedia.

Menerapkan konfigurasi dalam container ke cluster baru

Bagian ini menunjukkan cara menerapkan file konfigurasi dalam container 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 pada cluster Standar baru dengan menjalankan perintah gcloud container clusters create dengan opsi yang sama.

Menerapkan konfigurasi dalam container ke cluster yang ada

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

Memeriksa cakupan akses

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

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

Periksa 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 Standar, periksa kumpulan node:

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 kumpulan node baru dengan cakupan akses cloud-platform, lalu hapus kumpulan node yang ada.

Update 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 Standar

Jika cluster Standar tidak menggunakan upgrade otomatis, Anda harus membuat ulang kumpulan node secara manual untuk menerapkan konfigurasi baru. Untuk memicu pembuatan ulang node manual, upgrade cluster Anda 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 versi 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 beban kerja yang mengakses image pribadi

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

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 gambar pribadi Anda.

Deploy Pod:

kubectl create -f private-registry-pod.yaml

Merotasi sertifikat CA pribadi

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

Buat paket sertifikat yang dienkode ke PEM yang berisi sertifikat lama dan baru Anda.
Tambahkan paket sebagai versi rahasia baru di Secret Manager.
Perbarui kolom secretURI file konfigurasi runtime Anda dengan nomor versi rahasia yang baru.
Update cluster Anda untuk menggunakan versi secret baru.

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

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.

Output-nya adalah daftar nama node yang belum dibuat ulang dengan konfigurasi yang diperbarui. Jika output kosong, lanjutkan ke langkah berikutnya.
Buat versi baru secret Anda di Secret Manager hanya dengan sertifikat baru.
Ulangi langkah-langkah sebelumnya untuk mengupdate cluster, mendapatkan stempel waktu operasi, dan memastikan bahwa node Anda menggunakan versi secret yang baru.
Hapus versi secret lama dari Secret Manager.

Lihat log audit di Logging

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

Buka halaman Logs Explorer di konsol Google Cloud:

Buka Logs Explorer

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 seperti berikut:

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

Jika penginstalan sertifikat Anda gagal, outputnya akan terlihat seperti 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 dapat mengarah ke versi sertifikat yang berbeda dari waktu ke waktu, yang dapat menyebabkan kompleksitas dalam pelacakan versi tertentu yang digunakan beban kerja Anda.
Gunakan masa pemeliharaan dan pengecualian untuk mengontrol kapan GKE dapat membuat ulang node Anda untuk menerapkan konfigurasi dalam container yang diperbarui.
Berikan akses ke secret di level secret, bukan di level project.

Menonaktifkan opsi konfigurasi dalam container

Untuk menghapus konfigurasi kustom, lakukan langkah berikut:

Update file konfigurasi Anda untuk menentukan enabled: false di item konfigurasi yang ingin Anda nonaktifkan dan hapus kolom lain dalam item tersebut, seperti dalam contoh berikut:
```
privateRegistryAccessConfig:
  enabled: false
```
Terapkan file konfigurasi terbaru ke cluster Anda. Untuk mendapatkan petunjuk, lihat Menerapkan konfigurasi dalam container ke cluster yang ada.

Memecahkan masalah

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