排解叢集建立或升級問題

您可以診斷並解決安裝或升級 Google Distributed Cloud 叢集時發生的問題。查看診斷記錄和節點狀態，有助於找出失敗原因，並復原中斷的作業。

安裝問題

以下各節可協助您排解安裝 Google Distributed Cloud 時遇到的問題。

暫時性錯誤訊息

Google Distributed Cloud 的安裝程序是持續協調迴圈。因此，安裝期間記錄中可能會出現暫時性錯誤訊息。

只要安裝順利完成，您就可以放心忽略這些錯誤。以下列出常見的暫時性錯誤記錄訊息：

  Internal error occurred: failed calling webhook "webhook.cert-manager.io": Post
  https://cert-manager-webhook.cert-manager.svc:443/mutate?timeout=10s:
  dial tcp IP_ADDRESS:443: connect: connection refused

  Internal error occurred: failed calling webhook "vcluster.kb.io": Post
  https://webhook-service.kube-system.svc:443/validate-baremetal-cluster-gke-io-v1-cluster?timeout=30s:
  dial tcp IP_ADDRESS:443: connect: connection refused

  Failed to register cluster with GKE Hub; gcloud output: error running command
  'gcloud container fleet memberships register CLUSTER_NAME  --verbosity=error --quiet':
  error: exit status 1, stderr: 'ERROR: (gcloud.container.hub.memberships.register)
  Failed to check if the user is a cluster-admin: Unable to connect to the server: EOF

  Get
  https://127.0.0.1:34483/apis/infrastructure.baremetal.cluster.gke.io/v1/namespaces/cluster-
  cluster1/baremetalmachines: dial tcp 127.0.0.1:34483: connect: connection refused"

  Create Kind Cluster "msg"="apply run failed" "error"="unable to recognize \"/tmp/kout088683152\": no matches for kind \"NetworkLogging\" in version \"networking.gke.io/v1alpha1\""
  Create Kind Cluster "msg"="apply run failed" "error"="unable to recognize \"/tmp/kout869681888\": no matches for kind \"Provider\" in version \"clusterctl.cluster.x-k8s.io/v1alpha3\""

如果 Google Cloud 服務帳戶金鑰已過期，bmctl會顯示下列錯誤訊息：

Error validating cluster config: 3 errors occurred:
        * GKEConnect check failed: Get https://gkehub.googleapis.com/v1beta1/projects/project/locations/global/memberships/admin: oauth2: cannot fetch token: 400 Bad Request
Response: {"error":"invalid_grant","error_description":"Invalid JWT Signature."}
        * ClusterOperations check failed: Post https://cloudresourcemanager.googleapis.com/v1/projects/project:testIamPermissions?alt=json&prettyPrint=false: oauth2: cannot fetch token: 400 Bad Request
Response: {"error":"invalid_grant","error_description":"Invalid JWT Signature."}
        * GCR pull permission for bucket: artifacts.anthos-baremetal-release.appspot.com failed: Get https://storage.googleapis.com/storage/v1/b/artifacts.anthos-baremetal-release.appspot.com/iam/testPermissions?alt=json&permissions=storage.objects.get&permissions=storage.objects.list&prettyPrint=false: oauth2: cannot fetch token: 400 Bad Request
Response: {"error":"invalid_grant","error_description":"Invalid JWT Signature."}

您需要產生新的服務帳戶金鑰。

使用啟動叢集偵錯

Google Distributed Cloud 建立自行管理的叢集 (管理員、混合或獨立叢集) 時，會部署 Kubernetes in Docker (kind) 叢集，暫時託管建立叢集所需的 Kubernetes 控制器。這個暫時叢集稱為啟動叢集。使用者叢集是由管理員或混合叢集建立及升級，不需使用 bootstrap 叢集。

注意： 自 Google Distributed Cloud 1.15.0 版起，自行管理的叢集 (管理員、混合或獨立叢集) 預設升級行為是就地升級。就地升級會使用生命週期控制器 (而非 bootstrap 叢集) 管理整個升級作業。這項異動可簡化程序並減少資源需求，讓叢集升級更可靠且可擴充。雖然不建議這麼做，但您仍可使用 bmctl upgrade 指令設定 --use-bootstrap=true 旗標，選擇使用 bootstrap 叢集。

如果您嘗試安裝時，部署作業中已有 kind 叢集，Google Distributed Cloud 會刪除現有的 kind 叢集。只有在安裝或升級成功後，才會刪除。如要在成功後保留現有的 kind 叢集，請使用 bmctl 的 --keep-bootstrap-cluster 旗標。

Google Distributed Cloud 會在 WORKSPACE_DIR/.kindkubeconfig 下為 bootstrap 叢集建立設定檔。只有在建立及升級叢集時，才能連線至 bootstrap 叢集。

bootstrap 叢集需要存取 Docker 存放區，才能提取映像檔。除非您使用私人登錄檔，否則登錄檔預設為 Artifact Registry。建立叢集時，bmctl 會建立下列檔案：

• bmctl-workspace/config.json：包含 Google Cloud 服務帳戶憑證，用於存取登錄檔。憑證是從叢集設定檔的 gcrKeyPath 欄位取得。

• bmctl-workspace/config.toml：包含 kind 叢集中的 containerd 設定。

檢查啟動叢集記錄

如要對啟動叢集進行偵錯，請按照下列步驟操作：

• 在建立及升級叢集期間，連線至啟動叢集。
• 取得啟動叢集的記錄。

您可以在執行 bmctl 的機器中，找到下列資料夾中的記錄：

• bmctl-workspace/CLUSTER_NAME/log/create-cluster-TIMESTAMP/bootstrap-cluster/
• bmctl-workspace/CLUSTER_NAME/log/upgrade-cluster-TIMESTAMP/bootstrap-cluster/

將 CLUSTER_NAME 和 TIMESTAMP 替換為叢集名稱和對應的系統時間。

如要直接從 bootstrap 叢集取得記錄，您可以在建立及升級叢集時執行下列指令：

docker exec -it bmctl-control-plane bash

這個指令會在 bmctl 控制層容器內開啟終端機，該容器在啟動叢集中執行。

如要檢查 kubelet 和 containerd 記錄，請使用下列指令，並在輸出內容中尋找錯誤或警告：

journalctl -u kubelet
journalctl -u containerd

啟用 containerd 偵錯記錄檔功能

如果標準 containerd 記錄檔提供的資訊不足，無法排解問題，您可以提高記錄層級。診斷複雜問題 (例如登錄檔鏡像或 ImagePullBackOff 錯誤) 時，通常需要提高記錄層級。

注意： 如果在疑難排解期間觸發 machine-update 工作，該工作會復原您對 config.toml 檔案所做的任何變更。如果發生這種情況，請等待工作完成，然後再試一次。

如要提高記錄層級，請按照下列步驟操作：

1. 啟用偵錯記錄功能：

   1. 使用偏好的文字編輯器開啟 containerd 設定檔 (/etc/containerd/config.toml)。

   2. 在檔案中，找出 [debug] 區段，並將 level 的值從 "" 變更為 "debug"。

   3. 儲存檔案並離開文字編輯器。

   4. 確認設定檔已成功更新：

      cat /etc/containerd/config.toml | grep debug
      

      輸出內容應如下所示：

      [debug]
        level = "debug"
          shim_debug = false
      

   5. 如要套用記錄層級變更，請重新啟動 containerd：

      sudo systemctl restart containerd
      

2. 如要產生新的記錄項目，請嘗試提取不存在或未由任何節點或叢集使用的映像檔。例如：

   # This command fails because the image doesn't exist
   crictl pull us-west1-docker.pkg.dev/gdc-project/samples/non-existent-image:latest
   

   這會強制 containerd 執行動作並產生詳細記錄。

3. 等待映像檔提取或失敗，然後將 containerd 記錄收集到名為 containerd_log.txt 的檔案中：

   journalctl -u containerd --no-pager --since TIME_PERIOD > containerd_log.txt
   

   將 TIME_PERIOD 替換為指定記錄開始時間的值。如果值含有空格，請以雙引號括住。例如："2 hours ago"。

4. 完成疑難排解後，請將記錄層級還原為預設值。如果持續啟用偵錯記錄檔功能，系統記錄可能會過多，影響效能，並可能洩漏機密資訊。

   1. 開啟 /etc/containerd/config.toml 檔案，並將 level 的值改回預設記錄層級 ""。

   2. 確認設定已成功更新：

      cat /etc/containerd/config.toml | grep level
      

      輸出內容應如下所示：

      level = ""
      

   3. 如要套用變更，請重新啟動 containerd：

      sudo systemctl restart containerd
      

      系統現在已恢復標準記錄設定。

叢集升級問題

升級 Google Distributed Cloud 叢集時，您可以監控進度，並查看叢集和節點的狀態。

• 如果在升級期間遇到問題，請嘗試判斷失敗發生在哪個階段。如要進一步瞭解叢集在升級程序中的情況，請參閱「叢集升級的生命週期和階段」。
• 如要進一步瞭解叢集升級期間發生問題的影響，請參閱「瞭解 Google Distributed Cloud 故障的影響」。

您可以參考下列指引，判斷升級作業是否正常進行，或是否有問題。

監控升級進度

在升級過程中，使用 kubectl describe cluster 指令查看叢集狀態：

kubectl describe cluster CLUSTER_NAME \
    --namespace CLUSTER_NAMESPACE \
    --kubeconfig ADMIN_KUBECONFIG

替換下列值：

• CLUSTER_NAME：叢集名稱。
• CLUSTER_NAMESPACE：叢集的命名空間。
• ADMIN_KUBECONFIG：管理員 kubeconfig 檔案。
  • 根據預設，管理員、混合和獨立叢集會使用就地升級。如果您搭配使用 --use-bootstrap=true 旗標和 bmctl upgrade 指令，升級作業會使用 bootstrap 叢集。如要在使用啟動叢集時監控升級進度，請指定啟動叢集 kubeconfig 檔案 .kindkubeconfig 的路徑。這個檔案位於工作區目錄中。

查看輸出內容的 Status 部分，其中會顯示叢集升級狀態的匯總。如果叢集回報錯誤，請參閱下列各節，排解問題所在。

確認節點是否已準備就緒

在升級過程中，使用 kubectl get nodes 指令查看叢集中的節點狀態：

kubectl get nodes --kubeconfig KUBECONFIG

如要確認節點是否已成功完成升級程序，請查看指令回應中的 VERSION 和 AGE 欄。VERSION 是叢集的 Kubernetes 版本。如要查看特定 Google Distributed Cloud 版本的 Kubernetes 版本，請參閱「版本管理」。

如果節點顯示 NOT READY，請嘗試連線至節點，並檢查 kubelet 狀態：

systemctl status kubelet

您也可以查看 kubelet 記錄：

journalctl -u kubelet

查看 kubelet 狀態和記錄的輸出內容，找出指出節點問題原因的訊息。

查看正在升級的節點

如要查看叢集中正在升級的節點，請使用 kubectl get baremetalmachines 指令：

kubectl get baremetalmachines --namespace CLUSTER_NAMESPACE \
    --kubeconfig ADMIN_KUBECONFIG

替換下列值：

• CLUSTER_NAMESPACE：叢集的命名空間。
• ADMIN_KUBECONFIG：管理員 kubeconfig 檔案。
  • 如果使用啟動叢集進行管理員、混合或獨立升級，請指定啟動叢集 kubeconfig 檔案 (bmctl-workspace/.kindkubeconfig)。

以下輸出範例顯示，升級中的節點 ABM VERSION 與 DESIRED ABM VERSION 不同：

NAME         CLUSTER    READY   INSTANCEID               MACHINE      ABM VERSION   DESIRED ABM VERSION
10.200.0.2   cluster1   true    baremetal://10.200.0.2   10.200.0.2   1.13.0        1.14.0
10.200.0.3   cluster1   true    baremetal://10.200.0.3   10.200.0.3   1.13.0        1.13.0

查看哪些節點正在進行排空作業

在升級過程中，系統會清空節點中的 Pod，並停用排程功能，直到節點成功升級為止。如要查看哪些節點正在清空，請使用 kubectl get nodes 指令：

kubectl get nodes --kubeconfig USER_CLUSTER_KUBECONFIG | grep "SchedulingDisabled"

將 USER_CLUSTER_KUBECONFIG 替換為使用者叢集 kubeconfig 檔案的路徑。

STATUS 欄會使用 grep 篩選，只顯示回報 SchedulingDisabled 的節點。這個狀態表示節點正在清空。

您也可以從管理員叢集查看節點狀態：

kubectl get baremetalmachines -n CLUSTER_NAMESPACE \
  --kubeconfig ADMIN_KUBECONFIG

替換下列值：

• CLUSTER_NAMESPACE：叢集的命名空間。
• ADMIN_KUBECONFIG：管理員 kubeconfig 檔案。
  • 如果使用啟動叢集進行管理員、混合或獨立升級，請指定啟動叢集 kubeconfig 檔案 (bmctl-workspace/.kindkubeconfig)。

正在排空的節點會在 MAINTENANCE 欄下方顯示狀態。

檢查節點長時間處於「正在排除」狀態的原因

使用上一節中的其中一種方法，透過 kubectl get nodes 指令找出正在清空的節點。使用 kubectl get pods 指令並篩選這個節點名稱，即可查看其他詳細資料：

kubectl get pods --all-namespaces -o wide --field-selector spec.nodeName=NODE_NAME

將 NODE_NAME 替換為要排除的節點名稱。輸出內容會傳回卡住或耗盡速度緩慢的 Pod 清單。如果節點的排除程序耗時超過 20 分鐘，即使有 Pod 卡住，升級作業仍會繼續進行。

從 1.29 版開始，節點清空程序會使用 Eviction API，該 API 遵循 PodDisruptionBudgets (PDB)。

下列 PDB 設定可能會導致節點耗盡問題：

• 由多個 PDB 管理的 Pod

• PDB 靜態設定，例如：

  • maxUnavailable == 0
  • minUnavailable >= 副本總數

  副本總數是在較高層級的資源 (例如 Deployment、ReplicaSet 或 StatefulSet) 中定義，因此很難從 PDB 資源判斷。PDB 只會根據設定中的選取器與 Pod 比對。如要診斷靜態 PDB 設定是否造成問題，建議先查看 pdb.Status.ExpectPods <= pdb.Status.DesiredHealthy，並確認上述靜態設定是否允許這種情況發生。

執行階段違規事項 (例如 PDB 資源的 DisruptionsAllowed 計算值為 0) 也可能導致節點耗盡作業遭到封鎖。如果您設定的 PodDisruptionBudget 物件無法允許任何額外中斷，節點升級作業在多次嘗試後，可能無法升級至控制層版本。為避免發生這種失敗情形，建議您擴充 Deployment 或 HorizontalPodAutoscaler，讓節點在不違反 PodDisruptionBudget 設定的情況下，順利完成排空作業。

如要查看所有不允許任何中斷的 PodDisruptionBudget 物件，請使用下列指令：

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

查看 Pod 狀態不佳的原因

如果 Pod 包含 upgrade-first-node 或 upgrade-node 控制層 IP 位址，升級可能會失敗。這種情況通常是因為靜態 Pod 狀況不佳。

1. 使用 crictl ps -a 指令檢查靜態 Pod，並找出任何當機的 Kubernetes 或 etcd Pod。如有任何失敗的 Pod，請查看 Pod 的記錄，瞭解當機原因。

   CrashLoop 行為的可能原因包括：

   • 掛接至靜態 Pod 的檔案權限或擁有者不正確。
   • 無法連線至虛擬 IP 位址。
   • 「etcd」的問題。

2. 如果 crictl ps 指令無法運作或未傳回任何內容，請檢查 kubelet 和 containerd 狀態。使用 systemctl status SERVICE 和 journalctl -u SERVICE 指令查看記錄。

後續步驟

如需其他協助，請與 Cloud Customer Care 團隊聯絡。您也可以參閱「取得支援」，進一步瞭解支援資源，包括：

• 建立客服案件的需求條件。
• 工具：協助您疑難排解，例如您的環境設定、記錄和指標。
• 支援的元件。