升級叢集

本文說明如何升級 Google Distributed Cloud (僅限軟體) for VMware 中的叢集。本文將說明如何升級管理員工作站、使用者叢集和管理員叢集。升級使用者叢集的步驟說明如何升級控制層和所有節點集區。如要分別升級使用者叢集控制層和節點集區，請參閱「升級節點集區」。

本頁面適用於負責管理基礎技術架構生命週期的 IT 管理員和作業人員。如要進一步瞭解我們在 Google Cloud 內容中提及的常見角色和範例工作，請參閱「常見的 GKE Enterprise 使用者角色和工作」。

繼續操作之前，建議您先詳閱下列說明文件：

• 升級總覽
  這份文件說明瞭升級的支援版本偏差和版本規則，這些規則在 1.28 以上版本中有所變更。

• 升級最佳做法
  本文提供升級叢集的檢查清單和最佳做法。

進階叢集差異

啟用進階叢集後，升級作業會有所不同，尤其是在 1.31 版的進階叢集預先發布版中。如要查看升級差異，請在這份文件中搜尋「advanced」一詞。如需所有差異的表格，請參閱執行進階叢集時的差異。

需求條件

本節提供版本相關需求，以及使用 GKE On-Prem API 用戶端 ( Google Cloud 控制台、Google Cloud CLI 和 Terraform) 升級時的需求。

版本規則

升級規則取決於叢集次要版本。

• 如果是 1.30 以下版本，使用者叢集的子版本必須大於或等於管理員叢集的子版本。修補程式版本無關緊要。舉例來說，如果使用者叢集版本為 1.30.1，管理員叢集可以升級至較高的修補程式版本，例如 1.30.3。

• 如果是 1.31 以上版本，管理員叢集版本 (包括修補程式版本) 必須大於或等於使用者叢集版本。舉例來說，如果管理員叢集是 1.31.1 版，使用者叢集最高只能升級至 1.31.1 版。

如要將叢集升級至 1.31 版，請先將所有叢集升級至 1.30 版。所有叢集都升級至 1.30 版後，即可將管理員叢集升級至 1.31 版。完成後，即可將使用者叢集升級至與管理員叢集相同的 1.31 修補程式版本。

「gkectl」的版本規則

可供升級的 gkectl 版本取決於目標叢集版本 (即要升級的叢集版本)。一般來說，您會使用與叢集目標版本相同的 gkectl 版本。升級期間會強制執行下列規則：

• gkectl 版本不得低於目標次要叢集版本。舉例來說，如果您要將 1.29 叢集升級至 1.30，就無法使用 gkectl 1.29，因為該版本低於目標叢集版本。修補程式版本不重要。舉例來說，您可以使用 gkectl 1.29.0-gke.1456 版升級至較高的修補程式版本，例如 1.29.1000-gke.94。

• gkectl 版本不得高於目前的叢集版本超過兩個次要版本。舉例來說，如果將 1.28 叢集升級至 1.29，gkectl 版本可以是 1.29 或 1.30。但您無法使用 gkectl 1.31 版，因為該版本比叢集版本高出三個子版本。

如有需要，請參閱「下載 gkectl」一文，瞭解如何取得支援的 gkectl 版本。

檢查防火牆規則

在 1.29 以上版本中，伺服器端預檢檢查功能預設為啟用。 伺服器端預檢需要額外的防火牆規則。在「管理員叢集的防火牆規則」中，搜尋「Preflight checks」，並確認已設定所有必要的防火牆規則。

透過伺服器端前置檢查，使用 gkectl 升級使用者叢集時，前置檢查會在管理員叢集上執行，而不是在管理員工作站本機執行。使用 Google Cloud 控制台、Google Cloud CLI 或 Terraform 升級叢集時，系統也會在管理員叢集上執行伺服器端預檢。

升級管理員叢集時，Google Distributed Cloud 會部署 Kubernetes in Docker (kind) 叢集，暫時託管升級管理員叢集所需的 Kubernetes 控制器。這個暫時性叢集稱為「啟動叢集」。升級管理員叢集時，系統會在啟動叢集上執行伺服器端預檢。

啟用 Dataplane V2

自 1.31 版起，所有使用者叢集都必須啟用 Dataplane V2。 將使用者叢集升級至 1.31 版之前，請先完成下列步驟。如果您對暫時移除 NetworkPolicy 規格有疑慮，請與 Google 支援團隊聯絡。

在使用者叢集設定檔中，將 enableDataplaneV2 設為 true。

如果叢集使用 NetworkPolicy，請暫時從叢集中移除規格，方法如下：

1. 檢查叢集是否套用任何非系統 NetworkPolicy：

   kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get networkpolicy -A -o wide | grep -v kube-system
   

2. 如果上一個步驟的輸出內容不為空白，請將每個 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 的命名空間。

3. 使用下列指令刪除 NetworkPolicy：

   kubectl --kubeconfig USER_CLUSTER_KUBECONFIG delete networkpolicy NETWORK_POLICY_NAME -n NETWORK_POLICY_NAMESPACE
   

4. 繼續升級。

5. 升級完成後，如果您移除了任何非系統 NetworkPolicy 規格，請使用下列指令重新套用：

   kubectl --kubeconfig USER_CLUSTER_KUBECONFIG apply -f NETWORK_POLICY_NAME.yaml
   

Google API 和 IAM 需求

如要將叢集升級至 1.28 以上版本，您必須啟用 kubernetesmetadata.googleapis.com，並將 kubernetesmetadata.publisher 身分與存取權管理角色授予記錄與監控服務帳戶。如要使用 Cloud Monitoring，就必須進行這些變更。

1. 啟用 kubernetesmetadata.googleapis.com：

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

   將 PROJECT_ID 替換為車隊主專案的 ID，使用者叢集是該專案的成員。這是您在建立叢集時指定的專案。如果您使用 gkectl 建立叢集，這個 ID 就是叢集設定檔中 gkeConnect.projectID 欄位的專案 ID。

2. 如果貴機構已設定許可清單，允許來自 Google API 和其他位址的流量通過 Proxy 伺服器，請將 kubernetesmetadata.googleapis.com 加入許可清單。

3. 將 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 版之前，請務必將叢集遷移至建議功能。

升級使用者叢集的身分與存取權管理需求

如果您打算使用 gkectl 升級使用者叢集，請略過本節。

如要使用 Google Cloud 控制台、Google Cloud CLI 或 Terraform 升級使用者叢集，且您不是專案擁有者，則必須在建立叢集的 Google Cloud 專案中，獲派roles/gkeonprem.admin Identity and Access Management 角色。如要進一步瞭解這個角色包含的權限，請參閱 IAM 說明文件中的「GKE On-Prem 角色」。

如要使用主控台升級叢集，您至少還需要下列項目：

• roles/container.viewer。使用者可透過這個角色在主控台中查看 GKE 叢集頁面和其他容器資源。如要進一步瞭解這個角色包含的權限，或授予具有讀取/寫入權限的角色，請參閱 IAM 說明文件中的「Kubernetes Engine 角色」。

• roles/gkehub.viewer。這個角色可讓使用者在主控台中查看叢集。如要進一步瞭解這個角色包含的權限，或授予具備讀取/寫入權限的角色，請參閱 IAM 說明文件中的「GKE Hub 角色」。

進階叢集的限制

如果已啟用進階叢集，請注意下列限制：

• 您必須使用 gkectl 升級叢集。不支援 GKE On-Prem API 用戶端 (主控台、gcloud CLI 和 Terraform)。

• 系統僅支援同步升級。

在升級前後變更設定

如要變更叢集設定，請在升級前後更新叢集。升級時，叢集設定的唯一變更應該是版本。視叢集版本和類型而定，其他設定變更可能會遭到忽略，或導致升級失敗。詳情請參閱「移除不支援的變更，解除升級封鎖」。

查看叢集升級可用的版本

執行下列指令，查看可升級的版本：

gkectl version --kubeconfig ADMIN_CLUSTER_KUBECONFIG

將 ADMIN_CLUSTER_KUBECONFIG 替換為管理員叢集 kubeconfig 檔案的路徑。

輸出畫面會顯示目前版本和可升級的版本。

如果您打算使用控制台、gcloud CLI 或 Terraform 升級，版本發布後約 7 到 14 天，GKE On-Prem API 才會在所有 Google Cloud 區域提供該版本。控制台只會列出可供使用者叢集升級的版本。使用 gcloud CLI 或 Terraform 升級使用者叢集的步驟包括執行 gcloud container vmware clusters query-version-config，取得可升級的版本。

升級管理員工作站

管理員工作站的升級方式取決於建立方式： gkeadm 或 使用者管理。

升級管理員叢集

升級管理員叢集的步驟會因升級目標的次要版本而略有不同：

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

事前準備：

1. 如要升級至 1.13 以上版本，請先填寫管理員叢集設定檔中的 gkeConnect 區段，註冊管理員叢集。使用設定檔變更執行 gkectl update cluster 指令。

2. 請確認 gkectl 和叢集版本適合升級，並已下載適當的套件組合。管理員與使用者叢集之間的版本差異取決於 Google Distributed Cloud 版本。如要確保可以升級管理員叢集，請參閱「管理員和使用者叢集版本差異」。

3. 請確認管理員叢集設定檔中的 bundlepath 欄位，與要升級的套件路徑相符。

   如果您對管理員叢集設定檔中的欄位進行任何其他變更，升級時系統會忽略這些變更。如要讓這些變更生效，請先升級叢集，然後執行 update cluster 指令，並使用設定檔變更，對叢集進行其他變更。

執行升級

請在管理員工作站上執行本節中的步驟。gkectl upgrade admin 指令有兩種變體：

• 非同步：
  使用非同步變體時，指令會啟動升級作業，然後完成。升級期間，您不必全程觀看指令輸出內容。您可以改為定期執行 gkectl list admin 和 gkectl describe admin，查看升級進度。如要使用非同步變體，請在指令中加入 --async 旗標。

  非同步升級的規定：

  • 僅適用於版本 1.29 以上的 HA 管理員叢集。
  • 所有使用者叢集都必須啟用 Controlplane V2。
  • 1.31 版：不支援進階叢集。
  • 1.32 以上版本：適用於進階叢集。

• 同步：
  使用同步變體時，gkectl upgrade admin 指令會在升級過程中，將狀態訊息輸出至管理員工作站。

升級使用者叢集

您可以使用 gkectl、控制台、gcloud CLI 或 Terraform 升級使用者叢集。如要瞭解如何選擇工具，請參閱「選擇升級使用者叢集的工具」。

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

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

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

移除完整套裝組合

如果您下載了完整套件，並已成功執行 gkectl prepare，以及升級管理員叢集和所有使用者叢集，就應刪除完整套件，以節省管理員工作站的磁碟空間。執行下列指令，刪除完整套件：

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

繼續升級管理員叢集

如果管理員叢集升級作業中斷或失敗，只要管理員叢集檢查點包含還原中斷前狀態所需的狀態，即可繼續升級。

警告：升級失敗後，請勿使用 gkectl repair admin-master 修復管理員主機。這會導致管理員叢集進入錯誤狀態。

步驟如下：

1. 在首次嘗試升級前，請先檢查管理控制層是否正常運作。請參閱「診斷叢集問題」。如該主題所述，請為管理員叢集執行 gkectl diagnose cluster 指令。

2. 如果管理控制層在首次嘗試升級前運作不正常，請使用 gkectl repair admin-master 指令修復管理控制層。

3. 如果升級作業中斷或失敗，請使用與上次升級嘗試相同的套件和目標版本，重新執行升級指令。

重新執行升級指令時，續傳的升級作業會從檢查點重新建立管理員叢集狀態，並重新執行整個升級作業。從 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 替換為管理員工作站設定檔的路徑。

回溯指令會執行下列步驟：

1. 下載 gkeadm 的復原版本。
2. 備份目前管理員工作站的主目錄。
3. 使用 gkeadm 的復原版本建立新的管理員工作站。
4. 刪除原始管理員工作站。

安裝其他版本的套件進行升級

升級工作站後，系統會安裝相應版本的套件，用於升級叢集。如要使用其他版本，請按照下列步驟安裝 TARGET_VERSION 的套件，也就是您要升級的版本。

1. 如要查看目前的 gkectl 和叢集版本，請執行下列指令。如需更多詳細資訊，請使用 --details/-d 標記。

   gkectl version --kubeconfig ADMIN_CLUSTER_KUBECONFIG --details
   

   輸出內容會提供叢集版本的相關資訊。

2. 根據輸出內容，找出下列問題並視需要修正。

   • 如果目前的管理員叢集版本比 TARGET_VERSION 低一個以上的次要版本，請將所有叢集升級至比 TARGET_VERSION 低一個次要版本。

   • 如果 gkectl 版本低於 1.11，且您想升級至 1.12.x，則必須執行多次升級。請一次升級一個子版本，直到升級至 1.11.x 為止，然後按照本主題中的說明操作。

   • 如果 gkectl 版本低於 TARGET_VERSION，請將管理員工作站升級至 TARGET_VERSION。

3. 確認 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/
   

4. 安裝套裝組合。

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

   請將 ADMIN_CLUSTER_KUBECONFIG 替換為 kubeconfig 檔案的路徑。如果檔案位於目前的目錄中，而且名稱為 kubeconfig，則可省略這個旗標。

5. 列出可用的叢集版本，並確認目標版本包含在可用的使用者叢集版本中。

   gkectl version --kubeconfig ADMIN_CLUSTER_KUBECONFIG --details

您現在可以建立目標版本的使用者叢集，或將使用者叢集升級至目標版本。

排解升級程序問題

如果在按照建議的升級程序操作時遇到問題，請按照下列建議解決。這些建議假設您已開始設定 1.11.x 版，並按照建議的升級程序進行。

另請參閱：排解叢集建立和升級問題

排解使用者叢集升級問題

假設您在升級使用者叢集時，發現升級版本有問題。您向 Google 支援團隊確認，這個問題會在日後推出的修補程式版本中修正。請按照下列步驟操作：

1. 繼續使用目前版本進行生產。
2. 修補程式發布後，請在非正式叢集中測試。
3. 確認沒問題後，將所有正式版使用者叢集升級至修補程式版本。
4. 將管理員叢集升級至修補程式發布版本。

排解管理員叢集升級問題

如果升級管理員叢集時發生問題，請與 Google 支援團隊聯絡，解決管理員叢集的問題。

在此期間，您仍可透過新的升級流程，享有新版使用者叢集功能，不會受到管理員叢集升級作業的阻礙，因此您可以視需要降低管理員叢集的升級頻率。升級程序如下：

1. 將正式版使用者叢集升級至 1.12.x。
2. 將管理員叢集維持在舊版，並繼續接收安全性修補程式。
3. 在測試環境中，將管理員叢集從 1.11.x 升級至 1.12.x，並回報所有問題。
4. 如果 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 get poddisruptionbudget --all-namespaces -o jsonpath='{range .items[?(@.status.disruptionsAllowed==0)]}{.metadata.name}/{.metadata.namespace}{"\n"}{end}'

附錄

關於在 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 版本資訊中的已知問題。

升級期間的停機時間

如果缺少資訊檔案，請重新建立

如果管理員工作站的輸出資訊檔案遺失，您必須重新建立這個檔案，才能繼續升級。這個檔案是在您最初建立工作站時建立，如果您之後進行升級，檔案也會更新為新資訊。

輸出資訊檔案的格式如下：

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: /usr/local/google/home/janedoe/.ssh/gke-admin-workstation
Upgraded from (rollback version): v1.10.0-gke.194
To access your admin workstation:
ssh -i /usr/local/google/home/janedoe/.ssh/gke-admin-workstation ubuntu@172.16.91.21

在編輯器中建立檔案，並代入適當的參數。將檔案儲存為與執行 gkeadm 的目錄中 VM 名稱相同的檔案名稱。舉例來說，如果 VM 名稱為 admin-ws-janedoe，請將檔案儲存為 admin-ws-janedoe。

後續步驟

• gcloud CLI 參考說明文件

  • gcloud container vmware clusters
  • gcloud container vmware node-pools
  • gcloud container vmware admin-clusters

• Terraform 參考說明文件

  • google_gkeonprem_vmware_cluster
  • google_gkeonprem_vmware_node_pool