本文說明如何升級 Google Distributed Cloud (僅限軟體) for VMware 中的叢集。本文將說明如何升級管理員工作站、使用者叢集和管理員叢集。升級使用者叢集的步驟說明如何升級控制層和所有節點集區。如要分別升級使用者叢集控制層和節點集區,請參閱「升級節點集區」。
本頁面適用於負責管理基礎技術架構生命週期的 IT 管理員和作業人員。如要進一步瞭解我們在 Google Cloud 內容中提及的常見角色和範例工作,請參閱「常見的 GKE Enterprise 使用者角色和工作」。
繼續操作之前,建議您先詳閱下列說明文件:
進階叢集差異
啟用進階叢集後,升級作業會有所不同,尤其是在 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
,請暫時從叢集中移除規格,方法如下:
檢查叢集是否套用任何非系統
NetworkPolicy
:kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get networkpolicy -A -o wide | grep -v kube-system
如果上一個步驟的輸出內容不為空白,請將每個
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
身分與存取權管理角色授予記錄與監控服務帳戶。如要使用 Cloud Monitoring,就必須進行這些變更。
啟用
kubernetesmetadata.googleapis.com
:gcloud services enable --project PROJECT_ID \ kubernetesmetadata.googleapis.com
將
PROJECT_ID
替換為車隊主專案的 ID,使用者叢集是該專案的成員。這是您在建立叢集時指定的專案。如果您使用gkectl
建立叢集,這個 ID 就是叢集設定檔中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 版之前,請務必將叢集遷移至建議功能。
升級使用者叢集的身分與存取權管理需求
如果您打算使用 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 或 使用者管理。
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 版。
事前準備:
如要升級至 1.13 以上版本,請先填寫管理員叢集設定檔中的
gkeConnect
區段,註冊管理員叢集。使用設定檔變更執行gkectl
update cluster 指令。請確認
gkectl
和叢集版本適合升級,並已下載適當的套件組合。管理員與使用者叢集之間的版本差異取決於 Google Distributed Cloud 版本。如要確保可以升級管理員叢集,請參閱「管理員和使用者叢集版本差異」。請確認管理員叢集設定檔中的
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 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.32.100-gke.106
STATE
的可能值為RUNNING
、UPGRADING
、RECONCILING
、ERROR
和UNKNOWN
。如要進一步瞭解升級進度和叢集事件,請按照下列步驟操作:
gkectl describe admin --kubeconfig ADMIN_CLUSTER_KUBECONFIG
輸出內容會顯示指定管理叢集的 OnPremAdminCluster 自訂資源,包括叢集狀態、條件和事件。
我們會記錄每個重要升級階段的開始和結束事件。
輸出內容範例:
Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal ControlPlaneUpgradeStarted 40m onprem-admin-cluster-controller Creating or updating admin cluster API Controller Normal ControlPlaneMachineUpgradeStarted 40m onprem-admin-cluster-controller Creating or updating control plane machine Normal StatusChanged 40m onprem-admin-cluster-controller OnPremAdminCluster status changed: - New ClusterState condition: UPGRADING - New Ready condition: False, CreateOrUpdateControlPlaneMachine, Creating or updating control plane machine Normal StatusChanged 2m onprem-admin-cluster-controller OnPremAdminCluster status changed: - New ClusterState condition: RUNNING - New Ready condition: True, ClusterRunning, Cluster is running
升級完成後,
gkectl list admin
會顯示STATUS
的RUNNING
:NAME STATE AGE VERSION gke-admin-test RUNNING 9h 1.32.100-gke.106
此外,升級完成後,
gkectl describe admin
會在Status
下方顯示Last GKE On Prem Version
欄位。例如:Status: Cluster State: RUNNING Last GKE On Prem Version: 1.32.0-gke.1
排解非同步升級問題
如果是非同步升級,逾時時間長度會根據叢集中的節點數而定。如果升級時間超過逾時時間長度,叢集狀態會從 UPGRADING
變更為 ERROR
,並顯示升級作業逾時的事件。請注意,這裡的 ERROR
狀態表示升級時間比預期長,但尚未終止。控制器會繼續執行協調程序,並不斷重試作業。如果升級作業遭到封鎖或失敗,可以執行 gkectl diagnose
檢查常見的叢集問題。根據結果,您可以決定是否要手動修正,或聯絡Google Cloud 支援團隊尋求進一步協助。
同步升級
執行下列指令:
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
升級使用者叢集
您可以使用 gkectl
、控制台、gcloud CLI 或 Terraform 升級使用者叢集。如要瞭解如何選擇工具,請參閱「選擇升級使用者叢集的工具」。
gkectl
準備升級使用者叢集
在管理員工作站上執行下列步驟:
只有在
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 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.32.0-gke.1
STATE
的可能值為PROVISIONING
、UPGRADING
、DELETING
、UPDATING
、RUNNING
、RECONCILING
、ERROR
和UNKNOWN
。如要進一步瞭解升級進度和叢集事件,請按照下列步驟操作:
gkectl describe clusters --kubeconfig ADMIN_CLUSTER_KUBECONFIG \ --cluster USER_CLUSTER_NAME -v 5
輸出內容會顯示指定使用者叢集的 OnPremUserCluster 自訂資源,包括叢集狀態、條件和事件。
我們會記錄每個重要升級階段的開始和結束事件,包括:
- ControlPlaneUpgrade
- MasterNodeUpgrade
- AddonsUpgrade
- NodePoolsUpgrade
輸出內容範例:
Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal NodePoolsUpgradeStarted 22m onprem-user-cluster-controller Creating or updating node pools: pool-2: Creating or updating node pool Normal AddonsUpgradeStarted 22m onprem-user-cluster-controller Creating or updating addon workloads Normal ControlPlaneUpgradeStarted 25m onprem-user-cluster-controller Creating or updating cluster control plane workloads: deploying user-kube-apiserver-base, ...: 14/15 pods are ready Normal ControlPlaneUpgradeFinished 23m onprem-user-cluster-controller Control plane is running
升級完成後,
gkectl list clusters
會顯示STATUS
的RUNNING
:NAMESPACE NAME READY STATE AGE VERSION my-uc-gkeonprem-mgmt my-uc True RUNNING 9h 1.32.0-gke.1
此外,升級完成後,
gkectl describe clusters
會在Status
下方顯示Last GKE On Prem Version
欄位。例如:Status: Cluster State: RUNNING Last GKE On Prem Version: 1.32.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
,檢查常見的叢集問題。根據結果,您可以決定是否要手動修正,或是聯絡 Anthos 支援團隊尋求進一步協助。
同步升級
gkectl upgrade
指令會執行預檢。如果預檢失敗,系統會封鎖指令。您必須修正失敗問題,或使用 --skip-preflight-check-blocking
旗標。只有在確定沒有重大故障時,才應略過前置檢查。
在管理員工作站上繼續執行下列步驟:
如果升級至 1.16 以上版本,請略過這個步驟。
如果您使用準備好的憑證和私密登錄檔做為使用者叢集,請務必先準備好私密登錄檔憑證,再升級使用者叢集。如要瞭解如何準備私有登錄檔憑證,請參閱為使用者叢集設定準備好的憑證。
升級叢集:
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_FILE \
--skip-validation-all
控制台
升級使用者叢集時,需要對管理員叢集進行一些變更。控制台會自動執行下列作業:
向 GKE On-Prem API 註冊管理員叢集 (如果尚未註冊)。
下載並將一組元件部署至管理員叢集。元件版本與您指定的升級版本相符。管理員叢集可透過這些元件管理該版本的使用者叢集。
如要升級使用者叢集,請按照下列步驟操作:
在控制台中,前往「Google Kubernetes Engine clusters overview」(Google Kubernetes Engine 叢集總覽) 頁面。
選取 Google Cloud 專案,然後選取要升級的叢集。
在「詳細資料」面板中,按一下「瞭解詳情」。
在「叢集基本資訊」專區中,按一下
「升級」。在「選擇目標版本」清單中,選取要升級的版本。精選清單只會列出最新的修補程式版本。
按一下「升級」。
叢集升級前,系統會進行預檢來驗證叢集狀態和節點健康狀態。如果預檢通過,使用者叢集就會升級。升級程序大約需要 30 分鐘才能完成。
如要查看升級狀態,請按一下「叢集詳細資料」分頁標籤上的「顯示詳細資料」。
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
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
建立叢集,這個 ID 就是叢集設定檔中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 init
Terraform 會安裝任何需要的程式庫,例如 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 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 版本資訊中的已知問題。
升級期間的停機時間
資源 | 說明 |
---|---|
管理員叢集 | 管理員叢集停機時,使用者叢集控制層和使用者叢集上的工作負載會繼續執行,除非受到導致停機的故障影響。 |
使用者叢集控制層 | 一般來說,使用者叢集的控制層應該不會有明顯的停機情形。不過,與 Kubernetes API 伺服器的長時間連線可能會中斷,需要重新建立連線。在這些情況下,API 呼叫端應重試,直到建立連線為止。在最糟的情況下,升級期間可能會停機最多一分鐘。 |
使用者叢集節點 | 如果升級需要變更使用者叢集節點,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: /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 參考說明文件
Terraform 參考說明文件