Mengurutkan peluncuran upgrade cluster dengan tahap kustom

Autopilot Standard

Rollout sequencing with custom stages

• Urutan Peluncuran dengan tahapan kustom (Pratinjau)
• Pengurutan Peluncuran (GA)

Pratinjau

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Dokumen ini menunjukkan cara mengelola upgrade cluster Google Kubernetes Engine (GKE) yang menggunakan urutan peluncuran dengan tahap kustom. Anda membuat urutan peluncuran dengan menggunakan grup cluster yang diatur ke dalam fleet dan, secara opsional, subset cluster dari fleet tersebut. Anda dapat memilih durasi pengujian perendaman yang diinginkan setelah upgrade cluster selesai dalam sebuah grup (maksimum 30 hari). Anda dapat menyertakan cluster Autopilot dan Standard. Untuk mengetahui informasi selengkapnya tentang cara kerja fitur ini, lihat Tentang pengurutan peluncuran dengan tahap kustom.

Jika Anda mengelola peluncuran di beberapa armada, sebaiknya gunakan project khusus untuk menghosting objek RolloutSequence Anda. Project ini bertindak sebagai induk dan koordinator untuk peluncuran di seluruh urutan. Project ini biasanya bukan bagian dari urutan; artinya, project tidak berisi fleet atau cluster yang merupakan bagian dari urutan.

Sebelum memulai

• Instal Google Cloud CLI. Setelah penginstalan, inisialisasi Google Cloud CLI dengan menjalankan perintah berikut:

  gcloud init

  Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

  Catatan: Jika Anda telah menginstal gcloud CLI sebelumnya, pastikan Anda memiliki versi terbaru dengan menjalankan gcloud components update.
• Pastikan Anda sudah memiliki cluster Autopilot atau Standard. Untuk membuat cluster baru, lihat Membuat cluster Autopilot.

• (Opsional) Jika Anda belum memiliki project Google Cloud khusus untuk menghosting konfigurasiRolloutSequence, buat project menggunakan konsol Google Cloud atau metode lain.

• Pastikan Anda telah mengaktifkan API yang diperlukan untuk fleet. API ini harus diaktifkan di project host fleet Anda untuk membuat jenis urutan peluncuran apa pun. Untuk project host urutan peluncuran Anda, aktifkan gkehub.googleapis.com API.

Peran yang diperlukan

Untuk membuat project, Anda memerlukan peran Project Creator (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.

Untuk membuat atau mengubah urutan peluncuran, Anda harus memiliki peran IAM Fleet Editor (roles/gkehub.editor) di setiap project host fleet dalam urutan peluncuran dan project host urutan peluncuran Anda. Peran ini memberikan izin berikut:

• gkehub.rolloutsequences.create
• gkehub.rolloutsequences.get
• gkehub.rolloutsequences.list
• gkehub.rolloutsequences.update
• gkehub.rolloutsequences.delete
• gkehub.fleet.get

Izin ini memungkinkan Anda membuat, mengakses, dan mengubah objek RolloutSequence, serta menggunakan armada dalam urutan peluncuran.

Jika perlu mendaftarkan atau membatalkan pendaftaran cluster ke fleet, Anda memerlukan semua izin berikut:

• Izin pendaftaran cluster di project host fleet Anda.
• Izin admin cluster untuk cluster GKE apa pun yang akan didaftarkan.
• Izin pendaftaran cluster lintas project untuk cluster GKE apa pun yang akan didaftarkan ke fleet di project berbeda.

Untuk mengetahui informasi selengkapnya tentang peran IAM dengan hak istimewa terendah yang diperlukan untuk berbagai tugas, lihat Mendapatkan saran peran bawaan dengan bantuan Gemini.

Mengonfigurasi urutan peluncuran

Untuk membuat urutan peluncuran, cluster harus diatur ke dalam grup fleet. Anda juga dapat membuat tahap terperinci yang dapat menargetkan subset cluster tertentu dalam armada menggunakan label Kubernetes. Untuk mendapatkan panduan tentang cara mengatur cluster, lihat contoh bank komunitas. Setelah mengatur cluster ke dalam grup dan secara opsional memberi label, Anda membuat urutan peluncuran dengan menentukan daftar berurutan tahap dan waktu perendaman untuk setiap grup.

Mengatur cluster ke dalam fleet

Dalam urutan peluncuran, sebaiknya daftarkan semua cluster di saluran rilis yang sama. Jika cluster tidak terdaftar di saluran yang sama, GKE akan memilih versi dari saluran yang paling konservatif dalam urutan. Misalnya, jika cluster terdaftar di saluran Stabil dan Reguler, GKE akan memilih versi dari saluran Stabil. Sebaiknya semua cluster menjalankan versi minor yang sama agar memenuhi syarat untuk versi target upgrade otomatis yang sama.

Jika cluster telah diatur ke dalam fleet, Anda dapat melewati langkah-langkah berikut dan melanjutkan ke bagian Membuat subset cluster.

1. Kelompokkan cluster Anda ke dalam fleet. Anda dapat mengatur cluster berdasarkan lingkungan deployment, seperti Pengujian, Staging, dan Produksi (direkomendasikan).
2. Daftarkan setiap cluster ke fleet berdasarkan pengelompokan yang Anda pilih.

Membuat subset cluster (opsional)

Untuk membuat tahap dalam urutan peluncuran menargetkan cluster tertentu, Anda harus memberi label pada cluster tersebut.

Misalnya, untuk menguji versi baru pada sebagian kecil cluster sebelum peluncuran penuh, Anda dapat menerapkan label canary ke cluster tersebut. Untuk menambahkan label canary dengan nilai true ke cluster menggunakan Google Cloud CLI, jalankan perintah berikut:

gcloud container clusters update CLUSTER_NAME \
    --location=CLUSTER_LOCATION\
    --update-labels=canary=true

Ganti kode berikut:

• CLUSTER_NAME: nama cluster yang ada.
• CLUSTER_LOCATION: region atau zona Compute Engine cluster.

Flag --update-labels=canary=true menginstruksikan GKE untuk menerapkan label canary ke cluster .

Peringatan: Memperbarui label pada cluster akan menimpa label yang ada di cluster. Jika cluster memiliki label yang ingin dipertahankan, Anda harus menyertakan label tersebut bersama dengan label baru yang ingin ditambahkan saat memperbarui cluster.

Untuk mengetahui informasi selengkapnya tentang cara menambahkan label ke cluster, lihat Menambahkan atau memperbarui label untuk cluster yang ada.

Membuat urutan peluncuran dengan tahap kustom

Urutan peluncuran menentukan urutan upgrade menggunakan tahap. Untuk membuat urutan peluncuran, Anda harus membuat file YAML yang menentukan tahap, lalu membuat RolloutSequence.

Untuk memastikan bahwa urutan mencakup semua cluster, setiap fleet harus menyertakan tahap umum (tahap tanpa pemilih label). Tahap mencakup semua ini mencakup semua cluster yang tersisa yang tidak dipilih GKE pada tahap sebelumnya. Jika Anda menetapkan satu cluster ke beberapa tahap dalam satu RolloutSequence, untuk menyelesaikan konflik, GKE secara implisit menetapkan cluster hanya ke tahap paling awal.

Penting: Dalam file konfigurasi YAML, waktu perendaman harus dinyatakan dalam detik .

Contoh konfigurasi berikut membuat tiga tahap:

• Tahap pertama menargetkan semua cluster di fleet dev. Setelah upgrade selesai, ada waktu perendaman selama 7 hari (nilai 604800 detik).
• Tahap kedua menargetkan cluster di fleet prod yang memiliki label canary=true. Setelah upgrade selesai, ada waktu perendaman selama 7 hari.
• Tahap ketiga menargetkan cluster yang tersisa di fleet prod. Setelah upgrade selesai, ada waktu perendaman selama 7 hari.

1. Simpan manifes berikut sebagai rollout-sequence.yaml:

   - stage:
     fleet-projects:
     - projects/dev
     soak-duration: 604800s
   - stage:
     fleet-projects:
     - projects/prod
     soak-duration: 604800s
     label-selector: resource.labels.canary=='true'
   - stage:
     fleet-projects:
     - projects/prod
     soak-duration: 604800s
   

   Perhatikan hal berikut:

   • stage: mencakup fleet atau subset cluster dalam fleet. Cluster pada tahap sebelumnya harus diupgrade dan diuji sepenuhnya sebelum urutan dilanjutkan ke tahap berikutnya. Namun, jika cluster belum selesai diupgrade 30 hari setelah proses upgrade dimulai, GKE akan memulai periode berendam.
   • fleet-projects: daftar fleet tempat memilih cluster untuk tahap ini. Maksimal satu armada dapat dirujuk per tahap. Fleet diidentifikasi berdasarkan project tempat fleet dihosting. Project ini dapat berupa project yang berbeda dari project tempat cluster berada, jika fleet berisi keanggotaan lintas project. Format untuk menentukan project fleet adalah projects/PROJECT_ID.
   • label-selector (opsional): memilih subset cluster dari fleet yang ditentukan. Kolom ini menggunakan sintaksis Common Expression Language (CEL) dan harus dimulai dengan resource.labels.
   • soak-duration: waktu tunggu setelah mengupgrade semua cluster di tahap sebelumnya sebelum melanjutkan ke tahap berikutnya. Dinyatakan dalam detik.

2. Untuk membuat urutan peluncuran yang Anda tentukan dalam manifes rollout-sequence.yaml, jalankan perintah berikut:

   gcloud beta container fleet rolloutsequences create ROLLOUT_SEQUENCE_NAME \
       --display-name=DISPLAY_NAME \
       --stage-config=rollout-sequence.yaml
   

   Ganti kode berikut:

   • ROLLOUT_SEQUENCE_NAME: ID tetap yang sesuai dengan spesifikasi RFC-1034, misalnya, test-rollout-sequence.
   • DISPLAY_NAME: string yang dapat dibaca manusia untuk urutan peluncuran Anda.

Memeriksa status peluncuran

Setelah Anda mengonfigurasi urutan peluncuran, sistem akan otomatis membuat objek Rollout untuk mengelola upgrade. Anda dapat mengamati dan melacak progres objek ini menggunakan perintah Google Cloud CLI.

Mencantumkan peluncuran

Untuk mencantumkan semua peluncuran aktif dan historis di project host urutan peluncuran, jalankan perintah berikut:

gcloud beta container fleet rollouts list --project=HOST_PROJECT_ID

Ganti HOST_PROJECT_ID dengan ID project host urutan peluncuran Anda.

Anda dapat menghilangkan flag --project=HOST_PROJECT_ID jika sudah berada di project tempat urutan peluncuran dihosting.

Outputnya mirip dengan hal berikut ini:

NAME                                              STATE      CREATE_TIME
05eb251e4f19269e23-node-1-33-5-gke-1201000-t7mqd  COMPLETED  2025-10-30T20:07:46
05eb251e4f19269e23-kcp-1-33-5-gke-1201000-djwst   COMPLETED  2025-10-30T18:07:06
05eb251e4f19269e23-node-1-33-5-gke-1125000-6bxvu  COMPLETED  2025-10-23T17:46:54
05eb251e4f19269e23-kcp-1-33-5-gke-1125000-2f6ct   RUNNING    2025-10-23T16:41:33

Dalam output sebelumnya, nama peluncuran yang berisi kcp merujuk pada upgrade bidang kontrol, dan nama yang berisi node merujuk pada upgrade node. Segmen nama peluncuran setelah kcp atau node berasal dari versi GKE.

Menjelaskan peluncuran

Untuk mendapatkan informasi mendetail tentang peluncuran tertentu, termasuk versi target, status, dan cluster mana yang telah diupgrade, gunakan perintah describe dengan ID peluncuran yang Anda peroleh dari perintah sebelumnya:

gcloud beta container fleet rollouts describe ROLLOUT_ID \
  --project=HOST_PROJECT_ID

Ganti kode berikut:

• ROLLOUT_ID: ID peluncuran yang Anda peroleh saat mencantumkan peluncuran.
• HOST_PROJECT_ID: project ID tempat urutan peluncuran Anda dihosting.

Contoh:

gcloud beta container fleet rollouts describe 927e9a989930cf3b55-kcp-1-32-4-gke-1106006 \
  --project=my-hostfleet

Outputnya mirip dengan hal berikut ini:

createTime: '2025-05-26T11:47:29.909959672Z'
membershipStates:
  projects/dev-project-id/locations/us-central1/memberships/c-1:
    lastUpdateTime: '2025-05-26T12:20:55.601542481Z'
    targets:
    - cluster:   projects/dev-project-id/locations/us-central1/clusters/c-1
      operation: //container.googleapis.com/v1/projects/dev-project-id/locations/us-central1/operations/operation-1234567890-abcdefg-hijklm-nopqrst
      state: SUCCEEDED
    stageAssignment: 1
  projects/dev-project-id/locations/us-central1/memberships/c-2:
    lastUpdateTime: '2025-05-26T12:22:57.151203493Z'
    targets:
    - cluster:   projects/dev-project-id/locations/us-central1/clusters/c-2
      operation: //container.googleapis.com/v1/projects/dev-project-id/locations/us-central1/operations/operation-987654321-ghijkl-mno-pqr-stu-vwxyz
      state: SUCCEEDED
    stageAssignment: 1
  projects/prod-project-id/locations/us-central1/memberships/c-1:
    lastUpdateTime: '2025-05-26T13:03:34.134308942Z'
    targets:
    - cluster: projects/prod-project-id/locations/us-central1/clusters/c-1
      operation: //container.googleapis.com/v1/projects/prod-project-id/locations/us-central1/operations/operation-567891234-efghij-klm-nopq-rstu-vwxyz
      state: SUCCEEDED
    stageAssignment: 2
  projects/prod-project-id/locations/us-central1/memberships/c-2:
    lastUpdateTime: '2025-05-26T13:06:34.025261641Z'
    targets:
    - cluster: projects/prod-project-id/locations/us-central1/clusters/c-1
      operation: //container.googleapis.com/v1/projects/prod-project-id/locations/us-central1/operations/operation-765432198-01a7b896-67c2-523-6fjjh4-icmdydh
      state: SUCCEEDED
    stageAssignment: 2
name: projects/user-hostfleet/locations/global/rollouts/05eb251e4f19269e23-kcp-1-32-4-gke-1106006
rolloutSequence: projects/project-id/locations/global/rolloutSequences/my-sequence
state: COMPLETED
updateTime: '2025-07-22T07:36:51.052691989Z'
versionUpgrade:
  desiredVersion: 1.32.4-gke.1106006
  type: TYPE_CONTROL_PLANE
stages:
- state: COMPLETED
  endTime: '2025-05-26T12:22:28.828506491Z'
  stageNumber: 1
  startTime: '2025-05-26T11:48:28.772658427Z'
  soakDuration: 600s
- state: COMPLETED
  endTime: '2025-05-26T13:06:20.026390832Z'
  stageNumber: 2
  startTime: '2025-05-26T12:32:38.419372153Z'
  soakDuration: 600s

Informasi status untuk peluncuran

Saat Anda menjelaskan peluncuran, kolom stages dan membershipStates dari output memberikan status progres setiap tahap dan cluster dalam tahap tersebut, masing-masing.

Tabel berikut mencantumkan kemungkinan status tahap:

Status	Deskripsi
PENDING	Upgrade belum dimulai untuk tahap ini.
RUNNING	Upgrade sedang berlangsung untuk tahap ini. Jika Anda telah mengonfigurasi masa pemeliharaan untuk cluster di tahap tersebut, GKE akan menunggu hingga masa pemeliharaan dimulai sebelum mengupgrade cluster.
SOAKING	Semua cluster dalam tahap ini telah menyelesaikan upgrade, dan tahap ini berada dalam periode berdiam yang dikonfigurasi.
FORCED_SOAKING	Upgrade memerlukan waktu lebih lama daripada waktu upgrade maksimum (30 hari), dan oleh karena itu GKE memulai fase berdiam secara paksa. Upgrade masih dilanjutkan di cluster yang tersisa.
COMPLETED	Tahap perendaman telah selesai, dan peluncuran dilanjutkan ke tahap berikutnya.

Tabel berikut mencantumkan kemungkinan status cluster dalam urutan:

Status	Deskripsi
PENDING	Upgrade tertunda di cluster ini.
INELIGIBLE	Cluster ini tidak memenuhi syarat untuk upgrade, mungkin karena perbedaan versi. Alasan tidak memenuhi syarat diberikan dalam output.
RUNNING	Upgrade sedang berlangsung di cluster ini.
SUCCEEDED	Upgrade telah berhasil diselesaikan di cluster ini.
FAILED	Upgrade telah gagal di cluster ini. Target yang gagal akan dicoba lagi tanpa batas waktu selama tahapnya aktif (dalam status RUNNING atau FORCED_SOAKING).

Mengelola urutan peluncuran

Anda dapat mengontrol upgrade cluster otomatis dengan urutan peluncuran dalam beberapa cara, seperti yang dijelaskan di bagian berikut.

Mencantumkan urutan peluncuran Anda

Untuk mencantumkan semua urutan peluncuran di project host Anda, jalankan perintah berikut:

gcloud beta container fleet rolloutsequences list --project=HOST_PROJECT_ID

Ganti HOST_PROJECT_ID dengan ID project host urutan peluncuran Anda.

Mendeskripsikan urutan peluncuran

Untuk melihat detail urutan peluncuran tertentu, jalankan perintah berikut:

gcloud beta container fleet rolloutsequences describe ROLLOUT_SEQUENCE_NAME \
  --project=HOST_PROJECT_ID

Ganti kode berikut:

• ROLLOUT_SEQUENCE_NAME: nama urutan peluncuran.
• HOST_PROJECT_ID: ID project host urutan peluncuran Anda.

Outputnya mirip dengan hal berikut ini:

createTime: '2025-10-23T16:40:16.403871189Z'
displayName: my-display-name
name: projects/HOST_PROJECT_ID/locations/global/rolloutSequences/ROLLOUT_SEQUENCE_NAME
stages:
- clusterSelector:
    labelSelector: resource.labels.canary=='true'
  fleetProjects:
  - projects/FLEET_PROJECT_ID
  soakDuration: 600s
- fleetProjects:
  - projects/FLEET_PROJECT_ID
  soakDuration: 300s
uid: 5c5b2ac8-9d76-45f9-92ca-5e6bd3fbcaef
updateTime: '2025-10-23T17:11:57.285678399Z'

Mengubah urutan peluncuran

Anda dapat mengubah urutan peluncuran yang ada dengan mengedit file konfigurasi YAML tempat Anda menentukan urutan. Misalnya, Anda dapat memperbarui waktu berdiam untuk tahap atau memperbarui tahap untuk mengubah urutan upgrade. Setelah mengedit file, terapkan perubahan.

Misalnya, jika Anda menentukan urutan peluncuran asli dalam file bernama rollout-sequence.yaml, edit file sesuai kebutuhan. Kemudian, jalankan perintah berikut:

gcloud beta container fleet rolloutsequences update test-rollout-sequence \
  --display-name="My Updated Rollout Sequence" \
  --stage-config=rollout-sequence.yaml

Perhatian: Jika Anda mengubah urutan peluncuran yang ada dengan cara yang memengaruhi cluster yang berpartisipasi, misalnya, mengubah urutan tahap, GKE akan segera membatalkan semua peluncuran yang ada. Jika Anda hanya mengubah waktu perendaman tahap, GKE tidak akan membatalkan peluncuran.

Menghapus urutan peluncuran

Untuk menghapus urutan peluncuran, jalankan perintah berikut:

gcloud beta container fleet rolloutsequences delete ROLLOUT_SEQUENCE_NAME \
  --project=HOST_PROJECT_ID

Ganti kode berikut:

• ROLLOUT_SEQUENCE_NAME dengan nama urutan peluncuran.
• HOST_PROJECT_ID dengan ID project host urutan peluncuran Anda.

Jika Anda menghapus urutan peluncuran, semua peluncuran yang sedang berlangsung untuk urutan tersebut akan dibatalkan. Cluster yang merupakan bagian dari urutan akan kembali ke perilaku upgrade otomatis default untuk saluran rilis yang terdaftar.

Memigrasikan urutan peluncuran yang ada untuk menggunakan tahap kustom

Jika menggunakan versi peluncuran berbasis armada yang tersedia secara umum untuk pengurutan peluncuran, Anda dapat bermigrasi ke urutan yang menggunakan tahap kustom dengan membuat RolloutSequence baru yang mereferensikan armada yang ada.

Sebelum memigrasikan urutan, sebaiknya buat salinan konfigurasi urutan peluncuran saat ini.

Untuk memigrasikan urutan peluncuran, selesaikan langkah-langkah berikut:

1. Buat project Google Cloud khusus untuk menghosting urutan peluncuran Anda. Proyek ini biasanya tidak menjadi bagian dari urutan; artinya, proyek tidak berisi fleet atau cluster yang merupakan bagian dari urutan.
2. Jika Anda ingin urutan peluncuran menyertakan cluster tertentu dalam fleet, tambahkan label ke cluster tersebut. Langkah ini opsional.

3. Ikuti petunjuk di Membuat urutan peluncuran dengan tahap kustom.

   Misalnya, manifes berikut, yang bernama rollout-sequence-migrate.yaml, mereferensikan fleet yang ada dalam urutan peluncuran sebelumnya. Manifes ini menjelaskan tiga tahap, termasuk tahap canary di fleet prod:

   - stage:
     fleet-projects:
     - projects/dev
     soak-duration: 604800s
   - stage:
     fleet-projects:
     - projects/prod
     soak-duration: 604800s
     label-selector: canary=true
   - stage:
     fleet-projects:
     - projects/prod
     soak-duration: 604800s
   

Segera setelah Anda menentukan RolloutSequence baru untuk fleet, GKE akan mulai mengupgrade fleet sesuai urutan baru, dan menghapus konfigurasi sebelumnya.

Memigrasikan urutan peluncuran dengan tahap kustom ke urutan peluncuran sebelumnya

Bagian ini menjelaskan cara mengembalikan urutan peluncuran dengan tahap kustom ke model urutan berbasis fleet yang tersedia secara umum. Proses ini melibatkan penghapusan RolloutSequence baru dan memulihkan konfigurasi berbasis fleet asli Anda.

Mencegah upgrade yang tidak berurutan selama migrasi

Untuk menghindari upgrade yang tidak diinginkan atau tidak berurutan saat Anda mengonfigurasi ulang urutan, terapkan pengecualian pemeliharaan ke cluster produksi Anda. Langkah ini akan menjeda sementara semua upgrade otomatis di cluster tersebut. Misalnya, Anda dapat mengonfigurasi pengecualian pemeliharaan jenis no upgrades di cluster produksi.

Menghapus urutan peluncuran

Hapus objek RolloutSequence yang mengelola cluster Anda. Penghapusan ini menonaktifkan fitur tahap kustom.

Untuk menghapus RolloutSequence, jalankan perintah berikut:

gcloud beta container fleet rolloutsequences delete ROLLOUT_SEQUENCE_NAME

Ganti ROLLOUT_SEQUENCE_NAME dengan nama urutan peluncuran Anda.

Memulihkan konfigurasi urutan peluncuran sebelumnya (tanpa tahap kustom)

Setelah menghapus RolloutSequence, Anda dapat memulihkan konfigurasi berbasis fleet asli. Proses ini melibatkan pembuatan ulang fitur clusterupgrade dengan parameter aslinya, termasuk link upstreamFleet dan waktu perendaman untuk setiap armada dalam urutan Anda. Untuk mengetahui informasi selengkapnya, lihat Membuat urutan peluncuran.

Menghapus pengecualian pemeliharaan

Setelah memulihkan konfigurasi pengurutan peluncuran berbasis armada asli, hapus pengecualian pemeliharaan yang Anda terapkan pada langkah pertama di bagian ini. GKE melanjutkan upgrade otomatis, yang kini diatur oleh urutan berbasis fleet yang dipulihkan.

Langkah Berikutnya

• Pelajari lebih lanjut upgrade cluster dengan urutan peluncuran.