Menyesuaikan konfigurasi containerd di node GKE

Halaman ini menunjukkan cara menyesuaikan konfigurasi runtime container containerd di node Google Kubernetes Engine (GKE). Sebelum membaca dokumen ini, pastikan Anda memahami apa yang dimaksud dengan runtime penampung dan alasan Anda ingin menyesuaikannya.

Tentang konfigurasi containerd di GKE

Anda dapat mengonfigurasi serangkaian opsi secara manual di runtime containerd pada node GKE yang menjalankan sistem operasi seperti Container-Optimized OS. Menyesuaikan runtime memungkinkan Anda mengonfigurasi persyaratan khusus seperti akses ke registry image pribadi. Untuk menyetel opsi ini, Anda membuat file YAML yang disebut file konfigurasi runtime dan meneruskan file tersebut ke GKE saat Anda membuat atau mengupdate cluster atau node pool.

Metode penyesuaian containerd ini memungkinkan Anda menghindari deployment DaemonSet dengan hak istimewa, yang merupakan risiko keamanan. Saat Anda menyediakan file konfigurasi runtime ke GKE, GKE akan membuat ulang node Anda dan mengupdate file config.toml containerd di setiap node dengan konfigurasi Anda. Konfigurasi tetap ada saat node dihentikan, diupgrade, dan dibuat ulang.

Anda dapat mengonfigurasi setelan containerd di level cluster atau di level node pool. Konfigurasi tingkat node pool menggantikan konfigurasi tingkat cluster untuk opsi tersebut. Saat Anda mengupdate opsi konfigurasi containerd tingkat cluster (seperti registryHosts atau writableCgroups), GKE hanya mengupdate dan membuat ulang node di node pool yang tidak memiliki setelan tingkat node pool sendiri untuk opsi tersebut. Node pool dengan konfigurasi tingkat node pool sendiri untuk opsi ini tidak akan diupdate atau dibuat ulang dan akan terus menggunakan setelannya sendiri.

File konfigurasi runtime hanya memungkinkan Anda mengonfigurasi opsi di containerd. GKE juga mendukung konfigurasi opsi kubelet tertentu dan opsi kernel Linux level rendah menggunakan file terpisah yang disebut file konfigurasi sistem node. Untuk mengetahui detail selengkapnya, lihat Menyesuaikan konfigurasi sistem node.

Batasan

Anda tidak dapat menggunakan file konfigurasi runtime untuk mengubah setelan containerd di image node Windows.

Opsi konfigurasi containerd yang tersedia

Bagian berikut menjelaskan opsi yang dapat Anda konfigurasi menggunakan file konfigurasi runtime.

privateRegistryAccessConfig

Mengakses registry image pribadi dengan kredensial pribadi yang Anda simpan di Secret Manager.

Opsi ini tersedia dengan GKE versi 1.27.3-gke.1700 atau yang lebih baru untuk image node Container-Optimized OS, dan 1.33 atau yang lebih baru untuk image node Ubuntu.

Untuk mengetahui petunjuknya, lihat Mengakses registry pribadi dengan sertifikat CA pribadi.

privateRegistryAccessConfig:
  enabled: true
  certificateAuthorityDomainConfig:
  - gcpSecretManagerCertificateConfig:
    secretURI: "SECRET_LOCATION"
  fqdns:
  - "FQDN1"
  - "FQDN2"

Konfigurasi ini memiliki kolom berikut:

  • enabled: boolean untuk mengaktifkan konfigurasi registry pribadi. Jika Anda menetapkan enabled: false, hapus kolom lain dalam item privateRegistryAccessConfig.
  • certificateAuthorityDomainConfig: berisi hingga lima definisi sertifikat dan FQDN.
  • gcpSecretManagerCertificateConfig: berisi sertifikat yang disimpan di Secret Manager dan array FQDN.
  • secretURI: lokasi sertifikat di Secret Manager. privateRegistryAccessConfig mendukung secret global hanya di secretURI.
  • fqdns: daftar nama domain yang sepenuhnya memenuhi syarat dari registri pribadi. Anda juga dapat menggunakan alamat IPv4, tetapi sebaiknya gunakan FQDN.

registryHosts

Konfigurasikan setelan lanjutan untuk registry containerd, seperti kemampuan, header kustom, dan sertifikat. Hal ini sesuai dengan hosts.toml containerd.

Opsi ini tersedia untuk GKE versi 1.34.1-gke.2980000 atau yang lebih baru.

registryHosts:
- server: "REGISTRY_SERVER_FQDN"
  hosts:
  - host: "MIRROR_FQDN"
    capabilities:
    - "HOST_CAPABILITY_PULL"
    - "HOST_CAPABILITY_RESOLVE"
    - "HOST_CAPABILITY_PUSH"
    overridePath: false
    dialTimeout: "30s"
    header:
    - key: "HEADER_KEY"
      value:
      - "HEADER_VALUE_1"
      - "HEADER_VALUE_2"
    ca:
    - gcpSecretManagerSecretUri: "projects/PROJECT_ID_OR_NUMBER/secrets/CA_SECRET/versions/VERSION"
    client:
    - cert:
        gcpSecretManagerSecretUri: "projects/PROJECT_ID_OR_NUMBER/secrets/CLIENT_CERT_SECRET/versions/VERSION"
      key:
        gcpSecretManagerSecretUri: "projects/PROJECT_ID_OR_NUMBER/secrets/CLIENT_KEY_SECRET/versions/VERSION"

Konfigurasi ini memiliki kolom berikut:

  • server: Nama host server registry (misalnya, example.com). Ini digunakan untuk memberi nama file konfigurasi di node. Ini harus berupa nama domain atau alamat IP yang sepenuhnya memenuhi syarat tanpa skema, port, atau jalur.
  • hosts: Daftar konfigurasi khusus host untuk server.
  • host: Nama host mirror registry (misalnya, https://mirror.example.com:8000/1234, 1.2.3.4:80). Nama host ini harus berupa nama domain yang sepenuhnya memenuhi syarat (FQDN) atau alamat IP. Skema, port, dan jalur didukung. Skema hanya dapat berupa http atau https.
  • capabilities: Daftar kemampuan yang menentukan operasi yang dapat dilakukan host. Nilai yang didukung adalah salah satu nilai berikut:
    • HOST_CAPABILITY_PULL: mewakili kemampuan untuk mengambil manifes dan blob berdasarkan ringkasan.
    • HOST_CAPABILITY_RESOLVE: merepresentasikan kemampuan untuk mengambil manifes berdasarkan nama.
    • HOST_CAPABILITY_PUSH: mewakili kemampuan untuk mengirim blob dan manifes.
    Jika tidak ditentukan, semua kemampuan akan diaktifkan.
  • overridePath: Boolean. Jika true, menunjukkan bahwa endpoint root API host ditentukan di jalur URL, bukan oleh spesifikasi API. Hal ini dapat digunakan dengan registry OCI yang tidak mematuhi dan tidak memiliki awalan /v2. Setelan defaultnya adalah false.
  • dialTimeout: String durasi (misalnya, "30s") yang menentukan durasi maksimum yang diizinkan untuk penyelesaian upaya koneksi. Nilai maksimum yang diizinkan adalah "180s". Jika tidak ditetapkan, containerd akan menetapkan default "30s". Nilai harus berupa angka desimal detik dengan akhiran s.
  • header: Daftar header HTTP kustom yang akan dikirim ke host registry.
    • key: Kunci header.
    • value: Daftar nilai header.
  • ca: Daftar konfigurasi sertifikat untuk Certificate Authority (CA) host registri. Untuk membuat secret untuk sertifikat dan mengonfigurasi izin yang diperlukan, lihat petunjuk di Menyimpan kunci publik CA Anda di Secret Manager.
    • gcpSecretManagerSecretUri: URI secret di Secret Manager yang berisi sertifikat CA. Secret Manager mendukung secret global dan secret regional. Berikut adalah format untuk masing-masing jenis secret:
      • Format secret global: projects/PROJECT_ID_OR_NUMBER/secrets/SECRET_NAME/versions/VERSION.
      • Format secret regional: projects/PROJECT_ID_OR_NUMBER/locations/REGION/secrets/SECRET_NAME/versions/VERSION.
  • client: Daftar pasangan kunci dan sertifikat klien untuk mengautentikasi ke host registri. Untuk membuat secret untuk sertifikat dan mengonfigurasi izin yang diperlukan, lihat petunjuk di Menyimpan kunci publik CA Anda di Secret Manager.
    • cert: Konfigurasi sertifikat klien.
      • gcpSecretManagerSecretUri: URI secret di Secret Manager yang berisi sertifikat klien. Layanan ini mendukung secret global dan secret regional.
    • key: Konfigurasi kunci pribadi klien.
      • gcpSecretManagerSecretUri: URI secret di Secret Manager yang berisi kunci klien. Secret Manager mendukung secret global dan secret regional.

writableCgroups

Instal sistem file /sys/fs/cgroup dalam mode baca-tulis sehingga workload dapat mengelola resource proses turunannya.

Opsi ini tersedia untuk GKE versi 1.34.1-gke.2541000 atau yang lebih baru.

Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi cgroup yang dapat ditulis untuk container.

writableCgroups:
  enabled: true

Menerapkan konfigurasi containerd ke cluster baru

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

Jalankan perintah berikut untuk membuat cluster Autopilot:

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 untuk cluster baru Anda.
  • PATH_TO_CONFIG_FILE: jalur ke file konfigurasi yang Anda buat, seperti ~/containerd-configuration.yaml.

Anda dapat mengaktifkan konfigurasi containerd di cluster Standar baru dengan menjalankan perintah gcloud container clusters create dengan opsi yang sama. Kecuali jika Anda menentukan konfigurasi containerd yang berbeda, node pool baru yang dibuat di cluster akan mewarisi konfigurasi containerd default tingkat cluster.

Menerapkan konfigurasi containerd ke node pool baru

Anda dapat menerapkan konfigurasi containerd ke node pool GKE baru dengan perintah berikut:

gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=LOCATION \
    --scopes="cloud-platform" \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

Ganti kode berikut:

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

Menerapkan konfigurasi containerd ke cluster yang ada

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

Memperbarui konfigurasi containerd level cluster hanya berlaku untuk node pool yang tidak memiliki setelan sendiri yang ditentukan di level node pool (seperti registryHosts atau writableCgroups). GKE membuat ulang node di node pool ini untuk menerapkan konfigurasi baru. Node pool dengan setelan tingkat node pool akan terus menggunakan konfigurasi sendiri dan nodenya tidak dibuat ulang. Memperbarui cluster atau node pool dengan konfigurasi containerd akan membuat ulang node untuk menerapkan konfigurasi. Hal ini dapat menyebabkan gangguan sementara dalam menjalankan workload. 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.

Periksa cakupan akses

Jika file konfigurasi Anda menggunakan secret dari Secret Manager, cluster atau node pool Anda harus memiliki cakupan akses cloud-platform. Bagian ini menunjukkan cara memeriksa cakupan akses dan memperbarui cluster yang ada dengan file konfigurasi runtime baru atau yang diubah.

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 Anda menggunakan secret dari Secret Manager dan 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 \
    --format='value[delimiter="\\n"](config.oauthScopes)'

Ganti NODE_POOL_NAME dengan nama node pool.

Jika Anda menggunakan secret dari Secret Manager dan 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.

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"

Memperbarui node pool untuk menggunakan file konfigurasi

Untuk mengupdate konfigurasi containerd pada node pool, jalankan perintah berikut:

gcloud container node-pools update NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=LOCATION \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

Ganti kode berikut:

  • NODE_POOL_NAME: nama node pool yang ingin Anda perbarui.
  • CLUSTER_NAME: nama cluster yang ada.
  • LOCATION: lokasi Compute Engine cluster.
  • PATH_TO_CONFIG_FILE: jalur ke file konfigurasi yang Anda buat, seperti ~/containerd-configuration.yaml.

Membuat ulang node di cluster Standard

Jika cluster Standard Anda tidak menggunakan upgrade otomatis, Anda harus membuat ulang node pool secara manual untuk menerapkan konfigurasi baru. Untuk memicu pembuatan ulang node secara 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 yang sudah digunakan cluster.

Menonaktifkan opsi konfigurasi containerd

Nonaktifkan privateRegistryAccessConfig

  1. Perbarui file konfigurasi Anda untuk menentukan enabled: false di privateRegistryAccessConfig dan hapus kolom lain dalam item, seperti dalam 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.

Nonaktifkan registryHosts

  1. Perbarui file konfigurasi Anda untuk menentukan array kosong dalam item registryHosts, seperti dalam contoh berikut:

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