排解叢集建立或升級問題

您可以診斷並解決安裝或升級 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 叢集。

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

Google Distributed Cloud 會在 WORKSPACE_DIR/.kindkubeconfig 下為 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 控制層容器內開啟終端機,該容器在 bootstrap 叢集中執行。

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

journalctl -u kubelet
journalctl -u containerd

啟用 containerd 偵錯記錄檔功能

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

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

  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 叢集時,您可以監控進度,並查看叢集和節點的狀態。

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

監控升級進度

使用 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 >= 副本總數

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

執行階段違規事項 (例如 PDB 資源的 DisruptionsAllowed 計算值為 0) 也可能導致節點耗盡作業遭到封鎖。如果您設定了 PodDisruptionBudget 物件,且無法允許任何額外的中斷,則節點升級作業可能會在多次嘗試後,仍無法升級至控制層版本。為避免發生這項錯誤,建議您擴充 Deployment 或 HorizontalPodAutoscaler,讓節點在遵守 PodDisruptionBudget 設定的情況下,仍可清空。

列出叢集上不允許任何中斷的所有 PodDisruptionBudget 物件:

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

將 CLUSTER_KUBECONFIG 替換為叢集的 kubeconfig 檔案路徑。

如果預設的 kube-system/log-aggregator 和 kube-system/prometheus PDB 沒有相符的 Pod,且 status.expectedPods 為 0,則會顯示在輸出內容中,並標示 disruptionsAllowed: 0。這些 PDB 不會阻擋節點清空作業,因此可以忽略。

查看 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 指令查看記錄。

解決叢集升級期間的 CIDR 驗證錯誤

從 Google Distributed Cloud 1.34 版開始,bmctl 和叢集驗證許可 Webhook (vcluster.kb.io) 會對 spec.clusterNetwork.pods.cidrBlocks 和 spec.clusterNetwork.services.cidrBlocks 執行嚴格的標準 CIDR 驗證。標準 CIDR 標記法要求將子網路前置碼長度以外的所有主機位元設為零。

如果叢集建立時使用的 Pod 或 Service CIDR 區塊不符合標準,升級至 1.34 以上版本時會失敗,並顯示類似下列的錯誤:

[E000018] Unable to Parse Cluster Configuration File: ...
* Cluster.baremetal.cluster.gke.io "CLUSTER_NAME" is invalid:
  spec.clusterNetwork.services.cidrBlocks: Invalid value: "NON_CANONICAL_CIDR":
  must not have bits set beyond the prefix length

將 Cluster 自訂資源和叢集設定檔中的 CIDR 字串更新為標準網路位址,不會重新分配現有的 Pod 或 Service IP 位址、變更轉送或中斷工作負載。

如要將非標準 CIDR 區塊更新為標準網路標記法,並解除升級封鎖,請按照下列步驟操作:

  1. 將子網路前置碼長度以外的所有主機位元設為零,藉此判斷受影響 CIDR 區塊的標準網路位址。舉例來說,如果無效的 CIDR 區塊是 10.96.0.1/16,則標準 CIDR 區塊為 10.96.0.0/16。

  2. 編輯管理員叢集上的 lcm-validating-webhook-configuration ValidatingWebhookConfiguration 資源:

    kubectl --kubeconfig ADMIN_KUBECONFIG \
        edit validatingwebhookconfiguration lcm-validating-webhook-configuration
    

    將 ADMIN_KUBECONFIG 替換為管理員叢集 kubeconfig 檔案的路徑 (或獨立或混合叢集的叢集 kubeconfig 檔案)。

  3. 在 Webhook 設定中,找出驗證 baremetal.cluster.gke.io/v1 clusters 的 vcluster.kb.io 規則。暫時從 operations 清單中移除 UPDATE,讓 Webhook 允許設定更新,然後儲存並退出編輯器。

  4. 編輯受影響的 Cluster 自訂資源:

    kubectl --kubeconfig ADMIN_KUBECONFIG \
        edit cluster CLUSTER_NAME \
        -n CLUSTER_NAMESPACE
    

    更改下列內容:

    • CLUSTER_NAME:受影響叢集的名稱
    • CLUSTER_NAMESPACE:受影響叢集的命名空間,例如 cluster-CLUSTER_NAME
  5. 將 spec.clusterNetwork.pods.cidrBlocks 或 spec.clusterNetwork.services.cidrBlocks 更新為標準 CIDR 標記法,然後儲存並結束編輯器。

  6. 再次編輯 lcm-validating-webhook-configuration,並將 UPDATE 加回 vcluster.kb.io 的 operations 清單,還原驗證用 Webhook (如果未變更,生命週期控制器會自動協調並還原這項規則)。

  7. 如果您使用 bmctl upgrade cluster,請將本機叢集設定檔 (bmctl-workspace/CLUSTER_NAME/CLUSTER_NAME.yaml) 中的 spec.clusterNetwork.pods.cidrBlocks 或 spec.clusterNetwork.services.cidrBlocks 更新為相同的標準 CIDR 標記法。

  8. 重試叢集升級作業。

後續步驟

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

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