Mengupgrade cluster

Mengupgrade workstation admin, cluster pengguna, dan cluster admin untuk Google Distributed Cloud (khusus software) untuk VMware memungkinkan Anda mengadopsi rilis Kubernetes, patch keamanan, dan fitur platform yang didukung. Dokumen ini akan memandu Anda mengupgrade bidang kontrol dan node pool cluster pengguna secara bersamaan; untuk mengupgradenya secara terpisah, lihat Mengupgrade node pool.

Sebelum memulai, tinjau Ringkasan upgrade untuk pemilihan alat dan urutan upgrade, Aturan versi upgrade untuk penyimpangan versi dan persyaratan OS khusus rilis, serta Praktik terbaik upgrade untuk checklist pra-upgrade.

Sebelum memulai

  • Pastikan Anda memiliki cadangan cluster admin dan pengguna saat ini sebelum memulai upgrade. Untuk mengetahui informasi selengkapnya, lihat Mencadangkan cluster pengguna dan admin.

  • Diagnosis cluster Anda sebelum mengupgrade. Jalankan gkectl diagnose cluster untuk memastikan cluster admin Anda responsif, dan selesaikan masalah apa pun sebelum memulai upgrade.

  • Pastikan gkectl dan cluster Anda adalah versi yang sesuai untuk upgrade, dan Anda telah mendownload paket yang sesuai. Penyimpangan versi antara cluster admin dan pengguna bergantung pada versi Google Distributed Cloud. Untuk memastikan Anda dapat mengupgrade cluster admin, lihat aturan versi untuk versi Anda.

  • Pastikan kolom bundlepath di file konfigurasi cluster admin cocok dengan jalur paket yang ingin Anda upgrade.

    Jika Anda membuat perubahan lain pada kolom dalam file konfigurasi cluster admin, perubahan ini akan diabaikan selama upgrade. Agar perubahan tersebut diterapkan, Anda harus mengupgrade cluster terlebih dahulu, lalu menjalankan perintah update cluster dengan perubahan file konfigurasi untuk membuat perubahan lain pada cluster.

Meninjau aturan firewall Anda

Di versi 1.29 dan yang lebih baru, pemeriksaan preflight sisi server diaktifkan secara default. Pemeriksaan preflight sisi server memerlukan aturan firewall tambahan. Di Aturan firewall untuk cluster admin, telusuri "Pemeriksaan preflight" dan pastikan semua aturan firewall yang diperlukan telah dikonfigurasi.

Dengan pemeriksaan preflight sisi server, saat Anda mengupgrade cluster pengguna menggunakan gkectl, pemeriksaan preflight akan dijalankan di cluster admin, bukan secara lokal di workstation admin. Pemeriksaan preflight sisi server juga dijalankan di cluster admin saat Anda menggunakan konsol Google Cloud , Google Cloud CLI, atau Terraform untuk mengupgrade cluster.

Saat Anda mengupgrade cluster admin, Google Distributed Cloud akan men-deploy cluster Kubernetes di Docker (kind) untuk menghosting sementara pengontrol Kubernetes yang diperlukan untuk mengupgrade cluster admin. Cluster sementara ini disebut cluster bootstrap. Pemeriksaan preflight sisi server dijalankan di cluster bootstrap saat Anda mengupgrade cluster admin.

Aktifkan stackdriver

Jika Anda membuat cluster pengguna menggunakan gkectl, sebelum mengupgrade, pastikan bagian stackdriver dalam file konfigurasi cluster pengguna Anda telah diisi, yang mengaktifkan stackdriver (diperlukan untuk logging dan pemantauan). Jika stackdriver tidak diaktifkan, isi bagian stackdriver dalam file konfigurasi cluster pengguna, dan update cluster sebelum Anda melakukan upgrade.

Jika Anda membuat cluster menggunakan Terraform, konsol Google Cloud , atau gcloud CLI, stackdriver akan otomatis diaktifkan.

Mengaktifkan Dataplane V2

Dataplane V2 harus diaktifkan di semua cluster pengguna mulai versi 1.31. Sebelum mengupgrade cluster pengguna ke 1.31, lakukan langkah-langkah berikut. Jika Anda memiliki kekhawatiran tentang penghapusan sementara spesifikasi NetworkPolicy, hubungi Dukungan Google.

Tetapkan enableDataplaneV2 ke true dalam file konfigurasi cluster pengguna Anda.

Jika cluster Anda menggunakan NetworkPolicy, hapus spesifikasinya untuk sementara dari cluster, sebagai berikut:

  1. Periksa apakah ada NetworkPolicy non-sistem yang diterapkan ke cluster Anda:

    kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    get networkpolicy -A -o wide \
    --field-selector metadata.namespace!=kube-system

    Ganti USER_CLUSTER_KUBECONFIG dengan jalur file kubeconfig untuk cluster pengguna.

    Jika hanya ada kebijakan kube-system default, perintah akan menampilkan No resources found.

  2. Jika perintah sebelumnya mencantumkan objek NetworkPolicy, simpan setiap spesifikasi NetworkPolicy ke file agar Anda dapat menerapkan kembali spesifikasi tersebut setelah mengupgrade cluster:

    kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get networkpolicy NETWORK_POLICY_NAME -n NETWORK_POLICY_NAMESPACE -o yaml > NETWORK_POLICY_NAME.yaml

    Ganti kode berikut:

    • NETWORK_POLICY_NAME: nama NetworkPolicy yang Anda simpan.
    • NETWORK_POLICY_NAMESPACE: namespace NetworkPolicy.

  3. Hapus NetworkPolicy, menggunakan perintah berikut:

    kubectl --kubeconfig USER_CLUSTER_KUBECONFIG delete networkpolicy NETWORK_POLICY_NAME -n NETWORK_POLICY_NAMESPACE

  4. Lanjutkan upgrade.

  5. Setelah upgrade selesai, jika Anda menghapus spesifikasi NetworkPolicy non-sistem, terapkan kembali dengan perintah ini:

    kubectl --kubeconfig USER_CLUSTER_KUBECONFIG apply -f NETWORK_POLICY_NAME.yaml

Persyaratan Google API dan IAM

Untuk mengupgrade cluster ke versi 1.28 dan yang lebih baru, Anda harus mengaktifkan kubernetesmetadata.googleapis.com dan memberikan peran IAM kubernetesmetadata.publisher ke akun layanan logging-monitoring. Perubahan ini diperlukan untuk menggunakan Cloud Monitoring.

  1. Aktifkan kubernetesmetadata.googleapis.com:

    gcloud services enable --project PROJECT_ID  \
    kubernetesmetadata.googleapis.com

    Ganti PROJECT_ID dengan ID project host fleet tempat cluster pengguna menjadi anggota. Ini adalah project yang Anda tentukan saat cluster dibuat. Jika Anda membuat cluster menggunakan gkectl, ini adalah project ID di kolom gkeConnect.projectID dalam file konfigurasi cluster.

  2. Jika organisasi Anda telah menyiapkan daftar yang diizinkan yang memungkinkan traffic dari Google API dan alamat lain melewati server proxy Anda, tambahkan kubernetesmetadata.googleapis.com ke daftar yang diizinkan.

  3. Berikan peran kubernetesmetadata.publisher ke akun layanan logging-monitoring:

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member "serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role "roles/kubernetesmetadata.publisher"

    Ganti SERVICE_ACCOUNT_EMAIL dengan alamat email akun layanan logging-monitoring Anda.

Fitur lama diblokir saat upgrade

Fitur lama berikut diblokir selama upgrade cluster ke versi 1.32:

  • Dataplane V1 (Calico)
  • Konfigurasi load balancer F5 Big IP terintegrasi
  • Cluster admin non-HA
  • Cluster pengguna Kubeception
  • Load balancer Seesaw

Anda harus memigrasikan cluster ke fitur yang direkomendasikan sebelum mengupgrade ke versi 1.32.

Persyaratan IAM untuk mengupgrade cluster pengguna

Lewati bagian ini jika Anda berencana menggunakan gkectl untuk upgrade cluster pengguna.

Jika Anda ingin menggunakan konsol Google Cloud , Google Cloud CLI, atau Terraform untuk mengupgrade cluster pengguna, dan Anda bukan Project Owner, Anda harus diberi peran Identity and Access Management roles/gkeonprem.admin pada project Google Cloud tempat cluster dibuat. Untuk mengetahui detail tentang izin yang disertakan dalam peran ini, lihat Peran GKE on-prem dalam dokumentasi IAM.

Untuk menggunakan konsol guna mengupgrade cluster, minimal Anda juga memerlukan hal berikut:

  • roles/container.viewer. Peran ini memungkinkan pengguna melihat halaman Cluster GKE dan resource container lainnya di konsol. Untuk mengetahui detail tentang izin yang disertakan dalam peran ini, atau untuk memberikan peran dengan izin baca/tulis, lihat peran Kubernetes Engine dalam dokumentasi IAM.

  • roles/gkehub.viewer. Peran ini memungkinkan pengguna melihat cluster di konsol. Untuk mengetahui detail tentang izin yang disertakan dalam peran ini, atau untuk memberikan peran dengan izin baca/tulis,lihat peran GKE Hub dalam dokumentasi IAM.

Batasan pada cluster lanjutan

Perhatikan batasan berikut jika Anda telah mengaktifkan cluster lanjutan:

  • Saat mengupgrade cluster dari versi 1.32 ke 1.33, Anda harus menggunakan gkectl. Klien GKE On-Prem API (konsol, gcloud CLI, dan Terraform) tidak didukung untuk jalur upgrade khusus ini, tetapi didukung untuk upgrade mulai dari versi 1.33.

  • Untuk cluster lanjutan di versi 1.31 Pratinjau, atau saat mengonversi cluster admin non-lanjutan menjadi cluster admin lanjutan, Anda harus menjalankan upgrade sinkron. Di versi 1.32 dan yang lebih baru, Anda dapat menggunakan flag --async dengan perintah gkectl upgrade admin dan gkectl upgrade cluster untuk cluster lanjutan yang ada.

Membuat perubahan konfigurasi sebelum atau setelah upgrade

Jika Anda perlu membuat perubahan konfigurasi pada cluster, lakukan update cluster sebelum atau setelah upgrade. Satu-satunya perubahan pada konfigurasi cluster untuk upgrade adalah versi. Bergantung pada versi dan jenis cluster, perubahan konfigurasi lainnya akan diabaikan secara otomatis atau menyebabkan kegagalan upgrade. Untuk mengetahui informasi selengkapnya, lihat Menghapus perubahan yang tidak didukung untuk mengizinkan upgrade.

Memeriksa versi yang tersedia untuk upgrade cluster

Jalankan perintah berikut untuk melihat versi yang tersedia untuk diupgrade:

gkectl version --kubeconfig ADMIN_CLUSTER_KUBECONFIG

Ganti ADMIN_CLUSTER_KUBECONFIG dengan jalur ke file kubeconfig cluster admin.

Output akan menampilkan versi saat ini dan versi yang tersedia untuk diupgrade.

Jika Anda berencana menggunakan konsol, gcloud CLI, atau Terraform untuk upgrade, diperlukan waktu sekitar 7 hingga 14 hari setelah rilis agar versi tersebut tersedia di GKE On-Prem API di semua region Google Cloud . Konsol hanya mencantumkan versi yang tersedia untuk upgrade cluster pengguna. Langkah-langkah untuk mengupgrade cluster pengguna menggunakan gcloud CLI atau Terraform mencakup langkah untuk menjalankan gcloud container vmware clusters query-version-config guna mendapatkan versi yang tersedia untuk upgrade.

Mengupgrade workstation admin

Cara mengupgrade workstation admin bergantung pada cara Anda membuatnya: gkeadm atau dikelola pengguna.

gkeadm

Menemukan file yang diperlukan

Sebelum membuat workstation admin, Anda mengisi file konfigurasi workstation admin yang dibuat oleh gkeadm create config. Nama default untuk file ini adalah admin-ws-config.yaml.

Selain itu, workstation Anda memiliki file informasi. Nama default file ini sama dengan nama workstation admin Anda.

Temukan file konfigurasi workstation admin dan file informasi Anda. Anda memerlukannya untuk melakukan langkah-langkah upgrade. Jika file ini berada di direktori saat ini dan memiliki nama default, Anda tidak perlu menentukannya saat menjalankan perintah upgrade. Jika file ini berada di direktori lain, atau jika Anda telah mengubah nama file, tentukan file tersebut menggunakan flag --config dan --info-file.

Jika file informasi output tidak ada, Anda dapat membuatnya kembali. Lihat Membuat ulang file informasi jika tidak ada.

Upgrade

Upgrade workstation admin:

  1. Periksa kolom adminWorkstation.diskGB di file konfigurasi workstation admin dan pastikan ukuran yang ditentukan minimal 100, misalnya:

    adminWorkstation:
  diskGB: 100

    Saat mengupgrade ke versi 1.28 dan yang lebih tinggi, diperlukan 100 GB, dan upgrade cluster akan gagal jika workstation admin tidak memiliki kapasitas disk yang cukup.

  2. Dari server jump, download gkeadm:

    gkeadm upgrade gkeadm --target-version TARGET_VERSION

    Ganti TARGET_VERSION dengan versi yang akan digunakan setelah upgrade. Anda harus menentukan nomor versi lengkap dalam bentuk X.Y.Z-gke.N. Untuk mengetahui daftar versi Google Distributed Cloud, lihat Pembuatan versi.

  3. Upgrade workstation admin Anda:

    gkeadm upgrade admin-workstation --config AW_CONFIG_FILE \
  --info-file INFO_FILE

Ganti kode berikut:

  • AW_CONFIG_FILE: jalur file konfigurasi workstation admin Anda. Anda dapat menghilangkan flag ini jika file berada di direktori saat ini dan memiliki nama admin-ws-config.yaml.

  • INFO_FILE: jalur file informasi Anda. Anda dapat menghilangkan flag ini jika file berada di direktori Anda saat ini. Nama default file ini sama dengan nama workstation admin Anda.

Dikelola pengguna

Di workstation admin, buka direktori tempat Anda ingin menginstal versi baru gkectl.

  1. Download gkectl:

     gcloud storage cp gs://gke-on-prem-release/gkectl/TARGET_VERSION/gkectl ./
 chmod +x gkectl

    Ganti TARGET_VERSION dengan versi yang akan diupgrade. Anda harus menentukan nomor versi lengkap dalam bentuk X.Y.Z-gke.N. Untuk mengetahui daftar versi Google Distributed Cloud, lihat Pembuatan versi.

  2. Download paket Google Distributed Cloud. Pastikan versinya cocok dengan versi yang Anda gunakan untuk mendownload gkectl:

     gcloud storage cp gs://gke-on-prem-release/gke-onprem-bundle/TARGET_VERSION/gke-onprem-vsphere-TARGET_VERSION.tgz ./

Mengupgrade cluster admin

Langkah-langkah untuk mengupgrade cluster admin sedikit berbeda, bergantung pada versi minor yang Anda upgrade (versi target):

1.31 dan yang lebih baru

Jika versi target adalah 1.31 atau yang lebih tinggi, sebelum mengupgrade cluster pengguna ke versi minor berikutnya, Anda perlu mengupgrade cluster admin. Di versi 1.31 dan yang lebih tinggi, versi cluster admin, termasuk versi patch, harus lebih besar dari atau sama dengan versi cluster pengguna. Misalnya, jika cluster admin menggunakan versi 1.31.1, versi tertinggi yang dapat diupgrade untuk cluster pengguna adalah 1.31.1.

Jalankan perintah berikut di workstation admin Anda untuk mengimpor image OS ke vSphere:

gkectl prepare \
    --bundle-path /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz \
    --kubeconfig ADMIN_CLUSTER_KUBECONFIG

Ganti ADMIN_CLUSTER_KUBECONFIG dengan jalur ke file kubeconfig cluster admin.

1.30 dan yang lebih lama

Jika versi target adalah 1.30 atau yang lebih rendah, Anda harus mengupgrade semua cluster pengguna sebelum mengupgrade cluster admin. Versi minor cluster admin harus kurang dari atau sama dengan versi minor cluster pengguna. Versi patch tidak menjadi masalah. Misalnya, jika cluster pengguna berada di versi 1.30.1, cluster admin dapat diupgrade ke versi patch yang lebih tinggi, seperti 1.30.3.

Melakukan upgrade

gkectl

Lakukan langkah-langkah di bagian ini di workstation admin Anda. Ada dua variasi perintah gkectl upgrade admin:

  • Asinkron:
    Dengan variasi asinkron, perintah akan memulai upgrade, lalu selesai. Anda tidak perlu mengamati output perintah selama seluruh durasi upgrade. Sebagai gantinya, Anda dapat memeriksa progres upgrade secara berkala dengan menjalankan gkectl list admin dan gkectl describe admin. Untuk menggunakan variasi asinkron, sertakan flag --async dalam perintah.

    Persyaratan untuk upgrade asinkron:

    • Hanya didukung untuk cluster admin dengan ketersediaan tinggi (HA) dengan versi 1.29 atau yang lebih tinggi.
    • Semua cluster pengguna harus mengaktifkan Controlplane V2.
    • Versi 1.31: Tidak didukung di cluster lanjutan.
    • Versi 1.32 dan yang lebih baru: Tersedia di cluster lanjutan.

  • Sinkron:
    Dengan variasi sinkron, perintah gkectl upgrade admin akan menghasilkan pesan status ke workstation admin seiring progres upgrade.

Upgrade asinkron

  1. Di workstation admin, diagnosis cluster sebelum mengupgrade:

    gkectl diagnose cluster \
   --kubeconfig ADMIN_CLUSTER_KUBECONFIG

    Jika perintah melaporkan error atau peringatan, lihat Mendiagnosis masalah cluster dan selesaikan masalah tersebut sebelum melanjutkan.

  2. Mulai upgrade asinkron:

    gkectl upgrade admin \
   --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
   --config ADMIN_CLUSTER_CONFIG_FILE \
   --async

    Ganti kode berikut:

    • ADMIN_CLUSTER_KUBECONFIG: jalur ke file kubeconfig cluster admin.

    • ADMIN_CLUSTER_CONFIG_FILE: jalur ke file konfigurasi cluster admin.

    Perintah sebelumnya selesai, dan Anda dapat terus menggunakan workstation admin saat upgrade sedang berlangsung.

  3. Untuk melihat status upgrade:

    gkectl list admin --kubeconfig ADMIN_CLUSTER_KUBECONFIG

    Output akan menampilkan nilai untuk cluster STATE. Jika cluster masih diupgrade, nilai STATE adalah UPGRADING. Contoh:

    NAME              STATE         AGE    VERSION
gke-admin-test    UPGRADING     9h     1.36.100-gke.144

    Nilai yang mungkin untuk STATE adalah RUNNING, UPGRADING, RECONCILING, ERROR, dan UNKNOWN.

  4. Untuk mendapatkan detail selengkapnya tentang progres upgrade dan peristiwa cluster:

    gkectl describe admin --kubeconfig ADMIN_CLUSTER_KUBECONFIG

    Output akan menampilkan resource kustom OnPremAdminCluster untuk cluster admin yang ditentukan, yang mencakup status dan kondisi cluster.

    Klik untuk melihat contoh output 
    Status:
 Cluster State:  RUNNING
 Conditions:
   Last Transition Time:    2026-08-10T20:22:58Z
   Message:                 Operator NodePool is ready
   Observed Generation:     2
   Reason:                  OperatorNodePoolReady
   Status:                  True
   Type:                    ControlPlaneReady
   Last Transition Time:    2026-08-10T20:22:59Z
   Message:                 Cluster is running
   Observed Generation:     2
   Reason:                  ClusterRunning
   Status:                  True
   Type:                    Ready
   Last Transition Time:    2026-08-10T20:23:00Z
   Message:
   Observed Generation:     2
   Reason:                  Reconciling
   Status:                  False
   Type:                    OperatorClusterKubeProxyCleanedUp
   Last Transition Time:    2026-08-10T20:22:58Z
   Message:
   Observed Generation:     2
   Reason:                  PreflightCheckPassed
   Status:                  True
   Type:                    OperatorClusterPreflightCheckSuccessful
   Last Transition Time:    2026-08-10T15:56:50Z
   Message:
   Observed Generation:     2
   Reason:                  ProvisioningStarted
   Status:                  True
   Type:                    OperatorClusterProvisioningStarted
   Last Transition Time:    2026-08-10T15:56:50Z
   Message:
   Observed Generation:     2
   Reason:                  RemoteTrackerSetupComplete
   Status:                  True
   Type:                    OperatorClusterRemoteTrackerSetupSuccessful
   Last Transition Time:    2026-08-10T15:56:50Z
   Message:
   Observed Generation:     2
   Reason:                  Reconciling
   Status:                  False
   Type:                    OperatorClusterStalled
   Last Transition Time:    2026-08-10T15:56:50Z
   Message:
   Observed Generation:     2
   Reason:                  NotPresent
   Status:                  False
   Type:                    OperatorClusterWaitingOnPendingClusterID
   Last Transition Time:    2026-08-10T20:22:59Z
   Message:                 Operator Cluster is ready
   Observed Generation:     2
   Reason:                  OperatorClusterReady
   Status:                  True
   Type:                    OperatorClusterReady
   Last Transition Time:    2026-08-10T15:56:50Z
   Message:                 Component provisioner job is completed
   Observed Generation:     2
   Reason:                  ComponentProvisionerJobCompleted
   Status:                  True
   Type:                    ComponentProvisionerSystemProfileInstalled
   Last Transition Time:    2026-08-10T15:58:20Z
   Message:                 Component provisioner job is completed
   Observed Generation:     2
   Reason:                  ComponentProvisionerJobCompleted
   Status:                  True
   Type:                    ComponentProvisionerAdminProfileInstalled
 Gke On Prem Version:       1.36.0-gke.527
 Last Gke On Prem Version:  1.35.300-gke.87
 Management Conditions:
   Last Transition Time:  2026-08-10T15:58:20Z
   Message:               Component provisioner job is completed
   Observed Generation:   2
   Reason:                ComponentProvisionerJobCompleted
   Status:                True
   Type:                  ManagementProfilesReady
   Last Transition Time:  2026-08-10T15:56:29Z
   Message:               Component provisioner job is completed
   Observed Generation:   2
   Reason:                ComponentProvisionerJobCompleted
   Status:                True
   Type:                  ComponentProvisionerSystemManagementProfileInstalled
   Last Transition Time:  2026-08-10T15:58:20Z
   Message:               Component provisioner job is completed
   Observed Generation:   2
   Reason:                ComponentProvisionerJobCompleted
   Status:                True
   Type:                  ComponentProvisionerManagementProfileInstalled
 Operator Cluster Status:
   Control Plane Node Pool Status:
     Anthos Bare Metal Version:  1.36.0-gke.527
     Anthos Bare Metal Versions:
       1.36.0-gke.527:  3
     Conditions:
       Last Transition Time:  2026-08-10T20:18:20Z
       Observed Generation:   11
       Reason:                PreflightCheckPassed
       Status:                True
       Type:                  PreflightCheckSuccessful
       Last Transition Time:  2026-08-10T20:22:58Z
       Observed Generation:   11
       Reason:                NodepoolReady
       Status:                True
       Type:                  Ready
       Last Transition Time:  2026-08-10T20:22:22Z
       Observed Generation:   11
       Reason:                ReconciliationCompleted
       Status:                False
       Type:                  Reconciling
     Gke Versions:
       v1.36.0-gke.2800:        3
     Last Reconciliation Time:  2026-08-10T20:25:07Z
     Maintenance Nodes:         0
     Managed Fields:
       Label Keys:
         kubernetes.googleapis.com/cluster-name
         node.kubernetes.io/control-plane
         node.kubernetes.io/master
       Node Label Keys:
         vsphere://abcdef-1:
           onprem.gke.io/failure-domain-name
           vmware.cluster.gke.io/machine-name
         vsphere://abcdef-2:
           onprem.gke.io/failure-domain-name
           vmware.cluster.gke.io/machine-name
         vsphere://abcdef-3:
           onprem.gke.io/failure-domain-name
           vmware.cluster.gke.io/machine-name
       Taints:
         Effect:         PreferNoSchedule
         Key:            node-role.kubernetes.io/control-plane
     Ready Nodes:        3
     Ready Timestamp:    2026-08-10T15:54:01Z
     Reconciling Nodes:  0
     Stalled Nodes:      0
     Unknown Nodes:      0
   Data Plane Load Balancer Status:
     Conditions:
       Last Transition Time:  2026-08-10T15:39:16Z
       Observed Generation:   1
       Reason:                ReconciliationCompleted
       Status:                False
       Type:                  Reconciling
     Node Pool Location:      control-plane-nodepool
   External Manifests Conditions:
     Last Transition Time:  2026-08-10T15:56:32Z
     Observed Generation:   2
     Reason:                ReconciliationCompleted
     Status:                False
     Type:                  Reconciling
   Gke Connect Conditions:
     Last Transition Time:  2026-08-10T20:13:39Z
     Observed Generation:   2
     Reason:                AnthosBareMetalVersion
     Status:                True
     Type:                  1.36.0-gke.527
     Last Transition Time:  2026-08-10T20:13:39Z
     Observed Generation:   2
     Reason:                ReconciliationCompleted
     Status:                False
     Type:                  Reconciling
   Gke Connect Dependent System Service Conditions:
     Last Transition Time:  2026-08-10T15:56:32Z
     Observed Generation:   2
     Reason:                ReconciliationCompleted
     Status:                False
     Type:                  Reconciling
   Gke Hub Registration Status:
     Membership:
       Description:  description
       Name:         name
   Gke Versions:
     v1.36.0-gke.2800:  3
   Kernel Version Conditions:
     Last Transition Time:  2026-08-10T15:39:23Z
     Reason:                kernelVersionCheckPassed
     Status:                True
     Type:                  kernelVersionCheckSuccessful
   System Service Conditions:
     Last Transition Time:  2026-08-10T20:12:26Z
     Observed Generation:   2
     Reason:                ReconciliationCompleted
     Status:                False
     Type:                  Reconciling

  5. Setelah upgrade selesai, gkectl list admin akan menampilkan STATE RUNNING:

    NAME              STATE         AGE    VERSION
gke-admin-test    RUNNING       9h     1.36.100-gke.144

    Selain itu, setelah upgrade selesai, gkectl describe admin akan menampilkan kolom Last GKE On Prem Version di bagian Status. Contoh:

    Status:
  Cluster State:  RUNNING
  Last GKE On Prem Version:  1.36.0-gke.1

Memecahkan masalah upgrade asinkron

Untuk upgrade asinkron, durasi waktu tunggu didasarkan pada jumlah node dalam cluster. Jika upgrade memerlukan waktu lebih lama daripada durasi waktu tunggu, status cluster akan diubah dari UPGRADING menjadi ERROR, dengan peristiwa yang menyatakan bahwa waktu tunggu operasi upgrade habis. Perhatikan bahwa status ERROR di sini berarti upgrade memerlukan waktu lebih lama dari yang diperkirakan, tetapi belum dihentikan. Pengontrol melanjutkan rekonsiliasi dan terus mencoba kembali operasi. Jika upgrade diblokir atau gagal, Anda dapat menjalankan gkectl diagnose untuk memeriksa masalah umum cluster. Berdasarkan hasilnya, Anda dapat memutuskan apakah akan melakukan perbaikan manual atau menghubungi DukunganGoogle Cloud untuk mendapatkan bantuan lebih lanjut.

Upgrade sinkron

  1. Di workstation admin, diagnosis cluster sebelum mengupgrade:

    gkectl diagnose cluster \
   --kubeconfig ADMIN_CLUSTER_KUBECONFIG

    Jika perintah melaporkan error atau peringatan, lihat Mendiagnosis masalah cluster dan selesaikan masalah tersebut sebelum melanjutkan.

  2. Upgrade cluster admin:

    gkectl upgrade admin \
   --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
   --config ADMIN_CLUSTER_CONFIG_FILE

    Ganti kode berikut:

    • ADMIN_CLUSTER_KUBECONFIG: jalur ke file kubeconfig cluster admin.

    • ADMIN_CLUSTER_CONFIG_FILE: jalur ke file konfigurasi cluster admin.

    Perintah gkectl upgrade menjalankan pemeriksaan preflight. Jika pemeriksaan preflight gagal, perintah akan diblokir. Anda harus memperbaiki kegagalan atau menggunakan flag --skip-preflight-check-blocking dengan perintah untuk membatalkan pemblokirannya.

  3. Jika Anda mengupgrade ke versi 1.14.0 atau yang lebih tinggi, file kubeconfig baru akan dibuat untuk cluster admin yang menimpa file yang ada. Untuk melihat detail cluster dalam file, jalankan perintah berikut:

    kubectl config view --kubeconfig ADMIN_CLUSTER_KUBECONFIG

gcloud CLI

Upgrade cluster admin menggunakan gcloud CLI.

  1. Update versi platform ke versi target:

    gcloud container vmware admin-clusters update ADMIN_CLUSTER_NAME \
    --location=REGION \
    --required-platform-version=VERSION \
    --async

    Ganti kode berikut:

    • ADMIN_CLUSTER_NAME: nama cluster admin Anda.
    • REGION: region Google Cloud tempat cluster admin dikelola.
    • VERSION: versi target yang akan diupgrade.

    Perintah ini menampilkan ID operasi. Anda dapat memantau progresnya menggunakan gcloud container vmware operations describe.

  2. Setelah Anda menyelesaikan update versi platform, update versi cluster admin:

    gcloud container vmware admin-clusters update ADMIN_CLUSTER_NAME \
    --location=REGION \
    --version=VERSION \
    --async

    Langkah ini menyelesaikan upgrade cluster admin ke versi target.

Mengupgrade cluster pengguna

Anda dapat menggunakan gkectl, konsol, gcloud CLI, atau Terraform untuk mengupgrade cluster pengguna. Untuk mengetahui informasi tentang cara memutuskan alat yang akan digunakan, lihat Memilih alat untuk mengupgrade cluster.

Konsol

Mengupgrade cluster pengguna memerlukan beberapa perubahan pada cluster admin. Konsol akan otomatis melakukan hal berikut:

  • Mendaftarkan cluster admin di GKE On-Prem API jika belum terdaftar.

  • Mendownload dan men-deploy paket komponen ke cluster admin. Versi komponen cocok dengan versi yang Anda tentukan untuk upgrade. Komponen ini memungkinkan cluster admin mengelola cluster pengguna pada versi tersebut.

Untuk mengupgrade cluster pengguna:

  1. Di konsol, buka halaman ringkasan cluster Google Kubernetes Engine.

    Buka cluster GKE

  2. Pilih project Google Cloud , lalu pilih cluster yang ingin Anda upgrade.

  3. Di panel Detail, klik Detail selengkapnya.

  4. Di bagian Cluster basics, klik Upgrade.

  5. Dalam daftar Choose target version, pilih versi yang ingin Anda upgrade. Daftar pilihan hanya berisi rilis patch terbaru.

  6. Klik Upgrade.

Sebelum cluster diupgrade, pemeriksaan preflight dijalankan untuk memvalidasi status cluster dan kondisi node. Jika pemeriksaan preflight lulus, cluster pengguna akan diupgrade. Perlu waktu sekitar 30 menit untuk menyelesaikan upgrade.

Untuk melihat status upgrade, klik Show Details di tab Cluster Details.

gcloud CLI

Mengupgrade cluster pengguna memerlukan beberapa perubahan pada cluster admin. Perintah gcloud container vmware clusters upgrade akan otomatis melakukan hal berikut:

  • Mendaftarkan cluster admin di GKE On-Prem API jika belum terdaftar.

  • Mendownload dan men-deploy paket komponen ke cluster admin. Versi komponen cocok dengan versi yang Anda tentukan untuk upgrade. Komponen ini memungkinkan cluster admin mengelola cluster pengguna pada versi tersebut.

Untuk mengupgrade cluster pengguna:

  1. Update komponen Google Cloud CLI:

    gcloud components update

  2. Dapatkan daftar versi yang tersedia untuk diupgrade:

    gcloud container vmware clusters query-version-config \
  --cluster=USER_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION

    Output perintah ini akan mirip dengan berikut ini:

    versions:
- version: 1.16.3-gke.45
- version: 1.16.2-gke.28
- version: 1.16.1-gke.45
- version: 1.16.0-gke.669
- version: 1.15.6-gke.25
- version: 1.15.5-gke.41

An Anthos version must be made available on the admin cluster ahead of the user
cluster creation or upgrade. Versions annotated with isInstalled=true are
installed on the admin cluster for the purpose of user cluster creation or
upgrade whereas other version are released and will be available for upgrade
once dependencies are resolved.

To install the version in the admin cluster, run:
$ gcloud container vmware admin-clusters update my-admin-cluster --required-platform-version=VERSION

    Anda dapat mengabaikan pesan setelah daftar versi. Tidak masalah apakah versi yang Anda upgrade diinstal di cluster admin. Perintah upgrade mendownload dan men-deploy paket komponen yang cocok dengan versi yang Anda tentukan dalam perintah upgrade.

  3. Mengupgrade cluster.

    gcloud container vmware clusters upgrade USER_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --version=VERSION

    Ganti VERSION dengan versi Google Distributed Cloud yang ingin Anda upgrade. Tentukan versi dari output perintah sebelumnya. Sebaiknya upgrade ke versi patch terbaru.

    Output dari perintah ini mirip dengan berikut ini:

    Waiting for operation [projects/example-project-12345/locations/us-west1/operations/operation-1679543737105-5f7893fd5bae9-942b3f97-75e59179] to complete.

    Dalam contoh output, string operation-1679543737105-5f7893fd5bae9-942b3f97-75e59179 adalah OPERATION_ID dari operasi yang berjalan lama. Anda dapat mengetahui status operasi dengan menjalankan perintah berikut di jendela terminal lain:

    gcloud container vmware operations describe OPERATION_ID \
  --project=PROJECT_ID \
  --location=REGION

gkectl

Bersiap untuk mengupgrade cluster pengguna

Lakukan langkah-langkah berikut di workstation admin Anda:

  1. Periksa apakah cluster pengguna responsif sebelum Anda memulai upaya upgrade awal. Lihat Mendiagnosis masalah cluster. Jalankan gkectl diagnose cluster di cluster pengguna dan selesaikan masalah apa pun.

  2. Lakukan langkah ini hanya jika TARGET_VERSION adalah 1.30 atau yang lebih rendah, atau jika Anda mengupgrade cluster pengguna ke versi yang berbeda dari cluster admin. Jalankan gkectl prepare untuk mengimpor image OS ke vSphere:

    gkectl prepare \
  --bundle-path /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz \
  --kubeconfig ADMIN_CLUSTER_KUBECONFIG

  3. Jika cluster Anda memiliki node pool Windows, jalankan gkectl prepare windows, dan perbarui kolom osImage untuk node pool. Untuk petunjuk mendetail, lihat Mengupgrade cluster pengguna dengan node pool Windows.

  4. Dalam file konfigurasi cluster pengguna, tetapkan gkeOnPremVersion ke versi target upgrade Anda.

Menjalankan pemeriksaan preflight

Saat mengupgrade ke versi 1.29 dan yang lebih tinggi, Anda dapat menjalankan pemeriksaan preflight sebelum mengupgrade cluster pengguna:

gkectl upgrade cluster \
    --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    --config USER_CLUSTER_CONFIG \
    --dry-run

Ganti USER_CLUSTER_CONFIG dengan jalur ke file konfigurasi cluster pengguna.

Dengan flag --dry-run, gkectl upgrade cluster akan menjalankan pemeriksaan preflight, tetapi tidak memulai proses upgrade. Meskipun versi Google Distributed Cloud yang lebih lama menjalankan pemeriksaan preflight, versi tersebut tidak dapat dijalankan secara terpisah dari upgrade. Dengan menambahkan flag --dry-run, Anda dapat menemukan dan memperbaiki masalah apa pun yang ditemukan oleh pemeriksaan preflight pada cluster pengguna sebelum upgrade.

Jalankan gkectl upgrade cluster

Ada dua variasi perintah gkectl upgrade cluster:

  • Asinkron: (direkomendasikan)
    Dengan variasi asinkron, perintah akan memulai upgrade, lalu selesai. Anda tidak perlu mengamati output perintah selama seluruh durasi upgrade. Sebagai gantinya, Anda dapat memeriksa progres upgrade secara berkala dengan menjalankan gkectl list clusters dan gkectl describe clusters. Untuk menggunakan variasi asinkron, sertakan flag --async dalam perintah.

    • Versi 1.31: Tidak tersedia di cluster lanjutan.
    • Versi 1.32 dan yang lebih baru: Tersedia di cluster lanjutan.

  • Sinkron:
    Dengan variasi sinkron, perintah gkectl upgrade cluster akan menghasilkan pesan status ke workstation admin seiring progres upgrade.

Upgrade asinkron

  1. Lewati langkah ini jika Anda mengupgrade ke versi yang lebih baru dari 1.16.

    Jika Anda menggunakan kredensial yang disiapkan dan registry pribadi untuk cluster pengguna, pastikan kredensial registry pribadi disiapkan sebelum mengupgrade cluster pengguna. Untuk mengetahui informasi tentang cara menyiapkan kredensial registry pribadi, lihat Mengonfigurasi kredensial yang disiapkan untuk cluster pengguna.

  2. Diagnosis cluster Anda untuk memastikan cluster tersebut responsif:

    gkectl diagnose cluster \
    --kubeconfig <var>ADMIN_CLUSTER_KUBECONFIG</var>

    Jika perintah melaporkan error atau peringatan, lihat Mendiagnosis masalah cluster dan selesaikan masalah tersebut sebelum melanjutkan.

  3. Di workstation admin, mulai upgrade asinkron:

    gkectl upgrade cluster \
  --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
  --config USER_CLUSTER_CONFIG \
  --async

    Perintah sebelumnya selesai, dan Anda dapat terus menggunakan workstation admin saat upgrade sedang berlangsung.

  4. Untuk melihat status upgrade:

    gkectl list clusters --kubeconfig ADMIN_CLUSTER_KUBECONFIG

    Output akan menampilkan nilai untuk cluster STATE. Jika cluster masih diupgrade, nilai STATE adalah UPGRADING. Contoh:

    NAMESPACE             NAME    READY   STATE       AGE   VERSION
my-uc-gkeonprem-mgmt  my-uc   False   UPGRADING   9h    1.36.0-gke.1

    Nilai yang mungkin untuk STATE adalah UPGRADING, DELETING, UPDATING, RUNNING, RECONCILING, ERROR, dan UNKNOWN.

  5. Untuk mendapatkan detail selengkapnya tentang progres upgrade dan peristiwa cluster:

    gkectl describe clusters --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
  --cluster USER_CLUSTER_NAME -v 5

    Output menampilkan resource kustom OnPremUserCluster untuk cluster pengguna yang ditentukan, yang mencakup status, kondisi, dan peristiwa cluster.

    Klik untuk melihat contoh output 
    Status:
Cluster State:  RUNNING
Conditions:
Last Transition Time:    2026-08-10T21:29:07Z
Message:                 Cluster is running
Observed Generation:     2
Reason:                  ClusterRunning
Status:                  True
Type:                    Ready
Last Transition Time:    2026-08-10T21:12:05Z
Message:                 Operator NodePool is ready
Observed Generation:     2
Reason:                  OperatorNodePoolReady
Status:                  True
Type:                    ControlPlaneReady
Last Transition Time:    2026-08-10T16:25:08Z
Message:                 Component provisioner job is completed
Observed Generation:     2
Reason:                  ComponentProvisionerJobCompleted
Status:                  True
Type:                    ComponentProvisionerUserProfileInstalled
Last Transition Time:    2026-08-10T21:29:07Z
Message:                 Node pools are running
Observed Generation:     2
Reason:                  NodePoolsRunning
Status:                  True
Type:                    NodePoolsReady
Last Transition Time:    2026-08-10T21:29:56Z
Message:
Observed Generation:     2
Reason:                  Reconciling
Status:                  False
Type:                    OperatorClusterKubeProxyCleanedUp
Last Transition Time:    2026-08-10T16:27:48Z
Message:
Observed Generation:     2
Reason:                  PreflightCheckPassed
Status:                  True
Type:                    OperatorClusterPreflightCheckSuccessful
Last Transition Time:    2026-08-10T16:27:48Z
Message:
Observed Generation:     2
Reason:                  ProvisioningStarted
Status:                  True
Type:                    OperatorClusterProvisioningStarted
Last Transition Time:    2026-08-10T16:27:48Z
Message:
Observed Generation:     2
Reason:                  RemoteTrackerSetupComplete
Status:                  True
Type:                    OperatorClusterRemoteTrackerSetupSuccessful
Last Transition Time:    2026-08-10T16:27:48Z
Message:
Observed Generation:     2
Reason:                  Reconciling
Status:                  False
Type:                    OperatorClusterStalled
Last Transition Time:    2026-08-10T16:27:48Z
Message:
Observed Generation:     2
Reason:                  NotPresent
Status:                  False
Type:                    OperatorClusterWaitingOnPendingClusterID
Last Transition Time:    2026-08-10T18:23:16Z
Message:                 Operator Cluster is ready
Observed Generation:     2
Reason:                  OperatorClusterReady
Status:                  True
Type:                    OperatorClusterReady
Gke On Prem Version:       1.36.0-gke.527
Last Gke On Prem Version:  1.35.300-gke.87
Operator Cluster Status:
Control Plane Node Pool Status:
  Anthos Bare Metal Version:  1.36.0-gke.527
  Anthos Bare Metal Versions:
    1.36.0-gke.527:  3
  Conditions:
    Last Transition Time:  2026-08-10T21:07:22Z
    Observed Generation:   11
    Reason:                PreflightCheckPassed
    Status:                True
    Type:                  PreflightCheckSuccessful
    Last Transition Time:  2026-08-10T21:12:05Z
    Observed Generation:   11
    Reason:                NodepoolReady
    Status:                True
    Type:                  Ready
    Last Transition Time:  2026-08-10T21:11:24Z
    Observed Generation:   11
    Reason:                ReconciliationCompleted
    Status:                False
    Type:                  Reconciling
  Gke Versions:
    v1.36.0-gke.2800:        3
  Last Reconciliation Time:  2026-08-10T21:28:02Z
  Maintenance Nodes:         0
  Managed Fields:
    Label Keys:
      node.kubernetes.io/control-plane
      node.kubernetes.io/master
    Node Label Keys:
      vsphere://abcdef-1:
        onprem.gke.io/failure-domain-name
        vmware.cluster.gke.io/machine-name
      vsphere://abcdef-2:
        onprem.gke.io/failure-domain-name
        vmware.cluster.gke.io/machine-name
      vsphere://abcdef-3:
        onprem.gke.io/failure-domain-name
        vmware.cluster.gke.io/machine-name
  Ready Nodes:        3
  Ready Timestamp:    2026-08-10T16:24:02Z
  Reconciling Nodes:  0
  Stalled Nodes:      0
  Unknown Nodes:      0
Data Plane Load Balancer Status:
  Conditions:
    Last Transition Time:  2026-08-10T16:08:47Z
    Observed Generation:   1
    Reason:                ReconciliationCompleted
    Status:                False
    Type:                  Reconciling
  Node Pool Location:      load-balancer-nodepool
External Manifests Conditions:
  Last Transition Time:  2026-08-10T16:12:25Z
  Observed Generation:   2
  Reason:                ReconciliationCompleted
  Status:                False
  Type:                  Reconciling
Gke Connect Conditions:
  Last Transition Time:  2026-08-10T21:11:33Z
  Observed Generation:   2
  Reason:                AnthosBareMetalVersion
  Status:                True
  Type:                  1.36.0-gke.527
  Last Transition Time:  2026-08-10T21:11:33Z
  Observed Generation:   2
  Reason:                ReconciliationCompleted
  Status:                False
  Type:                  Reconciling
Gke Connect Dependent System Service Conditions:
  Last Transition Time:  2026-08-10T16:25:26Z
  Observed Generation:   2
  Reason:                ReconciliationCompleted
  Status:                False
  Type:                  Reconciling
Gke Hub Registration Status:
  Membership:
    Description:  description
    Name:         name
Gke Versions:
  v1.36.0-gke.2800:  6
Kernel Version Conditions:
  Last Transition Time:  2026-08-10T16:08:53Z
  Reason:                kernelVersionCheckPassed
  Status:                True
  Type:                  kernelVersionCheckSuccessful
System Service Conditions:
  Last Transition Time:  2026-08-10T21:04:39Z
  Observed Generation:   2
  Reason:                ReconciliationCompleted
  Status:                False
  Type:                  Reconciling
Events:
Type    Reason         Age   From                            Message
    


    


    Normal  StatusChanged  58m   onprem-user-cluster-controller  OnPremUserCluster status changed:
    


      

    • New ClusterState condition: UPGRADING
Normal  ControlPlaneUpgradeStarted  58m  onprem-user-cluster-controller  Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:43:53 +0000 UTC
Normal  StatusChanged               58m  onprem-user-cluster-controller  OnPremUserCluster status changed:
      • 

    • New Ready condition: False, CreateOrUpdateOperatorNodePool, Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:43:53 +0000 UTC
Normal  ControlPlaneUpgradeStarted  58m  onprem-user-cluster-controller  Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:43:54 +0000 UTC
Normal  StatusChanged               58m  onprem-user-cluster-controller  OnPremUserCluster status changed:
      • 

    • New Ready condition: False, CreateOrUpdateOperatorNodePool, Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:43:54 +0000 UTC
Normal  ControlPlaneUpgradeStarted  58m  onprem-user-cluster-controller  Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:44:38 +0000 UTC
Normal  StatusChanged               58m  onprem-user-cluster-controller  OnPremUserCluster status changed:
      • 

    • New Ready condition: False, CreateOrUpdateOperatorNodePool, Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:44:38 +0000 UTC
Normal  StatusChanged  56m  onprem-user-cluster-controller  OnPremUserCluster status changed:
      • 

    • New Ready condition: False, CreateOrUpdateOperatorNodePool, Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:46:33 +0000 UTC
Normal  StatusChanged  54m (x2 over 56m)  onprem-user-cluster-controller  OnPremUserCluster status changed:
      • 

    • New Ready condition: False, CreateOrUpdateOperatorNodePool, Creating or updating operator NodePool: NodePoolClaim is currently in the progress of rolling update: Condition "NodeRecreationUpdateInProgress" ready, reason: "NodeRecreationUpdateInProgress", message: "Cannot further mark old InventoryMachines for recreation due to MinReadyNodesRequired requirement. Current process: There are still old InventoryMachines: [my-uc-cp-99cc4wxzvx8ww829-2 my-uc-cp-99cc4wxzvx8ww829-1]; New ready count (0) does not match desired count (3)"
Normal  StatusChanged  53m  onprem-user-cluster-controller  OnPremUserCluster status changed:
      • 

    • New Ready condition: False, CreateOrUpdateOperatorNodePool, Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" generation 7 hasn't been observed
Normal  StatusChanged  53m  onprem-user-cluster-controller  OnPremUserCluster status changed:
      • 

    • New Ready condition: False, CreateOrUpdateOperatorNodePool, Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:48:58 +0000 UTC
Normal  StatusChanged  30m (x3 over 58m)  onprem-user-cluster-controller  OnPremUserCluster status changed:
      • 

    • New Ready condition: True, ClusterRunning, Cluster is running
Normal  ControlPlaneUpgradeFinished  30m (x3 over 58m)  onprem-user-cluster-controller  Operator NodePool is ready
Normal  StatusChanged                29m (x9 over 47m)  onprem-user-cluster-controller  (combined from similar events): OnPremUserCluster status changed:
      • 

    • New Ready condition: False, CreateOrUpdateNodePools, Creating or updating node pools, unready node pools: [my-uc-gke-onprem-mgmt/my-uc], in deletion node pools: []
Normal  NodePoolsUpgradeStarted  29m  onprem-user-cluster-controller  Creating or updating node pools, unready node pools: [my-uc-gke-onprem-mgmt/my-uc], in deletion node pools: []
Normal  StatusChanged            13m  onprem-user-cluster-controller  OnPremUserCluster status changed:
      • 

    • New GKEOnPremVersion: "1.36.0-gke.527"
      • 

    • New ClusterState condition: RUNNING
      • 

    • New Ready condition: True, ClusterRunning, Cluster is running

  6. Setelah upgrade selesai, gkectl list clusters akan menampilkan STATE RUNNING:

    NAMESPACE             NAME    READY   STATE     AGE     VERSION
my-uc-gkeonprem-mgmt  my-uc   True    RUNNING   9h      1.36.0-gke.1

    Selain itu, setelah upgrade selesai, gkectl describe clusters akan menampilkan kolom Last GKE On Prem Version di bagian Status. Contoh:

    Status:
Cluster State:  RUNNING
Last GKE On Prem Version:  1.36.0-gke.1

Memecahkan masalah upgrade asinkron

Untuk upgrade asinkron, durasi waktu tunggu didasarkan pada jumlah node dalam cluster. Jika upgrade memerlukan waktu lebih lama dari durasi waktu tunggu, status cluster akan diubah dari UPGRADING menjadi ERROR, dengan peristiwa yang menyatakan bahwa waktu tunggu operasi upgrade telah habis. Perhatikan bahwa status ERROR di sini berarti upgrade memerlukan waktu lebih lama dari yang diperkirakan, tetapi belum dihentikan. Pengontrol melanjutkan rekonsiliasi dan terus mencoba kembali operasi.

Biasanya, waktu tunggu habis adalah hasil dari deadlock yang disebabkan oleh PodDisruptionBudget (PDB). Dalam hal ini, Pod tidak dapat dikeluarkan dari node lama, dan node lama tidak dapat dikosongkan. Jika pengeluaran Pod memerlukan waktu lebih dari 10 menit, kami akan menulis peristiwa ke objek OnPremUserCluster. Anda dapat merekam peristiwa dengan menjalankan gkectl describe clusters. Kemudian, Anda dapat menyesuaikan PDB agar node dapat dikosongkan. Setelah itu, upgrade dapat dilanjutkan dan akhirnya selesai.

Contoh peristiwa:

Warning  PodEvictionTooLong  96s (x2 over 4m7s)  onprem-user-cluster-controller
Waiting too long(>10m0.00000003s) for (kube-system/coredns-856d6dbfdf-dl6nz) eviction.

Selain itu, saat upgrade diblokir atau gagal, Anda dapat menjalankan gkectl diagnose untuk memeriksa masalah cluster umum. Berdasarkan hasilnya, Anda dapat memutuskan apakah akan melakukan perbaikan manual atau menghubungi DukunganGoogle Cloud untuk mendapatkan bantuan lebih lanjut.

Upgrade sinkron

Perintah gkectl upgrade menjalankan pemeriksaan preflight. Jika pemeriksaan preflight gagal, perintah akan diblokir. Anda harus memperbaiki kegagalan, atau menggunakan flag --skip-preflight-check-blocking. Anda hanya boleh melewati pemeriksaan preflight jika yakin tidak ada kegagalan kritis.

Lanjutkan dengan langkah-langkah berikut di workstation admin Anda:

  1. Lewati langkah ini jika Anda mengupgrade ke versi yang lebih baru dari 1.16.

    Jika Anda menggunakan kredensial yang disiapkan dan registry pribadi untuk cluster pengguna, pastikan kredensial registry pribadi disiapkan sebelum mengupgrade cluster pengguna. Untuk mengetahui informasi tentang cara menyiapkan kredensial registry pribadi, lihat Mengonfigurasi kredensial yang disiapkan untuk cluster pengguna.

  2. Diagnosis cluster Anda untuk memastikan cluster tersebut responsif:

    gkectl diagnose cluster \
  --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
  --config USER_CLUSTER_CONFIG

    Jika perintah melaporkan error atau peringatan, lihat Mendiagnosis masalah cluster dan selesaikan masalah tersebut sebelum melanjutkan.

  3. Upgrade cluster:

    gkectl upgrade cluster \
  --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
  --config USER_CLUSTER_CONFIG

  4. Jika Anda mengupgrade ke versi 1.14.0 atau yang lebih tinggi, file kubeconfig baru akan dibuat untuk cluster pengguna yang menimpa file yang ada. Untuk melihat detail cluster dalam file, jalankan perintah berikut:

    kubectl config view --kubeconfig USER_CLUSTER_KUBECONFIG

Melanjutkan upgrade

Jika upgrade cluster pengguna terganggu, Anda dapat melanjutkan upgrade cluster pengguna dengan menjalankan perintah upgrade yang sama dengan flag --skip-validation-all:

gkectl upgrade cluster \
    --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    --config USER_CLUSTER_CONFIG \
    --skip-validation-all

Terraform

  1. Update komponen Google Cloud CLI:

    gcloud components update

  2. Jika Anda belum melakukannya, daftarkan cluster admin di GKE On-Prem API. Setelah cluster didaftarkan di GKE On-Prem API, Anda tidak perlu melakukan langkah ini lagi.

  3. Dapatkan daftar versi yang tersedia untuk diupgrade:

    gcloud container vmware clusters query-version-config \
  --cluster=USER_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION

    Ganti kode berikut:

    • USER_CLUSTER_NAME: Nama cluster pengguna.

    • PROJECT_ID: ID project fleet tempat cluster pengguna tersebut menjadi anggota. Ini adalah project yang Anda tentukan saat cluster dibuat. Jika Anda membuat cluster menggunakan gkectl, ini adalah project ID di kolom gkeConnect.projectID dalam file konfigurasi cluster.

    • REGION: Region Google Cloud tempat GKE On-Prem API berjalan dan menyimpan metadatanya. Dalam file main.tf yang Anda gunakan untuk membuat cluster pengguna, region berada di kolom location resource cluster.

    Output perintah ini akan mirip dengan berikut ini:

    versions:
- version: 1.16.3-gke.45
- version: 1.16.2-gke.28
- version: 1.16.1-gke.45
- version: 1.16.0-gke.669
- version: 1.15.6-gke.25
- version: 1.15.5-gke.41

An Anthos version must be made available on the admin cluster ahead of the user
cluster creation or upgrade. Versions annotated with isInstalled=true are
installed on the admin cluster for the purpose of user cluster creation or
upgrade whereas other version are released and will be available for upgrade
once dependencies are resolved.

To install the version in the admin cluster, run:
$ gcloud container vmware admin-clusters update my-admin-cluster --required-platform-version=VERSION

  4. Download komponen versi baru dan deploy di cluster admin:

    gcloud container vmware admin-clusters update ADMIN_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --required-platform-version=VERSION

    Perintah ini mendownload versi komponen yang Anda tentukan di --required-platform-version ke cluster admin, lalu men-deploy komponen tersebut. Komponen ini memungkinkan cluster admin mengelola cluster pengguna pada versi tersebut.

  5. Dalam file main.tf yang Anda gunakan untuk membuat cluster pengguna, ubah on_prem_version di resource cluster ke versi baru.

  6. Lakukan inisialisasi dan buat rencana Terraform:

    terraform init

    Terraform menginstal library yang diperlukan, seperti penyedia Google Cloud.

  7. Tinjau konfigurasi dan buat perubahan jika diperlukan:

    terraform plan

  8. Terapkan Terraform plan untuk membuat cluster pengguna:

    terraform apply

Menghapus paket lengkap

Jika Anda mendownload paket lengkap, dan telah berhasil menjalankan gkectl prepare serta mengupgrade cluster admin dan semua cluster pengguna, Anda harus menghapus paket lengkap untuk menghemat kapasitas disk di workstation admin. Jalankan perintah berikut untuk menghapus paket lengkap:

rm /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION-full.tgz

Melanjutkan upgrade cluster admin

Jika upgrade cluster admin terganggu atau gagal, upgrade dapat dilanjutkan jika checkpoint cluster admin berisi status yang diperlukan untuk memulihkan status sebelum gangguan.

Peringatan: Jangan memperbaiki bidang kontrol admin dengan gkectl repair admin-master setelah upaya upgrade gagal. Melakukan hal ini akan menyebabkan cluster admin memasuki status buruk.

Ikuti langkah-langkah berikut:

  1. Periksa apakah bidang kontrol admin responsif sebelum Anda memulai upaya upgrade awal. Lihat Mendiagnosis masalah cluster. Seperti yang dibahas dalam topik tersebut, jalankan perintah gkectl diagnose cluster untuk cluster admin.

  2. Jika bidang kontrol admin tidak responsif sebelum upaya upgrade awal, perbaiki bidang kontrol admin dengan perintah gkectl repair admin-master.

  3. Saat Anda menjalankan kembali perintah upgrade setelah upgrade terganggu atau gagal, gunakan paket dan versi target yang sama seperti yang Anda lakukan dalam upaya upgrade sebelumnya.

Saat Anda menjalankan kembali perintah upgrade, upgrade yang dilanjutkan akan membuat ulang status cluster admin dari checkpoint dan menjalankan kembali seluruh upgrade. Mulai dari 1.12.0, jika bidang kontrol admin tidak responsif, proses upgrade akan langsung mengupgrade ke versi target tanpa mencoba memulihkan cluster admin di versi sumber sebelum melanjutkan upgrade.

Upgrade akan dilanjutkan dari titik kegagalan atau keluar jika checkpoint cluster admin tersedia. Jika checkpoint tidak tersedia, upgrade akan kembali mengandalkan bidang kontrol admin, sehingga bidang kontrol admin harus responsif agar dapat melanjutkan upgrade. Setelah upgrade berhasil, checkpoint akan dibuat ulang.

Jika gkectl keluar secara tidak terduga selama upgrade cluster admin, cluster kind tidak akan dihapus. Sebelum Anda menjalankan kembali perintah upgrade untuk melanjutkan upgrade, hapus cluster kind:

docker stop gkectl-control-plane && docker rm gkectl-control-plane

Setelah menghapus cluster kind, jalankan kembali perintah upgrade.

Me-roll back workstation admin setelah upgrade

Anda dapat melakukan roll back workstation admin ke versi yang digunakan sebelum upgrade.

Selama upgrade, gkeadm mencatat versi sebelum diupgrade dalam file informasi output. Selama rollback, gkeadm menggunakan versi yang tercantum untuk mendownload file lama.

Untuk melakukan roll back workstation admin ke versi sebelumnya:

gkeadm rollback admin-workstation --config=AW_CONFIG_FILE

Anda dapat menghilangkan --config=AW_CONFIG_FILE jika file konfigurasi workstation admin Anda adalah admin-ws-config.yaml default. Jika tidak, ganti AW_CONFIG_FILE dengan jalur ke file konfigurasi workstation admin.

Perintah rollback melakukan langkah-langkah berikut:

  1. Mendownload versi rollback gkeadm.
  2. Mencadangkan direktori utama workstation admin saat ini.
  3. Membuat workstation admin baru menggunakan versi rollback gkeadm.
  4. Menghapus workstation admin asli.

Menginstal paket dengan versi berbeda untuk upgrade

Jika Anda mengupgrade workstation, paket dengan versi yang sesuai akan diinstal di sana untuk mengupgrade cluster Anda. Jika Anda menginginkan versi yang berbeda, ikuti langkah-langkah berikut untuk menginstal paket untuk TARGET_VERSION, yang merupakan versi yang ingin Anda upgrade.

  1. Untuk memeriksa versi gkectl dan cluster saat ini, jalankan perintah ini. Gunakan flag --details/-d untuk mengetahui informasi yang lebih mendetail.

    gkectl version --kubeconfig ADMIN_CLUSTER_KUBECONFIG --details

    Output tersebut memberikan informasi tentang versi cluster Anda.

  2. Berdasarkan output yang Anda dapatkan, cari masalah berikut, dan perbaiki sesuai kebutuhan.

    • Jika versi cluster admin saat ini lebih rendah dari satu versi minor dari TARGET_VERSION, upgrade semua cluster Anda menjadi satu versi minor lebih rendah dari TARGET_VERSION.

    • Jika versi gkectl lebih rendah dari 1.11, dan Anda ingin mengupgrade ke 1.12.x, Anda harus melakukan beberapa upgrade. Upgrade satu versi minor pada satu waktu, hingga Anda mencapai 1.11.x, lalu lanjutkan dengan petunjuk dalam topik ini.

    • Jika versi gkectl lebih rendah dari TARGET_VERSION, upgrade workstation admin ke TARGET_VERSION.

  3. Setelah Anda menentukan bahwa versi gkectl dan cluster Anda sesuai untuk upgrade, download paketnya.

    Periksa apakah tarball paket sudah ada di workstation admin.

    stat /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz

    Jika paket tidak ada di workstation admin, download paket tersebut. 

    gcloud storage cp gs://gke-on-prem-release/gke-onprem-bundle/TARGET_VERSION/gke-onprem-vsphere-TARGET_VERSION.tgz /var/lib/gke/bundles/

  4. Instal paket.

    gkectl prepare --bundle-path /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz --kubeconfig ADMIN_CLUSTER_KUBECONFIG

    Ganti ADMIN_CLUSTER_KUBECONFIG dengan jalur file kubeconfig Anda. Anda dapat menghilangkan flag ini jika file berada di direktori saat ini dan memiliki nama kubeconfig.

  5. Cantumkan versi cluster yang tersedia, dan pastikan versi target disertakan dalam versi cluster pengguna yang tersedia.

    gkectl version --kubeconfig ADMIN_CLUSTER_KUBECONFIG --details

Sekarang Anda dapat membuat cluster pengguna pada versi target, atau mengupgrade cluster pengguna ke versi target.

Memecahkan masalah proses upgrade

Jika Anda mengalami masalah saat mengikuti proses upgrade yang direkomendasikan, ikuti rekomendasi berikut untuk menyelesaikannya. Saran ini mengasumsikan bahwa Anda telah memulai dengan penyiapan versi 1.11.x, dan melanjutkan proses upgrade yang direkomendasikan.

Lihat juga: Memecahkan masalah pembuatan dan upgrade cluster

Memecahkan masalah upgrade cluster pengguna

Misalnya, Anda menemukan masalah pada versi upgrade saat mengupgrade cluster pengguna. Anda mengetahui dari Dukungan Google bahwa masalah ini akan diperbaiki dalam rilis patch mendatang. Anda dapat melanjutkan sebagai berikut:

  1. Terus gunakan versi saat ini untuk produksi.
  2. Menguji rilis patch di cluster non-produksi saat dirilis.
  3. Upgrade semua cluster pengguna produksi ke versi rilis patch jika Anda sudah yakin.
  4. Upgrade cluster admin ke versi rilis patch.

Memecahkan masalah upgrade cluster admin

Jika Anda mengalami masalah saat mengupgrade cluster admin, Anda harus menghubungi Dukungan Google untuk menyelesaikan masalah terkait cluster admin.

Sementara itu, dengan alur upgrade baru, Anda masih dapat memanfaatkan fitur cluster pengguna baru tanpa diblokir oleh upgrade cluster admin, yang memungkinkan Anda mengurangi frekuensi upgrade cluster admin jika diinginkan. Proses upgrade Anda dapat dilanjutkan sebagai berikut:

  1. Mengupgrade cluster pengguna produksi ke 1.12.x.
  2. Pertahankan cluster admin pada versi sebelumnya dan terus terima patch keamanan.
  3. Uji upgrade cluster admin dari 1.11.x ke 1.12.x di lingkungan pengujian, dan laporkan masalah jika ada;
  4. Jika masalah Anda diselesaikan dengan rilis patch 1.12.x, Anda dapat memilih untuk mengupgrade cluster admin produksi ke rilis patch ini jika diinginkan.

Masalah umum untuk versi terbaru

Masalah umum berikut mungkin memengaruhi upgrade jika Anda mengupgrade dari versi 1.7 atau yang lebih baru.

Lihat juga: Masalah umum

Upgrade workstation admin mungkin gagal jika disk data hampir penuh

Jika Anda mengupgrade workstation admin dengan perintah gkectl upgrade admin-workstation, upgrade mungkin gagal jika disk data hampir penuh, karena sistem mencoba mencadangkan workstation admin saat ini secara lokal saat mengupgrade ke workstation admin baru. Jika Anda tidak dapat mengosongkan ruang yang cukup di disk data, gunakan perintah gkectl upgrade admin-workstation dengan flag tambahan --backup-to-local=false untuk mencegah pembuatan cadangan lokal workstation admin saat ini.

Gangguan untuk workload dengan PodDisruptionBudget

Mengupgrade cluster dapat menyebabkan gangguan atau periode nonaktif untuk workload yang menggunakan PodDisruptionBudgets (PDB).

Node gagal menyelesaikan proses upgrade-nya

Jika Anda memiliki objek PodDisruptionBudget yang dikonfigurasi untuk tidak mengizinkan gangguan tambahan, node mungkin akan gagal untuk mengupgrade ke versi bidang kontrol setelah beberapa percobaan. Untuk mencegah kegagalan ini, sebaiknya tingkatkan skala Deployment atau HorizontalPodAutoscaler agar node dapat dihabiskan sambil tetap mematuhi konfigurasi PodDisruptionBudget.

Cantumkan semua objek PodDisruptionBudget di cluster pengguna yang tidak mengizinkan gangguan apa pun:

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    get poddisruptionbudget --all-namespaces \
    -o jsonpath='{range .items[?(@.status.disruptionsAllowed==0)]}{.metadata.namespace}/{.metadata.name}{"\n"}{end}'

Ganti USER_CLUSTER_KUBECONFIG dengan jalur file kubeconfig untuk cluster pengguna.

PDB kube-system/log-aggregator dan kube-system/prometheus default muncul dalam output dengan disruptionsAllowed: 0 jika tidak memiliki Pod yang cocok dan status.expectedPods adalah 0. Karena PDB ini tidak memblokir pengosongan node, Anda dapat mengabaikannya.

Informasi upgrade tambahan

Tentang aturan VMware DRS yang diaktifkan di versi 1.1.0-gke.6

Mulai versi 1.1.0-gke.6, Google Distributed Cloud otomatis membuat aturan anti-afinitas Distributed Resource Scheduler (DRS) VMware untuk node cluster pengguna Anda, sehingga node tersebut tersebar di setidaknya tiga host fisik di pusat data Anda. Mulai versi 1.1.0-gke.6, fitur ini otomatis diaktifkan untuk cluster baru dan cluster yang sudah ada.

Sebelum melakukan upgrade, pastikan lingkungan vSphere Anda memenuhi kondisi berikut:

  • VMware DRS diaktifkan. VMware DRS memerlukan edisi lisensi vSphere Enterprise Plus. Untuk mempelajari cara mengaktifkan DRS, lihat Mengaktifkan VMware DRS di cluster.

  • Nama pengguna vSphere yang diberikan dalam file konfigurasi kredensial memiliki izin Host.Inventory.EditCluster.

  • Tersedia setidaknya tiga host fisik.

Jika lingkungan vSphere Anda tidak memenuhi kondisi sebelumnya, Anda masih dapat melakukan upgrade, tetapi untuk mengupgrade cluster pengguna dari 1.3.x ke 1.4.x, Anda harus menonaktifkan grup anti-afinitas. Untuk mengetahui informasi selengkapnya, lihat masalah umum ini dalam catatan rilis Google Distributed Cloud.

Tentang periode nonaktif selama upgrade

Resource Deskripsi
Cluster admin

Saat cluster admin nonaktif, bidang kontrol cluster pengguna dan workload di cluster pengguna akan terus berjalan, kecuali jika terpengaruh oleh kegagalan yang menyebabkan periode nonaktif.
Bidang kontrol cluster pengguna

Biasanya, Anda tidak akan mengalami periode nonaktif yang terlihat pada bidang kontrol cluster pengguna. Namun, koneksi yang berjalan lama ke server Kubernetes API mungkin terputus dan perlu dibuat ulang. Dalam kasus tersebut, pemanggil API harus mencoba lagi hingga koneksi berhasil dibuat. Dalam kasus terburuk, periode nonaktif dapat berlangsung hingga satu menit selama upgrade.
Node cluster pengguna

Jika upgrade memerlukan perubahan pada node cluster pengguna, Google Distributed Cloud akan membuat ulang node secara berkelanjutan, dan menjadwalkan ulang Pod yang berjalan di node ini. Anda dapat mencegah dampak pada workload dengan mengonfigurasi PodDisruptionBudgets dan aturan anti-afinitas yang sesuai.

Membuat ulang file informasi jika tidak ada

Jika file informasi output untuk workstation admin Anda tidak ada, Anda harus membuat ulang file ini agar dapat melanjutkan upgrade. File ini dibuat saat Anda pertama kali membuat workstation, dan jika Anda telah melakukan upgrade, file tersebut akan diperbarui dengan informasi baru.

File informasi output memiliki format berikut:

Admin workstation version: GKEADM_VERSION
Created using gkeadm version: GKEADM_VERSION
VM name: ADMIN_WS_NAME
IP: ADMIN_WS_IP
SSH key used: FULL_PATH_TO_ADMIN_WS_SSH_KEY
To access your admin workstation:
ssh -i FULL-PATH-TO-ADMIN-WS-SSH-KEY ubuntu@ADMIN-WS-IP

Berikut adalah contoh file informasi output:

Admin workstation version: v1.10.3-gke.49
Created using gkeadm version: v1.10.3-gke.49
VM name: admin-ws-janedoe
IP: 172.16.91.21
SSH key used: /home/janedoe/.ssh/gke-admin-workstation
Upgraded from (rollback version): v1.10.0-gke.194
To access your admin workstation:
ssh -i /home/janedoe/.ssh/gke-admin-workstation ubuntu@172.16.91.21

Buat file di editor, dengan mengganti parameter yang sesuai. Simpan file dengan nama file yang sama dengan nama VM di direktori tempat gkeadm dijalankan. Misalnya, jika nama VM adalah admin-ws-janedoe, simpan file sebagai admin-ws-janedoe.

Langkah berikutnya