升級 Google Distributed Cloud (僅限軟體) for VMware 的管理員工作站、使用者叢集和管理員叢集，即可採用支援的 Kubernetes 版本、安全性修補程式和平台功能。本文將逐步說明如何同時升級使用者叢集的控制層和節點集區。如要分別升級，請參閱「升級節點集區」。
開始之前，請先參閱升級總覽，瞭解工具選擇和升級順序；參閱升級版本規則，瞭解特定版本偏斜和 OS 需求；參閱升級最佳做法，瞭解升級前檢查清單。
事前準備
開始升級前，請確認您已備份管理員和使用者叢集。詳情請參閱「備份使用者和管理員叢集」。
升級前，請先診斷叢集。執行
gkectl diagnose cluster，確保管理員叢集健康狀態良好，並在開始升級前解決所有問題。請確認
gkectl和叢集是適合升級的版本，且您已下載適當的套件。管理員叢集和使用者叢集之間的版本差異，取決於 Google Distributed Cloud 版本。為確保您可以升級管理員叢集，請參閱您版本的版本規則。請確認管理員叢集設定檔中的
bundlepath欄位與要升級的套件路徑相符。如果您對管理員叢集設定檔中的欄位進行任何其他變更，系統會在升級期間忽略這些變更。如要讓這些變更生效，您必須先升級叢集，然後執行 update cluster 指令並變更設定檔，才能對叢集進行其他變更。
查看防火牆規則
在 1.29 以上版本中，伺服器端預檢功能預設為啟用。伺服器端預檢需要額外的防火牆規則。在「管理員叢集的防火牆規則」中，搜尋「預檢檢查」，並確認已設定所有必要的防火牆規則。
使用伺服器端預檢時，當您透過 gkectl 升級使用者叢集，預檢會在管理員叢集上執行，而非在本機的管理員工作站上執行。使用 Google Cloud 控制台、Google Cloud CLI 或 Terraform 升級叢集時，系統也會在管理員叢集上執行伺服器端預檢。
升級管理員叢集時，Google Distributed Cloud 會部署 Kubernetes in Docker (kind) 叢集，暫時託管升級管理員叢集所需的 Kubernetes 控制器。這個暫時叢集稱為「啟動叢集」。升級管理員叢集時，系統會在啟動叢集上執行伺服器端預檢。
啟用 stackdriver
如果您是使用 gkectl 建立使用者叢集，請務必先填寫使用者叢集設定檔中的 stackdriver 區段，再進行升級，以便啟用 stackdriver (記錄和監控功能所需)。如果未啟用 stackdriver，請填寫使用者叢集設定檔中的 stackdriver 部分，並在升級前更新叢集。
如果您是使用 Terraform、 Google Cloud 控制台或 gcloud CLI 建立叢集，系統會自動啟用 stackdriver。
啟用 Dataplane V2
自 1.31 版起，所有使用者叢集都必須啟用 Dataplane V2。將使用者叢集升級至 1.31 版前，請先完成下列步驟。如果您對暫時移除 NetworkPolicy 規格有疑慮，請與 Google 支援團隊聯絡。
在使用者叢集設定檔中，將 enableDataplaneV2 設為 true。
如果叢集使用 NetworkPolicy，請暫時從叢集移除其規格，如下所示：
檢查叢集是否套用了任何非系統
NetworkPolicy：kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \ get networkpolicy -A -o wide \ --field-selector metadata.namespace!=kube-system將
USER_CLUSTER_KUBECONFIG替換為使用者叢集的 kubeconfig 檔案路徑。如果只有預設
kube-system政策，指令會傳回No resources found。如果上述指令列出任何
NetworkPolicy物件，請將每個NetworkPolicy規格儲存至檔案，以便在升級叢集後重新套用規格：kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get networkpolicy NETWORK_POLICY_NAME -n NETWORK_POLICY_NAMESPACE -o yaml > NETWORK_POLICY_NAME.yaml更改下列內容：
NETWORK_POLICY_NAME：要儲存的NetworkPolicy名稱。NETWORK_POLICY_NAMESPACE：NetworkPolicy的命名空間。
使用下列指令刪除
NetworkPolicy：kubectl --kubeconfig USER_CLUSTER_KUBECONFIG delete networkpolicy NETWORK_POLICY_NAME -n NETWORK_POLICY_NAMESPACE繼續升級。
升級完成後，如果您移除了任何非系統
NetworkPolicy規格，請使用下列指令重新套用：kubectl --kubeconfig USER_CLUSTER_KUBECONFIG apply -f NETWORK_POLICY_NAME.yaml
Google API 和 IAM 需求
如要將叢集升級至 1.28 以上版本，您必須啟用 kubernetesmetadata.googleapis.com，並將 kubernetesmetadata.publisher IAM 角色授予記錄/監控服務帳戶。您必須完成這些變更，才能使用 Cloud Monitoring。
啟用
kubernetesmetadata.googleapis.com：gcloud services enable --project PROJECT_ID \ kubernetesmetadata.googleapis.com將
PROJECT_ID替換為使用者叢集所屬機群主專案的 ID。這是您在建立叢集時指定的專案。如果您使用gkectl建立叢集，這就是叢集設定檔中gkeConnect.projectID欄位的專案 ID。如果貴組織已設定許可清單，允許來自 Google API 和其他位址的流量通過 Proxy 伺服器，請將
kubernetesmetadata.googleapis.com新增至許可清單。將
kubernetesmetadata.publisher角色授予記錄/監控服務帳戶：gcloud projects add-iam-policy-binding PROJECT_ID \ --member "serviceAccount:SERVICE_ACCOUNT_EMAIL" \ --role "roles/kubernetesmetadata.publisher"將
SERVICE_ACCOUNT_EMAIL替換為記錄/監控服務帳戶的電子郵件地址。
升級時封鎖舊版功能
叢集升級至 1.32 版期間，系統會封鎖下列舊版功能：
- Dataplane V1 (Calico)
- 整合式 F5 BIG-IP 負載平衡器設定
- 非高可用性管理員叢集
- Kubeception 使用者叢集
- Seesaw 負載平衡器
您必須將叢集遷移至建議功能，才能升級至 1.32 版。
升級使用者叢集的 IAM 需求
如果您打算使用 gkectl 升級使用者叢集，請略過本節。
如要使用 Google Cloud 控制台、Google Cloud CLI 或 Terraform 升級使用者叢集，但您不是專案擁有者，則必須在建立叢集的 Google Cloud 專案中，取得 Identity and Access Management 角色 roles/gkeonprem.admin。如要進一步瞭解這個角色包含的權限，請參閱 IAM 說明文件中的「GKE on-prem 角色」。
如要使用控制台升級叢集，您至少還需要下列權限：
roles/container.viewer。這個角色可讓使用者在控制台中查看 GKE 叢集頁面和其他容器資源。如要進一步瞭解這個角色包含的權限，或授予具備讀取/寫入權限的角色，請參閱 IAM 說明文件中的「Kubernetes Engine 角色」。roles/gkehub.viewer。這個角色可讓使用者在控制台中查看叢集。如要進一步瞭解這個角色包含的權限，或授予具備讀取/寫入權限的角色，請參閱 IAM 說明文件中的「GKE Hub 角色」。
進階叢集的限制
如果啟用進階叢集，請注意下列限制：
將叢集從 1.32 版升級至 1.33 版時，必須使用
gkectl。GKE On-Prem API 用戶端 (控制台、gcloud CLI 和 Terraform) 不支援這個特定升級路徑，但支援從 1.33 版開始的升級。如果是 1.31 預先發布版的進階叢集，或將非進階管理員叢集轉換為進階管理員叢集，則必須執行同步升級。在 1.32 以上版本中，您可以對現有的進階叢集使用
--async旗標，搭配gkectl upgrade admin和gkectl upgrade cluster指令。
在升級前或升級後變更設定
如需變更叢集設定，請在升級前或升級後更新叢集。升級時，叢集設定唯一應變更的是版本。視叢集版本和類型而定，其他設定變更會遭到忽略，或導致升級失敗。詳情請參閱「移除不支援的變更，以便升級」。
查看叢集升級可用的版本
執行下列指令，查看可升級的版本：
gkectl version --kubeconfig ADMIN_CLUSTER_KUBECONFIG
將 ADMIN_CLUSTER_KUBECONFIG 替換為管理員叢集 kubeconfig 檔案的路徑。
輸出內容會顯示目前版本和可升級的版本。
如果您打算使用控制台、gcloud CLI 或 Terraform 進行升級，則在版本發布後，約需 7 到 14 天，才能在所有 Google Cloud 區域的 GKE On-Prem API 中使用該版本。控制台只會列出使用者叢集升級可用的版本。使用 gcloud CLI 或 Terraform 升級使用者叢集時，其中一個步驟是執行 gcloud container vmware clusters query-version-config，取得可用的升級版本。
升級管理員工作站
升級管理員工作站的方式取決於建立方式：gkeadm 或使用者自行管理。
gkeadm
找出所需檔案
建立管理員工作站前，您已填寫 gkeadm create config 產生的管理員工作站設定檔。這個檔案的預設名稱為 admin-ws-config.yaml。
此外，工作站還有一個資訊檔案。這個檔案的預設名稱與管理員工作站的名稱相同。
找出管理員工作站設定檔和資訊檔案。您需要這些資訊才能完成升級步驟。如果這些檔案位於目前的目錄中，且使用預設名稱，則執行升級指令時不需指定這些檔案。如果這些檔案位於其他目錄，或您已變更檔案名稱，請使用 --config 和 --info-file 旗標指定這些檔案。
如果輸出資訊檔案遺失，可以重新建立。請參閱「重新建立缺少的資訊檔案」。
升級
升級管理員工作站：
檢查管理員工作站設定檔中的
adminWorkstation.diskGB欄位，確認指定的大小至少為 100，例如：adminWorkstation: diskGB: 100升級至 1.28 以上版本時，需要 100 GB 的空間。如果管理員工作站的磁碟空間不足，叢集升級作業就會失敗。
從跳躍伺服器下載
gkeadm：gkeadm upgrade gkeadm --target-version TARGET_VERSION
將
TARGET_VERSION替換為要升級的版本。您必須以X.Y.Z-gke.N的形式指定完整版本號碼。如需 Google Distributed Cloud 版本清單，請參閱「版本管理」。升級管理員工作站：
gkeadm upgrade admin-workstation --config AW_CONFIG_FILE \ --info-file INFO_FILE
更改下列內容：
AW_CONFIG_FILE：管理員工作站設定檔的路徑。如果檔案位於目前的目錄中，而且名稱為admin-ws-config.yaml，則可省略這個旗標。INFO_FILE：資訊檔案的路徑。如果檔案位於目前的目錄中，則可省略這個旗標。這個檔案的預設名稱與管理員工作站的名稱相同。
使用者自行管理
在管理員工作站上，前往要安裝新版 gkectl 的目錄。
下載「
gkectl」：gcloud storage cp gs://gke-on-prem-release/gkectl/TARGET_VERSION/gkectl ./ chmod +x gkectl
將
TARGET_VERSION替換為要升級的版本。您必須以X.Y.Z-gke.N的形式指定完整版本號碼。如需 Google Distributed Cloud 版本清單，請參閱「版本管理」。下載 Google Distributed Cloud 套件。請確認版本與您用來下載
gkectl的版本相符：gcloud storage cp gs://gke-on-prem-release/gke-onprem-bundle/TARGET_VERSION/gke-onprem-vsphere-TARGET_VERSION.tgz ./
升級管理員叢集
升級管理員叢集的步驟會因要升級的子版本 (目標版本) 而略有不同：
1.31 以上
如果目標版本為 1.31 以上，請先升級管理員叢集，再將使用者叢集升級至下一個子版本。在 1.31 以上版本中，管理員叢集版本 (包括修補程式版本) 必須大於或等於使用者叢集版本。舉例來說，如果管理員叢集版本為 1.31.1，則使用者叢集最高可升級至 1.31.1 版。
在管理員工作站執行下列指令，將 OS 映像檔匯入 vSphere：
gkectl prepare \
--bundle-path /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz \
--kubeconfig ADMIN_CLUSTER_KUBECONFIG
將 ADMIN_CLUSTER_KUBECONFIG 替換為管理員叢集 kubeconfig 檔案的路徑。
1.30 以下版本
如果目標版本為 1.30 以下，您必須先升級所有使用者叢集，再升級管理員叢集。管理員叢集的子版本必須小於或等於使用者叢集的子版本。修補程式版本不影響。舉例來說，如果使用者叢集版本為 1.30.1，管理員叢集可以升級至較高的修補程式版本，例如 1.30.3。
執行升級
gkectl
請在管理員工作站上執行本節中的步驟。gkectl upgrade admin 指令有兩種變化版本：
非同步：
使用非同步變化版本時，指令會啟動升級，然後完成。您不必在整個升級期間監控指令的輸出內容。您可以改為執行gkectl list admin和gkectl describe admin，定期查看升級進度。如要使用非同步變化版本，請在指令中加入--async旗標。非同步升級的需求條件：
- 僅支援 1.29 以上版本的高可用性管理員叢集。
- 所有使用者叢集都必須啟用 Controlplane V2。
- 1.31 版：不支援進階叢集。
- 1.32 以上版本：適用於進階叢集。
同步：
使用同步變化版本時，gkectl upgrade admin指令輸出會在升級過程中，將狀態訊息輸出至管理員工作站。
非同步升級
在管理員工作站上，先診斷叢集再升級：
gkectl diagnose cluster \ --kubeconfig ADMIN_CLUSTER_KUBECONFIG
如果指令回報任何錯誤或警告，請參閱「診斷叢集問題」並解決問題，再繼續操作。
啟動非同步升級：
gkectl upgrade admin \ --kubeconfig ADMIN_CLUSTER_KUBECONFIG \ --config ADMIN_CLUSTER_CONFIG_FILE \ --async
更改下列內容：
ADMIN_CLUSTER_KUBECONFIG：管理員叢集的 kubeconfig 檔案路徑。ADMIN_CLUSTER_CONFIG_FILE：管理員叢集設定檔的路徑。
上述指令完成後，您可以在升級期間繼續使用管理員工作站。
如要查看升級狀態，請按照下列步驟操作：
gkectl list admin --kubeconfig ADMIN_CLUSTER_KUBECONFIG
輸出內容會顯示叢集
STATE的值。如果叢集仍在升級，STATE的值會是UPGRADING。例如：NAME STATE AGE VERSION gke-admin-test UPGRADING 9h 1.36.100-gke.144
STATE的可能值為RUNNING、UPGRADING、RECONCILING、ERROR和UNKNOWN。如要進一步瞭解升級進度和叢集事件，請按照下列步驟操作：
gkectl describe admin --kubeconfig ADMIN_CLUSTER_KUBECONFIG
輸出內容會顯示指定管理員叢集的 OnPremAdminCluster 自訂資源，包括叢集狀態和條件。
按這裡查看輸出內容範例
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升級完成後，
gkectl list admin會顯示RUNNING的STATE：NAME STATE AGE VERSION gke-admin-test RUNNING 9h 1.36.100-gke.144此外，升級完成後，
gkectl describe admin會在Status下方顯示Last GKE On Prem Version欄位。例如：Status: Cluster State: RUNNING Last GKE On Prem Version: 1.36.0-gke.1
排解非同步升級問題
如果是非同步升級，逾時時間長度取決於叢集中的節點數量。如果升級時間超過逾時時間長度，叢集狀態會從 UPGRADING 變更為 ERROR，並顯示升級作業逾時的事件。請注意，這裡的 ERROR 狀態表示升級時間超出預期，但尚未終止。控制器會繼續協調，並持續重試作業。如果升級作業遭到封鎖或失敗，您可以執行 gkectl diagnose，檢查常見的叢集問題。您可以根據結果，決定要手動修正，還是聯絡 Google Cloud 支援團隊尋求進一步協助。
同步升級
在管理員工作站上，先診斷叢集再升級：
gkectl diagnose cluster \ --kubeconfig ADMIN_CLUSTER_KUBECONFIG
如果指令回報任何錯誤或警告，請參閱「診斷叢集問題」並解決問題，再繼續操作。
升級管理員叢集：
gkectl upgrade admin \ --kubeconfig ADMIN_CLUSTER_KUBECONFIG \ --config ADMIN_CLUSTER_CONFIG_FILE
更改下列內容：
ADMIN_CLUSTER_KUBECONFIG：管理員叢集 kubeconfig 檔案的路徑。ADMIN_CLUSTER_CONFIG_FILE：管理員叢集設定檔的路徑。
gkectl upgrade指令會執行預檢。如果預檢失敗，指令就會遭到封鎖。您必須修正失敗問題，或在指令中使用--skip-preflight-check-blocking旗標，才能解除封鎖。如果您升級至 1.14.0 以上版本，系統會為管理員叢集產生新的 kubeconfig 檔案，並覆寫任何現有檔案。如要查看檔案中的叢集詳細資料，請執行下列指令：
kubectl config view --kubeconfig ADMIN_CLUSTER_KUBECONFIG
gcloud CLI
使用 gcloud CLI 升級管理員叢集。
將平台版本更新為目標版本：
gcloud container vmware admin-clusters update ADMIN_CLUSTER_NAME \ --location=REGION \ --required-platform-version=VERSION \ --async更改下列內容：
ADMIN_CLUSTER_NAME：管理員叢集的名稱。REGION：管理員叢集所在的 Google Cloud 區域。VERSION：要升級至的目標版本。
這個指令會傳回作業 ID。您可以使用
gcloud container vmware operations describe監控進度。完成平台版本更新後，請更新管理員叢集版本：
gcloud container vmware admin-clusters update ADMIN_CLUSTER_NAME \ --location=REGION \ --version=VERSION \ --async這個步驟會完成管理員叢集升級至目標版本的作業。
升級使用者叢集
您可以使用 gkectl、控制台、gcloud CLI 或 Terraform 升級使用者叢集。如要瞭解如何決定要使用的工具，請參閱「選擇升級叢集的工具」。
控制台
升級使用者叢集時，必須對管理員叢集進行一些變更。控制台會自動執行下列操作：
如果管理員叢集尚未註冊，則在 GKE On-Prem API 中註冊管理員叢集。
下載一組元件並部署至管理員叢集。元件版本與您指定的升級版本相符。管理員叢集會使用這些元件，管理該版本的使用者叢集。
如要升級使用者叢集，請按照下列步驟操作：
在控制台中，前往「Google Kubernetes Engine clusters overview」(Google Kubernetes Engine 叢集總覽) 頁面。
選取 Google Cloud 專案，然後選取要升級的叢集。
在「詳細資料」面板中，按一下「更多詳細資料」。
在「Cluster basics」(叢集基本資訊) 專區中，按一下 「Upgrade」(升級)。
在「Choose target version」(選擇目標版本) 清單中，選取要升級的版本。精選清單僅包含最新的修補程式版本。
按一下「升級」。
升級叢集前，系統會執行預檢檢查來驗證叢集狀態和節點健康狀態。如果預檢通過，使用者叢集就會升級。升級作業約需 30 分鐘才能完成。
如要查看升級狀態，請按一下「Cluster Details」(叢集詳細資料) 分頁上的「Show Details」(顯示詳細資料)。
gcloud CLI
升級使用者叢集時，必須對管理員叢集進行一些變更。gcloud container vmware clusters upgrade 指令會自動執行下列操作：
如果管理員叢集尚未註冊，則在 GKE On-Prem API 中註冊管理員叢集。
下載一組元件並部署至管理員叢集。元件版本與您指定的升級版本相符。管理員叢集會使用這些元件，管理該版本的使用者叢集。
如要升級使用者叢集，請按照下列步驟操作：
更新 Google Cloud CLI 元件：
gcloud components update取得可升級的版本清單：
gcloud container vmware clusters query-version-config \ --cluster=USER_CLUSTER_NAME \ --project=PROJECT_ID \ --location=REGION
指令會輸出類似以下的結果：
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您可以忽略版本清單後方的訊息。無論您要升級的版本是否已安裝在管理員叢集上，都不會影響升級作業。
upgrade指令會下載並部署與upgrade指令中指定版本相符的元件套件。升級叢集。
gcloud container vmware clusters upgrade USER_CLUSTER_NAME \ --project=PROJECT_ID \ --location=REGION \ --version=VERSION
將 VERSION 替換為要升級的 Google Distributed Cloud 版本。從上一個指令的輸出內容中指定版本。建議您升級至最新修補程式版本。
指令會輸出類似以下的結果：
Waiting for operation [projects/example-project-12345/locations/us-west1/operations/operation-1679543737105-5f7893fd5bae9-942b3f97-75e59179] to complete.
在輸出範例中，字串
operation-1679543737105-5f7893fd5bae9-942b3f97-75e59179是長時間執行的作業 OPERATION_ID。在其他終端機視窗中執行下列指令，即可查看作業狀態：gcloud container vmware operations describe OPERATION_ID \ --project=PROJECT_ID \ --location=REGION
gkectl
準備升級使用者叢集
在管理員工作站上執行下列步驟：
在開始嘗試初始升級之前，請先檢查使用者叢集是否健康。請參閱「診斷叢集問題」。在使用者叢集上執行
gkectl diagnose cluster，並解決所有問題。只有在
TARGET_VERSION為 1.30 以下版本，或要將使用者叢集升級至與管理員叢集不同的版本時，才需要執行這個步驟。執行gkectl prepare，將 OS 映像檔匯入 vSphere：gkectl prepare \ --bundle-path /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz \ --kubeconfig ADMIN_CLUSTER_KUBECONFIG
如果叢集有 Windows 節點集區，請執行
gkectl prepare windows，並更新節點集區的osImage欄位。如需詳細操作說明，請參閱「升級含有 Windows 節點集區的使用者叢集」。在使用者叢集設定檔中，將
gkeOnPremVersion設為升級目標版本。
執行預檢檢查
升級至 1.29 以上版本時，您可以在升級使用者叢集前執行預檢：
gkectl upgrade cluster \
--kubeconfig ADMIN_CLUSTER_KUBECONFIG \
--config USER_CLUSTER_CONFIG \
--dry-run
將 USER_CLUSTER_CONFIG 替換為使用者叢集設定檔的路徑。
使用 --dry-run 旗標時，gkectl upgrade cluster 會執行預檢，但不會啟動升級程序。雖然舊版 Google Distributed Cloud 會執行預檢，但無法與升級作業分開執行。新增 --dry-run 旗標後，您就能在升級前，找出並修正預檢作業在使用者叢集中發現的問題。
執行 gkectl upgrade cluster
gkectl upgrade cluster 指令有兩種變化版本：
非同步 (建議)：
使用非同步變化版本時，指令會啟動升級，然後完成。您不必在整個升級期間監控指令的輸出內容。您可以改為執行gkectl list clusters和gkectl describe clusters，定期查看升級進度。如要使用非同步變化版本，請在指令中加入--async旗標。- 1.31 版：不適用於進階叢集。
- 1.32 以上版本：適用於進階叢集。
同步：
使用同步變化版本時，gkectl upgrade cluster指令輸出會在升級過程中，將狀態訊息輸出至管理員工作站。
非同步升級
如果您要升級至 1.16 以上版本，請略過這個步驟。
如果您為使用者叢集使用預先準備的憑證和私人登錄檔，請務必在升級使用者叢集前，先準備好私人登錄檔憑證。如要瞭解如何準備私人登錄檔憑證，請參閱「為使用者叢集設定預先準備的憑證」。
診斷叢集，確保其健康狀態良好：
gkectl diagnose cluster \ --kubeconfig <var>ADMIN_CLUSTER_KUBECONFIG</var>如果指令回報任何錯誤或警告，請參閱「診斷叢集問題」並解決問題，再繼續操作。
在管理員工作站上，啟動非同步升級：
gkectl upgrade cluster \ --kubeconfig ADMIN_CLUSTER_KUBECONFIG \ --config USER_CLUSTER_CONFIG \ --async
上述指令完成後，您可以在升級期間繼續使用管理員工作站。
如要查看升級狀態，請按照下列步驟操作：
gkectl list clusters --kubeconfig ADMIN_CLUSTER_KUBECONFIG
輸出內容會顯示叢集
STATE的值。如果叢集仍在升級，STATE的值會是UPGRADING。例如：NAMESPACE NAME READY STATE AGE VERSION my-uc-gkeonprem-mgmt my-uc False UPGRADING 9h 1.36.0-gke.1
STATE的可能值為UPGRADING、DELETING、UPDATING、RUNNING、RECONCILING、ERROR和UNKNOWN。如要進一步瞭解升級進度和叢集事件，請按照下列步驟操作：
gkectl describe clusters --kubeconfig ADMIN_CLUSTER_KUBECONFIG \ --cluster USER_CLUSTER_NAME -v 5
輸出內容會顯示指定使用者叢集的 OnPremUserCluster 自訂資源，包括叢集狀態、條件和事件。
按這裡查看輸出內容範例
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
升級完成後，
gkectl list clusters會顯示RUNNING的STATE：NAMESPACE NAME READY STATE AGE VERSION my-uc-gkeonprem-mgmt my-uc True RUNNING 9h 1.36.0-gke.1
此外，升級完成後，
gkectl describe clusters會在Status下方顯示Last GKE On Prem Version欄位。例如：Status: Cluster State: RUNNING Last GKE On Prem Version: 1.36.0-gke.1
排解非同步升級問題
如果是非同步升級，逾時時間長度取決於叢集中的節點數量。如果升級時間超過逾時時間長度，叢集狀態會從 UPGRADING 變更為 ERROR，並顯示升級作業逾時的事件。請注意，這裡的 ERROR 狀態表示升級時間超出預期，但尚未終止。控制器會繼續協調，並持續重試作業。
逾時通常是由 PodDisruptionBudget (PDB) 造成的死結所致。在這種情況下，Pod 無法從舊節點中剔除，舊節點也無法清空。如果 Pod 移除作業耗時超過 10 分鐘，系統會將事件寫入 OnPremUserCluster 物件。您可以執行 gkectl describe clusters 來擷取事件。接著，您可以調整 PDB，允許節點排空。之後，升級作業即可繼續進行，並最終完成。
事件範例：
Warning PodEvictionTooLong 96s (x2 over 4m7s) onprem-user-cluster-controller Waiting too long(>10m0.00000003s) for (kube-system/coredns-856d6dbfdf-dl6nz) eviction.
此外，如果升級作業遭到封鎖或失敗，您可以執行 gkectl diagnose，檢查常見的叢集問題。您可以根據結果，決定要手動修正，還是聯絡Google Cloud 支援團隊尋求進一步協助。
同步升級
gkectl upgrade 指令會執行預檢。如果預檢失敗，指令就會遭到封鎖。您必須修正失敗問題，或使用 --skip-preflight-check-blocking 旗標。除非您確信沒有重大故障，否則請勿略過預檢。
在管理員工作站上按照下列步驟操作：
如果您要升級至 1.16 以上版本，請略過這個步驟。
如果您為使用者叢集使用預先準備的憑證和私人登錄檔，請務必在升級使用者叢集前，先準備好私人登錄檔憑證。如要瞭解如何準備私人登錄檔憑證，請參閱「為使用者叢集設定預先準備的憑證」。
診斷叢集，確保其健康狀態良好：
gkectl diagnose cluster \ --kubeconfig ADMIN_CLUSTER_KUBECONFIG \ --config USER_CLUSTER_CONFIG
如果指令回報任何錯誤或警告，請參閱「診斷叢集問題」並解決問題，再繼續操作。
升級叢集：
gkectl upgrade cluster \ --kubeconfig ADMIN_CLUSTER_KUBECONFIG \ --config USER_CLUSTER_CONFIG
如果您升級至 1.14.0 以上版本，系統會為使用者叢集產生新的 kubeconfig 檔案，並覆寫任何現有檔案。如要查看檔案中的叢集詳細資料，請執行下列指令：
kubectl config view --kubeconfig USER_CLUSTER_KUBECONFIG
繼續升級
如果使用者叢集升級作業中斷，您可以執行相同的升級指令並加上 --skip-validation-all 旗標，繼續升級使用者叢集：
gkectl upgrade cluster \
--kubeconfig ADMIN_CLUSTER_KUBECONFIG \
--config USER_CLUSTER_CONFIG \
--skip-validation-all
Terraform
更新 Google Cloud CLI 元件：
gcloud components update如果尚未在 GKE On-Prem API 中註冊管理員叢集，請先完成這項操作。叢集註冊 GKE On-Prem API 後，您就不必再次執行這個步驟。
取得可升級的版本清單：
gcloud container vmware clusters query-version-config \ --cluster=USER_CLUSTER_NAME \ --project=PROJECT_ID \ --location=REGION
更改下列內容：
USER_CLUSTER_NAME：使用者叢集的名稱。PROJECT_ID：使用者叢集所屬機群專案的 ID。這是您在建立叢集時指定的專案。如果您使用gkectl建立叢集，這就是叢集設定檔中gkeConnect.projectID欄位的專案 ID。REGION：GKE On-Prem API 執行及儲存中繼資料的 Google Cloud 區域。在您用來建立使用者叢集的main.tf檔案中，區域位於叢集資源的location欄位。
指令會輸出類似以下的結果：
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下載新版元件，並部署至管理員叢集：
gcloud container vmware admin-clusters update ADMIN_CLUSTER_NAME \ --project=PROJECT_ID \ --location=REGION \ --required-platform-version=VERSION
這個指令會將您在
--required-platform-version中指定的元件版本下載至管理員叢集，然後部署元件。這些元件可讓管理員叢集管理該版本的使用者叢集。在您用來建立使用者叢集的
main.tf檔案中，將叢集資源中的on_prem_version變更為新版本。初始化並建立 Terraform 方案：
terraform initTerraform 會安裝所有必要的程式庫，例如 Google Cloud供應商。
查看設定，並視需要進行變更：
terraform plan套用 Terraform 計畫，建立使用者叢集：
terraform apply
移除整個套裝組合
如果您下載了完整套件，並成功執行 gkectl prepare，且升級了管理員叢集和所有使用者叢集，則應刪除完整套件，以節省管理員工作站的磁碟空間。執行下列指令，刪除完整套件：
rm /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION-full.tgz
繼續升級管理員叢集
如果管理員叢集升級作業中斷或失敗，只要管理員叢集檢查點包含還原中斷前狀態所需的狀態，即可繼續升級。
警告：如果升級失敗，請勿使用 gkectl repair admin-master 修復管理員控制層。否則管理員叢集會進入不良狀態。
步驟如下：
在首次嘗試升級前，請先確認管理員控制層是否正常運作。請參閱「診斷叢集問題」。如該主題所述，請為管理員叢集執行
gkectl diagnose cluster指令。如果管理員控制層在首次嘗試升級前就處於異常狀態，請使用
gkectl repair admin-master指令修復管理員控制層。如果升級作業中斷或失敗，請使用與先前升級嘗試相同的套件和目標版本，重新執行升級指令。
重新執行升級指令時，系統會從檢查點重新建立管理員叢集狀態，並重新執行整個升級作業。從 1.12.0 版開始，如果管理員控制層不健康，升級程序會直接升級至目標版本，不會嘗試將管理員叢集還原至來源版本，再繼續升級。
如果管理員叢集檢查點可用，升級作業會從失敗或退出的時間點繼續執行。如果檢查點無法使用，升級作業會改為依賴管理員控制層，因此管理員控制層必須處於健康狀態，升級作業才能繼續。升級成功後，系統會重新產生檢查點。
如果 gkectl 在管理員叢集升級期間意外結束，系統不會清除 kind 叢集。重新執行升級指令以繼續升級前，請先刪除 kind 叢集：
docker stop gkectl-control-plane && docker rm gkectl-control-plane
刪除 kind 叢集後，請再次執行升級指令。
在升級後復原管理員工作站
您可以將管理員工作站復原至升級前使用的版本。
升級期間，gkeadm 會在輸出資訊檔案中記錄升級前的版本。復原期間，gkeadm 會使用列出的版本下載舊檔案。
如要將管理員工作站復原至先前的版本，請按照下列指示操作：
gkeadm rollback admin-workstation --config=AW_CONFIG_FILE
如果管理員工作站設定檔是預設的 admin-ws-config.yaml，則可省略 --config=AW_CONFIG_FILE。否則，請將 AW_CONFIG_FILE 替換為管理員工作站設定檔的路徑。
復原指令會執行下列步驟：
- 下載
gkeadm的復原版本。 - 備份目前管理員工作站的主目錄。
- 使用
gkeadm的復原版本建立新的管理員工作站。 - 刪除原始管理員工作站。
安裝不同版本的套件來升級
升級工作站時，系統會安裝對應版本的套件，用於升級叢集。如要使用其他版本，請按照下列步驟安裝 TARGET_VERSION 的套件，也就是要升級的版本。
如要查看目前的
gkectl和叢集版本，請執行下列指令。使用--details/-d旗標可取得更詳細的資訊。gkectl version --kubeconfig ADMIN_CLUSTER_KUBECONFIG --details
輸出內容會提供叢集版本的相關資訊。
請根據輸出結果，找出下列問題並視需要修正。
如果目前的管理員叢集版本比 TARGET_VERSION 低一個以上的子版本，請將所有叢集升級至比 TARGET_VERSION 低一個子版本。
如果
gkectl版本低於 1.11，且您想升級至 1.12.x，則必須執行多次升級。請一次升級一個子版本，直到升級至 1.11.x，然後按照本主題中的指示操作。如果
gkectl版本低於 TARGET_VERSION，請將管理員工作站升級至 TARGET_VERSION。
確認
gkectl和叢集版本適合升級後，請下載套件。檢查管理員工作站是否已有套件 tarball。
stat /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz
如果套件不在管理員工作站上，請下載套件。
gcloud storage cp gs://gke-on-prem-release/gke-onprem-bundle/TARGET_VERSION/gke-onprem-vsphere-TARGET_VERSION.tgz /var/lib/gke/bundles/
安裝套件。
gkectl prepare --bundle-path /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz --kubeconfig ADMIN_CLUSTER_KUBECONFIG
將 ADMIN_CLUSTER_KUBECONFIG 替換為 kubeconfig 檔案的路徑。如果檔案位於目前的目錄中，而且名稱為
kubeconfig，則可省略這個旗標。列出可用的叢集版本，並確認目標版本包含在可用的使用者叢集版本中。
gkectl version --kubeconfig ADMIN_CLUSTER_KUBECONFIG --details
現在，您可以建立目標版本的使用者叢集，或將使用者叢集升級至目標版本。
排解升級程序問題
如果按照建議的升級程序操作時遇到問題，請參考下列建議來解決。這些建議假設您已從 1.11.x 版設定開始，並正在進行建議的升級程序。
另請參閱：排解叢集建立和升級問題
排解使用者叢集升級問題
假設您在升級使用者叢集時發現升級版本有問題，您從 Google 支援服務得知，這個問題會在日後推出的修補程式版本中修正。您可以按照下列步驟操作：
- 繼續使用目前的正式版。
- 修補程式發布後，在非正式環境叢集中測試。
- 確認沒問題後，請將所有正式版使用者叢集升級至修補程式版本。
- 將管理員叢集升級至修補程式發布版本。
排解管理員叢集升級問題
如果在升級管理員叢集時遇到問題，請與 Google 支援團隊聯絡，解決管理員叢集的問題。
同時，透過新的升級流程，您仍可享有新的使用者叢集功能，不會受到管理員叢集升級的阻礙，因此您可以視需要降低管理員叢集的升級頻率。升級程序如下：
- 將正式環境使用者叢集升級至 1.12.x。
- 將管理員叢集維持在舊版本，並繼續接收安全性修補程式。
- 在測試環境中，測試將管理員叢集從 1.11.x 升級至 1.12.x，並回報任何問題。
- 如果 1.12.x 修補程式版本解決了問題，您可以選擇將正式版管理員叢集升級至這個修補程式版本。
近期版本的已知問題
如果您是從 1.7 以上版本升級，下列已知問題可能會影響升級作業。
另請參閱：已知問題
如果資料磁碟即將用盡，升級管理員工作站可能會失敗
如果使用 gkectl upgrade admin-workstation 指令升級管理員工作站，當資料磁碟接近全滿時，升級作業可能會失敗，因為系統在升級至新的管理員工作站時，會嘗試在本機備份目前的管理員工作站。如果無法在資料磁碟上清出足夠空間，請使用 gkectl upgrade admin-workstation 指令並加上 --backup-to-local=false 旗標，避免建立目前管理員工作站的本機備份。
設有 PodDisruptionBudget 的工作負載中斷
升級叢集可能會導致使用 PodDisruptionBudgets (PDB) 的工作負載中斷或停機。
節點無法完成升級程序
如果您設定的 PodDisruptionBudget 物件無法允許任何額外中斷，節點可能會在多次嘗試後仍無法升級至控制層版本。為避免發生這類失敗，建議您擴充 Deployment 或 HorizontalPodAutoscaler，讓節點在不違反 PodDisruptionBudget 設定的情況下，順利完成排空作業。
列出使用者叢集上不允許任何中斷的所有 PodDisruptionBudget 物件：
kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
get poddisruptionbudget --all-namespaces \
-o jsonpath='{range .items[?(@.status.disruptionsAllowed==0)]}{.metadata.namespace}/{.metadata.name}{"\n"}{end}'
將 USER_CLUSTER_KUBECONFIG 替換為使用者叢集的 kubeconfig 檔案路徑。
如果預設的 kube-system/log-aggregator 和 kube-system/prometheus PDB 沒有相符的 Pod，且 status.expectedPods 為 0，則會顯示在輸出內容中，並標示 disruptionsAllowed: 0。這些 PDB 不會阻擋節點清空作業，因此可以忽略。
其他升級資訊
關於 1.1.0-gke.6 版啟用的 VMware DRS 規則
自 1.1.0-gke.6 版起，Google Distributed Cloud 會自動為使用者叢集節點建立 VMware Distributed Resource Scheduler (DRS) 反相依性規則，使其分散於資料中心內至少三個實體主機上。自 1.1.0-gke.6 版起，新叢集和現有叢集會自動啟用這項功能。
升級前，請確認 vSphere 環境符合下列條件：
VMware DRS 已啟用。VMware DRS 須搭配 vSphere Enterprise Plus 授權版本。如要瞭解如何啟用 DRS，請參閱「在叢集中啟用 VMware DRS」。
憑證設定檔中提供的 vSphere 使用者名稱具有
Host.Inventory.EditCluster權限。至少有三個實體主機可用。
如果 vSphere 環境不符合上述條件，您仍可升級，但如要將使用者叢集從 1.3.x 升級至 1.4.x，則須停用反親和性群組。詳情請參閱 Google Distributed Cloud 版本資訊中的已知問題。
升級期間的停機時間
| 資源 | 說明 |
|---|---|
| 管理員叢集 | 管理員叢集停機時，使用者叢集控制層和使用者叢集上的工作負載會繼續執行，除非受到導致停機的故障影響。 |
| 使用者叢集控制層 | 一般來說，使用者叢集的控制層應該不會有明顯的停機情形。不過，與 Kubernetes API 伺服器之間的長時間連線可能會中斷，需要重新建立。在這種情況下，API 呼叫端應重試，直到建立連線為止。在最壞的情況下，升級期間最多可能會有 1 分鐘的停機時間。 |
| 使用者叢集節點 | 如果升級作業需要變更使用者叢集節點，Google Distributed Cloud 會以滾動方式重新建立節點，並重新排定在這些節點上執行的 Pod。您可以設定適當的 PodDisruptionBudgets 和反親和性規則，避免工作負載受到影響。 |
如果資訊檔案遺失，請重新建立
如果管理員工作站的輸出資訊檔案遺失，您必須重新建立這個檔案，才能繼續升級。這個檔案是在您初次建立工作站時建立，如果您之後曾升級，檔案會更新為新資訊。
輸出資訊檔案的格式如下：
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
以下是輸出資訊檔案範例：
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
在編輯器中建立檔案，並替換適當的參數。在執行 gkeadm 的目錄中，以 VM 名稱儲存檔案。舉例來說，如果 VM 名稱為 admin-ws-janedoe，請將檔案儲存為 admin-ws-janedoe。