適用於 VMware 的 Google Distributed Cloud (僅限軟體) 已知問題

本頁列出 Google Distributed Cloud on VMware 的所有已知問題。本頁面適用於 IT 管理員和作業人員，他們負責管理基礎技術架構的生命週期，並在服務等級目標 (SLO) 未達成或應用程式失敗時，回應快訊和呼叫。如要進一步瞭解我們在內容中提及的常見角色和範例工作，請參閱「常見的 GKE 使用者角色和工作」。 Google Cloud

如果您是 Google 開發人員計畫成員，請儲存這個頁面，以便在發布與這個頁面相關的版本說明時收到通知。詳情請參閱「已儲存的頁面」。

如要依產品版本或類別篩選已知問題，請從下列下拉式選單中選取所需篩選器。

選取 Google Distributed Cloud 版本：

選取問題類別：

或者，搜尋你的問題：

類別 已識別版本 問題和解決方法
安裝 1.30.200-gke.101

使用者叢集建立期間，gke-connect 代理程式 Pod 卡在 Pending 狀態

建立使用者叢集時，gke-connect代理程式 Pod 可能會停滯在 Pending 狀態，導致叢集無法完全建立。發生這個問題的原因是 gke-connect 代理程式 Pod 會在工作節點可用之前嘗試排程，導致死結。

如果初始使用者叢集建立作業因前置驗證錯誤而失敗，且後續嘗試建立叢集時未先刪除部分建立的資源，就會發生這個問題。在後續的叢集建立嘗試中，gke-connect 代理程式 Pod 會因控制平面節點上未容許的汙染而停滯，如下列類似的錯誤所示：

    0/3 nodes are available: 3 node(s) had untolerated taint {node-role.kubernetes.io/control-plane: }`.

解決方法：

如果使用者叢集建立作業因前置驗證錯誤而失敗，請先刪除部分建立的叢集資源，再嘗試使用修正後的設定重新建立叢集。這可確保建立工作流程正確進行，包括在部署 gke-connect 代理程式 Pod 之前建立節點集區。
更新 1.16 和更早版本、1.28.0-1.28.1100、1.29.0-1.29.700、1.30.0-1.30.200

使用 gkectl update cluster 停用永久密碼加密後，密碼仍會以加密形式儲存在 etcd 中。這個問題只會影響 kubeception 使用者叢集。如果叢集使用 Controlplane V2，就不會受到這個問題影響。

如要檢查密鑰是否仍處於加密狀態，請執行下列指令，從 etcd 擷取儲存的密鑰 default/private-registry-creds：

kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    exec -it -n USER_CLUSTER_NAME kube-etcd-0 -c kube-etcd -- \
    /bin/sh -ec "export ETCDCTL_API=3; etcdctl \
    --endpoints=https://127.0.0.1:2379 \
    --cacert=/etcd.local.config/certificates/etcdCA.crt \
    --cert=/etcd.local.config/certificates/etcd.crt \
    --key=/etcd.local.config/certificates/etcd.key \
    get /registry/secrets/default/private-registry-creds" | hexdump -C

如果密鑰是以加密方式儲存，輸出內容如下所示：

00000000  2f 72 65 67 69 73 74 72  79 2f 73 65 63 72 65 74  |/registry/secret|
00000010  73 2f 64 65 66 61 75 6c  74 2f 70 72 69 76 61 74  |s/default/privat|
00000020  65 2d 72 65 67 69 73 74  72 79 2d 63 72 65 64 73  |e-registry-creds|
00000030  0d 0a 6b 38 73 3a 65 6e  63 3a 6b 6d 73 3a 76 31  |..k8s:enc:kms:v1|
00000040  3a 67 65 6e 65 72 61 74  65 64 2d 6b 65 79 2d 6b  |:generated-key-k|
00000050  6d 73 2d 70 6c 75 67 69  6e 2d 31 3a 00 89 65 79  |ms-plugin-1:..ey|
00000060  4a 68 62 47 63 69 4f 69  4a 6b 61 58 49 69 4c 43  |JhbGciOiJkaXIiLC|
...

如果密碼未經過加密就儲存，輸出內容如下所示：

00000000  2f 72 65 67 69 73 74 72  79 2f 73 65 63 72 65 74  |/registry/secret|
00000010  73 2f 64 65 66 61 75 6c  74 2f 70 72 69 76 61 74  |s/default/privat|
00000020  65 2d 72 65 67 69 73 74  72 79 2d 63 72 65 64 73  |e-registry-creds|
00000030  0d 0a 6b 38 73 00 0d 0a  0c 0d 0a 02 76 31 12 06  |..k8s.......v1..|
00000040  53 65 63 72 65 74 12 83  47 0d 0a b0 2d 0d 0a 16  |Secret..G...-...|
00000050  70 72 69 76 61 74 65 2d  72 65 67 69 73 74 72 79  |private-registry|
00000060  2d 63 72 65 64 73 12 00  1a 07 64 65 66 61 75 6c  |-creds....defaul|
...

解決方法：

  1. 對特定 DaemonSet 執行輪動式更新，如下所示： 
        kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
      rollout restart statefulsets kube-apiserver \
      -n USER_CLUSTER_NAME
  2. 以 YAML 格式取得使用者叢集中所有密鑰的資訊清單： 
        kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
      get secrets -A -o yaml > SECRETS_MANIFEST.yaml
  3. 在使用者叢集中重新套用所有密鑰，以便將所有密鑰以純文字形式儲存在 etcd 中： 
        kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
      apply -f SECRETS_MANIFEST.yaml

設定 1.29、1.30、1.31

gkectl get-config 指令產生的使用者叢集設定檔 user-cluster.yaml，缺少 nodePools 區段中的 hostgroups 欄位。gkectl get-config 指令會根據 OnPremUserCluster 自訂資源的內容產生 user-cluster.yaml 檔案。不過，nodePools[i].vsphere.hostgroups 欄位存在於 OnPremNodePool 自訂資源中，且您執行 gkectl get-config 時，該欄位不會複製到 user-cluster.yaml 檔案。

解決方法

如要解決這個問題，請手動將 nodePools[i].vsphere.hostgroups 欄位新增至 user-cluster.yaml 檔案。編輯後的檔案應與下列範例類似：

apiVersion: v1
kind: UserCluster
...
nodePools:
- name: "worker-pool-1"
  enableLoadBalancer: true
  replicas: 3
  vsphere:
    hostgroups:
    - "hostgroup-1"
...

您可以透過編輯過的使用者叢集設定檔更新使用者叢集，不會觸發錯誤，且 hostgroups 欄位會保留。
網路 1.29.0-1.29.1000 1.30.0-1.30.500、1.31.0-1.31.100

如果資源安裝到使用者叢集，綁定 Ingress 的 Istiod Pod 就無法就緒。gateway.networking.k8s.io您可以在 Pod 記錄中找到下列範例錯誤訊息：

    failed to list *v1beta1.Gateway: gateways.gateway.networking.k8s.io is forbidden: User \"system:serviceaccount:gke-system:istiod-service-account\" cannot list resource \"gateways\" in API group \"gateway.networking.k8s.io\" at the cluster scope"

解決方法：

將下列 ClusterRole 和 ClusterRoleBinding 套用至使用者叢集：

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: istiod-gateway
rules:
- apiGroups:
  - 'gateway.networking.k8s.io'
  resources:
  - '*'
  verbs:
  - get
  - list
  - watch
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: istiod-gateway-binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: istiod-gateway
subjects:
- kind: ServiceAccount
  name: istiod-service-account
  namespace: gke-system
安裝 1.29.0-1.29.1000 1.30.0-1.30.500、1.31.0-1.31.100

如果「ipblocks」欄位中的主機名稱包含大寫字母，管理員叢集控制層節點可能會不斷重新啟動。

解決方法：

只能使用小寫主機名稱。
安裝、升級 1.30.0-1.30.500、1.31.0-1.31.100

執行 gkeadm create 或 upgrade 後出現「error」Runtime: out of memory

使用 gkeadm 指令建立或升級管理員工作站時，驗證下載的 OS 映像檔可能會導致 OOM 錯誤。

例如：

Downloading OS image
"gs://gke-on-prem-release/admin-appliance/1.30.400-gke.133/gke-on-prem-admin-appliance-vsphere-1.30.400-gke.133.ova"...

[==================================================>] 10.7GB/10.7GB

Image saved to
/anthos/gke-on-prem-admin-appliance-vsphere-1.30.400-gke.133.ova

Verifying image gke-on-prem-admin-appliance-vsphere-1.30.400-gke.133.ova...
|

runtime: out of memory

解決方法：

  • 增加執行 gkeadm 指令的 OS 記憶體大小。
    		•
    升級 1.30.0-1.30.400

    非 HA 管理員叢集升級作業停滯在 Creating or updating cluster control plane workloads

    升級非高可用性管理員叢集時，升級作業可能會停滯在 Creating or updating cluster control plane workloads。

    如果管理員主 VM 中的 ip a | grep cali 傳回非空白結果，就會發生這個問題。

    例如：

    ubuntu@abf8a975479b-qual-342-0afd1d9c ~ $ ip a | grep cali
4: cali2251589245f@if3:  mtu 1500 qdisc noqueue state UP group default

    解決方法：

    1. 修復管理員主機： 
      gkectl repair admin-master --kubeconfig=ADMIN_KUBECONFIG \
    --config=ADMIN_CONFIG_FILE \
    --skip-validation
    2. 如果看到類似下列範例的提示，請選取 1.30 VM 範本： 
      Please select the control plane VM template to be used for re-creating the
admin cluster's control plane VM.
    3. 繼續升級： 
      gkectl upgrade admin --kubeconfig ADMIN_KUBECONFIG \
    --config ADMIN_CONFIG_FILE
    設定 1.31.0

    叢集設定檔中 network.controlPlaneIPBlock 底下的多餘 isControlPlane 欄位

    gkectl create-config 1.31.0 產生的叢集設定檔在 network.controlPlaneIPBlock 下包含多餘的 isControlPlane 欄位：

        controlPlaneIPBlock:
    netmask: ""
    gateway: ""
    ips:
    - ip: ""
      hostname: ""
      isControlPlane: false
    - ip: ""
      hostname: ""
      isControlPlane: false
    - ip: ""
      hostname: ""
      isControlPlane: false

    這個欄位不需要，可以從設定檔中安全移除。

    遷移 1.29.0-1.29.800、1.30.0-1.30.400、1.31.0

    將使用 MetalLB 的非高可用性管理員叢集遷移至高可用性時，管理員外掛程式節點可能會停留在 NotReady 狀態，導致遷移作業無法完成。

    這個問題只會影響已設定 MetalLB 但未啟用自動修復功能的管理員叢集。

    這個問題是由遷移期間的競爭條件所致，MetalLB 音箱仍在使用舊的 metallb-memberlist 密鑰。由於競爭情況，舊的控制層 VIP 會無法存取，導致遷移作業停滯。

    解決方法：

    1. 刪除現有的 metallb-memberlist 密鑰： 
      kubectl --kubeconfig=ADMIN_KUBECONFIG -n kube-system \
    delete secret metallb-memberlist
    2. 重新啟動 metallb-controller 部署作業，以便產生新的 metallb-memberlist：
      kubectl --kubeconfig=ADMIN_KUBECONFIG -n kube-system \
    rollout restart deployment metallb-controller
    3. 確認是否已產生新的 metallb-memberlist： 
      kubectl --kubeconfig=ADMIN_KUBECONFIG -n kube-system \
    get secret metallb-memberlist
    4. 將 metallb-speaker DaemonSet 中的 updateStrategy.rollingUpdate.maxUnavailable 從 1 更新為 100%。

      這是必要步驟，因為某些 DaemonSet pod 會在 NotReady 節點上執行。

      kubectl --kubeconfig=ADMIN_KUBECONFIG -n kube-system \
    edit daemonset metallb-speaker
    5. 重新啟動 metallb-speaker DaemonSet，以便擷取新的成員清單： 
      kubectl --kubeconfig=ADMIN_KUBECONFIG -n kube-system \
    rollout restart daemonset metallb-speaker

      幾分鐘後，管理員外掛程式節點會再次變成 Ready，遷移作業即可繼續進行。

    6. 如果初始 gkectl 指令在超過 3 小時後逾時，請重新執行 gkectl update，繼續執行失敗的遷移作業。
    設定、操作 1.12 以上版本、1.13 以上版本、1.14 以上版本、1.15 以上版本、1.16 以上版本、1.28 以上版本、1.29 以上版本、1.30 以上版本

    由於資料儲存庫和資料磁碟名稱過長，非高可用性管理員叢集的叢集備份作業失敗

    嘗試備份非 HA 管理員叢集時，由於資料存放區和資料磁碟名稱的總長度超過字元長度上限，備份作業會失敗。

    資料存放區名稱的長度上限為 80 個字元。
    非高可用性管理員叢集的備份路徑採用「__」的命名語法。因此，如果串連的名稱超過長度上限，備份資料夾就會建立失敗

    解決方法：

    將資料存放區或資料磁碟重新命名為較短的名稱。
    確認資料存放區和資料磁碟名稱的總長度未超過字元長度上限。
    升級 1.28、1.29、1.30

    執行 gkectl repair admin-master 指令後，管理員控制層節點顯示的版本可能比預期版本舊。

    發生這個問題的原因是，用於修復 HA 管理員控制層節點的備份 VM 範本在升級後，不會在 vCenter 中重新整理，因為如果機器名稱維持不變，系統就不會在建立機器時複製備份 VM 範本。

    解決方法：

    1. 找出使用舊版 Kubernetes 的機器名稱： 
          kubectl get machine -o wide --kubeconfig=ADMIN_KUBECONFIG
    2. 移除 onprem.cluster.gke.io/prevented-deletion 註解： 
          kubectl edit machine MACHINE_NAME --kubeconfig=ADMIN_KUBECONFIG

      儲存編輯內容。

    3. 執行下列指令來刪除機器： 
          kubectl delete machine MACHINE_NAME --kubeconfig=ADMIN_KUBECONFIG

      系統會建立新機器，並使用正確版本。
    設定 1.30.0

    使用 Terraform 更新使用者叢集或節點集區時，Terraform 可能會嘗試將 vCenter 欄位設為空值。

    如果叢集不是使用 Terraform 建立，就可能發生這個問題。

    解決方法：

    為避免發生非預期的更新，請先確認更新安全無虞，再執行 terraform apply，詳情請參閱下列說明：

    1. 執行 terraform plan
    2. 在輸出內容中，檢查 vCenter 欄位是否設為 nil。
    3. 如果任何 vCenter 欄位設為空值，請在 Terraform 設定中，按照 Terraform 說明文件，將 vcenter 新增至 ignore_changes 清單。因此無法更新這些欄位。
    4. 再次執行 terraform plan 並檢查輸出內容，確認更新符合預期
    更新 1.13、1.14、1.15、1.16

    建立、更新或升級 kubeception 使用者叢集的控制層節點後，系統會在管理員叢集建立或升級至受影響版本時，逐一重新啟動這些節點。對於有 3 個控制層節點的 kubeception 叢集，這不應導致控制層停機，只會影響管理員叢集作業的執行時間。
    安裝、升級及更新 1.31

    在 Google Distributed Cloud 1.31 版中，嘗試建立自訂資源 (例如叢集 (所有類型) 和工作負載) 時，可能會發生錯誤。這個問題是由 Kubernetes 1.31 中導入的重大變更所致，該變更會導致自訂資源定義中的 caBundle 欄位無法從有效狀態轉換為無效狀態。如要進一步瞭解這項異動，請參閱 Kubernetes 1.31 變更記錄。

    在 Kubernetes 1.31 之前，caBundle 欄位通常會設為 \n 的臨時值，因為在舊版 Kubernetes 中，API 伺服器不允許 CA 組合內容為空。使用 \n 是合理的解決方法，可避免混淆，因為 cert-manager 通常會在稍後更新 caBundle。

    如果 caBundle 已從無效狀態修補為有效狀態，應該就不會有問題。不過，如果自訂資源定義重新協調至 \n (或其他無效值)，您可能會遇到下列錯誤：

    ...Invalid value: []byte{0x5c, 0x6e}: unable to load root certificates: unable to parse bytes as PEM block]

    解決方法

    如果您有自訂資源定義，其中 caBundle 設為無效值，可以安全地完全移除 caBundle 欄位。這麼做應該可以解決問題。
    作業系統 1.31

    將使用 Container-Optimized OS (COS) OS 映像檔的叢集升級至 1.31 時，即使 cloud-init 完成且沒有錯誤，cloud-init status 指令仍會失敗。

    解決方法：

    執行下列指令，檢查 cloud-init 的狀態：

        systemctl show -p Result cloud-final.service

    如果輸出內容與下列內容相似，表示 cloud-init 已順利完成：

        Result=success
    升級 1.28

    將叢集升級至 1.28 時，如果管理員工作站磁碟大小小於 100 GB，執行管理員工作站前置檢查時，gkectl prepare 指令會失敗。在這種情況下，指令會顯示類似以下的錯誤訊息：

        Workstation Hardware: Workstation hardware requirements are not satisfied

    在 1.28 版中，管理工作站的磁碟大小必要條件已從 50 GB 增加至 100 GB。

    解決方法：

    1. 復原管理員工作站。
    2. 更新管理員工作站設定檔，將磁碟大小增加至至少 100 GB。
    3. 升級管理員工作站。
    升級 1.30

    gkectl upgrade 指令會傳回有關 netapp storageclass 的錯誤訊息，但內容不正確。錯誤訊息類似以下內容： 

        detected unsupported drivers:
      csi.trident.netapp.io

    解決方法：

    使用 `--skip-pre-upgrade-checks` 標記執行 gkectl upgrade。
    身分識別 所有版本

    在使用者叢集上輪替憑證授權單位 (CA) 憑證後，ClientConfig 中的 spec.certificateAuthorityData 欄位會包含無效的 CA 憑證，導致無法向叢集進行驗證。

    解決方法：

    在下次進行 gcloud CLI 驗證前，請手動更新 ClientConfig 中的 spec.certificateAuthorityData 欄位，填入正確的 CA 憑證。

    1. 從管理員叢集 kubeconfig 的 certificate-authority-data 欄位複製叢集 CA 憑證。
    2. 編輯 ClientConfig，並將 CA 憑證貼到 spec.certificateAuthorityData 欄位。 
          kubectl edit clientconfig default -n kube-public --kubeconfig USER_CLUSTER_KUBECONFIG
    更新 1.28 以上版本

    如果您在叢集設定檔中移除 loadBalancer.vips.ingressVIP 欄位，停用隨附的 Ingress，MetalLB 預檢檢查的錯誤會導致叢集更新失敗，並顯示「invalid user ingress vip: invalid IP」錯誤訊息。

    解決方法：

    請忽略這則錯誤訊息。
    使用下列其中一種方法略過預檢：

    • 在 gkectl update cluster 指令中新增 --skip-validation-load-balancer 旗標。
    • 使用以下項目為 onpremusercluster 物件加上註解： onprem.cluster.gke.io/server-side-preflight-skip: skip-validation-load-balancer
      • 。
    VMware、升級 1.16

    在叢集升級期間，由於 vCenter 中缺少反親和性群組 (AAG) 規則，機器物件可能會停滯在 `Creating` 階段，且無法連結至節點物件。

    如果描述有問題的機器物件，您可能會看到重複的訊息，例如「Reconfigure DRS rule task "task-xxxx" complete」(重新設定 DRS 規則工作「task-xxxx」完成)

        kubectl --kubeconfig KUBECONFIG describe machine MACHINE_OBJECT_NAME

    解決方法：

    在管理員叢集設定和使用者叢集設定中，停用反親和性群組設定，並觸發強制更新指令，解除叢集升級封鎖：

        gkectl update admin --config ADMIN_CLUSTER_CONFIG_FILE --kubeconfig ADMIN_CLUSTER_KUBECONFIG --force
    
        gkectl update cluster --config USER_CLUSTER_CONFIG_FILE --kubeconfig USER_CLUSTER_KUBECONFIG --force
    遷移 1.29、1.30

    將使用者叢集遷移至 Controlplane V2 時，如果曾啟用 永遠開啟的密碼加密，遷移程序會無法正確處理密碼加密金鑰。因此，新的 Controlplane V2 叢集無法解密密鑰。如果下列指令的輸出內容不為空白，表示永久密碼加密功能已在某個時間點啟用，且叢集受到這個問題影響：

        kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
      get onpremusercluster USER_CLUSTER_NAME \
      -n USER_CLUSTER_NAME-gke-onprem-mgmt \
      -o jsonpath={.spec.secretsEncryption}

    如果已開始遷移，但遷移失敗，請聯絡 Google 支援團隊。否則，請在遷移作業前 停用永久密碼加密功能，並解密密碼。
    遷移 1.29.0-1.29.600、1.30.0-1.30.100

    如果管理員叢集在 1.14 版或更早版本中啟用永遠開啟的密碼加密功能，並從舊版一路升級至受影響的 1.29 和 1.30 版，當管理員叢集從非高可用性遷移至高可用性時，遷移程序無法正確處理密碼加密金鑰。因此，新的高可用性管理員叢集無法解密密碼。

    如要檢查叢集是否可能使用舊格式的金鑰，請按照下列步驟操作：

        kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG get secret -n kube-system admin-master-component-options -o jsonpath='{.data.data}' | base64 -d | grep -oP '"GeneratedKeys":\[.*?\]'

    如果輸出內容顯示空白金鑰 (如下所示)，則表示叢集會受到這個問題影響：

        "GeneratedKeys":[{"KeyVersion":"1","Key":""}]

    如果已開始遷移，但遷移失敗，請聯絡 Google 支援團隊。

    否則，請先輪替加密金鑰，再開始遷移。
    升級 1.16、1.28、1.29、1.30

    使用 gkeadm upgrade admin-workstation 指令升級管理員工作站時，credential.yaml 檔案會錯誤地重新產生。使用者名稱和密碼欄位為空白。 此外，privateRegistry 鍵含有錯字。

    admin-cluster.yaml 檔案中也有相同的 privateRegistry 鍵拼字錯誤。
    由於系統會在管理員叢集升級程序中重新產生 credential.yaml 檔案，因此即使先前已修正錯字，升級後仍會出現錯字。

    解決方法：

    • 更新 credential.yaml 中的私有登錄機碼名稱，使其與 admin-cluster.yaml 中的 privateRegistry.credentials.fileRef.entry 相符。
    • 在 credential.yaml 中更新私人登錄檔的使用者名稱和密碼。
    升級 1.16 以上版本

    升級使用者叢集時，升級前協調作業可能需要較長的時間，超過定義的逾時時間，導致升級失敗。錯誤訊息如下所示：

    Failed to reconcile the user cluster before upgrade: the pre-upgrade reconcile failed, error message:
failed to wait for reconcile to complete: error: timed out waiting for the condition,
message: Cluster reconcile hasn't finished yet, please fix that before
rerun the upgrade.

    升級前協調作業的逾時時間為 5 分鐘，加上使用者叢集中每個節點集區 1 分鐘。

    解決方法：

    確認 gkectl diagnose cluster 指令順利執行。
    在 gkectl upgrade cluster 指令中加入 --skip-reconcile-before-preflight 旗標，即可略過升級前協調作業。例如：

    gkectl upgrade cluster --skip-reconcile-before-preflight --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
--config USER_CLUSTER_CONFIG_FILE
    更新 1.16、1.28.0-1.28.800、1.29.0-1.29.400、1.30.0

    使用 gkectl update cluster 更新使用者叢集的 dataplaneV2.forwardMode 欄位時，變更只會在 ConfigMap 中更新，anetd DaemonSet 必須重新啟動才會採用設定變更，因此變更不會套用。

    解決方法：

    gkectl update cluster 指令完成後，您會看到 Done updating the user cluster 的輸出內容。看到該訊息後，請執行下列指令，重新啟動 anetd DaemonSet 以納入設定變更：

    kubectl --kubeconfig USER_CLUSTER_KUBECONFIG rollout restart daemonset anetd

    重新啟動後，請檢查 DaemonSet 是否已準備就緒：

    kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get daemonset anetd

    在上述指令的輸出結果中，確認 DESIRED 欄中的數字與 READY 欄中的數字相符。
    升級 1.16

    在 1.16 至 1.28 的使用者叢集升級期間，系統會備份管理員叢集。管理叢集備份程序會顯示「etcdctl: command not found」錯誤訊息。使用者叢集升級成功，且管理員叢集維持正常狀態。唯一的問題是管理員叢集上的中繼資料檔案未備份。

    問題原因是 1.28 版新增了 etcdctl 二進位檔，但 1.16 節點無法使用。

    管理員叢集備份作業包含多個步驟，包括擷取 etcd 快照，然後為管理員叢集寫入中繼資料檔案。由於在 etcd Pod 中執行 exec 後仍可觸發備份，因此 etcd 備份仍會成功。etcdctl但由於中繼資料檔案仍須依賴節點上安裝的 etcdctl 二進位檔，因此寫入作業會失敗。不過，中繼資料檔案備份不會阻礙備份作業，因此備份程序仍會成功，使用者叢集升級也是如此。

    解決方法：

    如要備份中繼資料檔案，請按照「使用 gkectl 備份及還原管理員叢集」一文的說明，使用與管理員叢集版本相符的 gkectl 版本，觸發個別管理員叢集備份作業。
    安裝 1.16-1.29

    建立設定為手動負載平衡的使用者叢集時，即使已停用隨附的 Ingress，仍會發生 gkectl check-config 失敗，指出 ingressHTTPNodePort 值必須至少為 30000。

    無論 ingressHTTPNodePort 和 ingressHTTPSNodePort 欄位是否已設定或留空，都會發生這個問題。

    解決方法：

    如要解決這個問題，請忽略 gkectl check-config 傳回的結果。如要停用隨附 Ingress，請參閱 停用隨附 Ingress。
    更新 1.29.0

    使用高可用性 (HA) 管理員叢集時，如果遷移後有 0 或 1 個管理員叢集節點沒有角色，就會發生 PodDisruptionBudget (PDB) 問題。如要檢查是否有沒有角色的節點物件，請執行下列指令：

    kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG get nodes -o wide

    如果遷移後有兩個以上的節點物件沒有角色，則 PDB 並未設定錯誤。

    症狀：

    管理員叢集診斷的輸出內容包含下列資訊：

    Checking all poddisruptionbudgets...FAILURE
  Reason: 1 pod disruption budget error(s).
  Unhealthy Resources:
  PodDisruptionBudget metrics-server: gke-managed-metrics-server/metrics-server might be configured incorrectly: the total replicas(1) should be larger than spec.MinAvailable(1).

    解決方法：

    執行下列指令即可刪除 PDB：

    kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG delete pdb metrics-server -n gke-managed-metrics-server
    安裝、升級及更新 1.28.0-1.28.600,1.29.0-1.29.100

    在極少數的競爭條件下，二進位授權 Webhook 和 gke-connect Pod 的安裝順序不正確，可能會導致節點無法達到就緒狀態，進而造成使用者叢集建立作業停滯。在受影響的情況下，節點無法達到就緒狀態，可能會導致使用者叢集建立作業停滯。如果發生這種情況，系統會顯示下列訊息：

         Node pool is not ready: ready condition is not true: CreateOrUpdateNodePool: 2/3 replicas are ready

    解決方法：

    1. 從設定檔中移除 Binary Authorization 設定。如需設定操作說明，請參閱 VMware 中 GKE 的二進位授權第 2 天安裝指南。
    2. 如要在目前的叢集建立程序中解除封鎖不正常的節點，請使用下列指令，暫時移除使用者叢集中的二進位授權 Webhook 設定。 
              kubectl --kubeconfig USER_KUBECONFIG delete ValidatingWebhookConfiguration binauthz-validating-webhook-configuration
      啟動程序完成後，即可重新新增下列 Webhook 設定。 
      apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  name: binauthz-validating-webhook-configuration
webhooks:
- name: "binaryauthorization.googleapis.com"
  namespaceSelector:
    matchExpressions:
    - key: control-plane
      operator: DoesNotExist
  objectSelector:
    matchExpressions:
    - key: "image-policy.k8s.io/break-glass"
      operator: NotIn
      values: ["true"]
  rules:
  - apiGroups:
    - ""
    apiVersions:
    - v1
    operations:
    - CREATE
    - UPDATE
    resources:
    - pods
    - pods/ephemeralcontainers
  admissionReviewVersions:
  - "v1beta1"
  clientConfig:
    service:
      name: binauthz
      namespace: binauthz-system
      path: /binauthz
    # CA Bundle will be updated by the cert rotator.
    caBundle: Cg==
  timeoutSeconds: 10
  # Fail Open
  failurePolicy: "Ignore"
  sideEffects: None
    升級 1.16、1.28、1.29

    升級使用者叢集時，如果使用者叢集中的鏡像機器物件包含 deletionTimestamp，升級作業可能會停滯。如果升級作業停滯，系統會顯示下列錯誤訊息：

        machine is still in the process of being drained and subsequently removed

    如果您先前嘗試在使用者叢集的鏡像機器中執行 gkectl delete machine，修復使用者控制層節點，就可能發生這個問題。

    解決方法：

    1. 取得鏡像機器的物件，並儲存至本機檔案以進行備份。
    2. 執行下列指令，從鏡像機器刪除終結器，並等待系統從使用者叢集刪除該機器。
          kubectl --kubeconfig ADMIN_KUBECONFIG patch machine/MACHINE_OBJECT_NAME -n USER_CLUSTER_NAME-gke-onprem-mgmt -p '{"metadata":{"finalizers":[]}}' --type=merge
    3. 按照「 Controlplane V2 使用者叢集控制層節點」一節中的步驟，在控制層節點上觸發節點修復作業，以便將正確的來源機器規格重新同步至使用者叢集。
    4. 重新執行 gkectl upgrade cluster，繼續升級程序
    設定、安裝 1.15、1.16、1.28、1.29

    如果是高可用性管理員叢集或 ControlPlane V2 使用者叢集，控制層 VIP 必須與其他叢集節點位於同一個子網路。否則，kubelet 無法使用控制層 VIP 與 API 伺服器通訊，因此叢集建立作業會失敗。

    解決方法：

    建立叢集前，請確保控制層 VIP 與其他叢集節點位於相同的子網路。
    安裝、升級、更新 1.29.0 - 1.29.100

    建立/升級叢集失敗，且 vsphere CSI Pod 發生錯誤，指出 vCenter 使用者名稱無效。這是因為所用的使用者名稱不是完整網域名稱。vsphere-csi-controller Pod 中的錯誤訊息如下：

        GetCnsconfig failed with err: username is invalid, make sure it is a fully qualified domain username

    只有 1.29 以上版本會發生這個問題，因為 vSphere CSI 驅動程式新增了驗證功能，可強制使用完整網域使用者名稱。

    解決方法：

    在憑證設定檔中，使用 vCenter 使用者名稱的完整網域名稱。舉例來說，請使用「username1@example.com」，而非「username1」。
    升級、更新 1.28.0 - 1.28.500

    從 1.16 升級管理員叢集至 1.28 時，新管理員主機的啟動程序可能無法產生控制層憑證。這是因為 1.28 以上版本中，Kubernetes API 伺服器產生憑證的方式有所變更。如果叢集是使用 1.10 以下版本建立，並升級至 1.16，且升級前未輪替葉子憑證，就會發生這個問題。

    如要判斷管理員叢集升級失敗是否由這個問題所致，請按照下列步驟操作：

    1. 使用 SSH 連線至失敗的管理員主機。
    2. 開啟 /var/log/startup.log，然後搜尋類似下列內容的錯誤：
    Error adding extensions from section apiserver_ext
801B3213B57F0000:error:1100007B:X509 V3 routines:v2i_AUTHORITY_KEYID:unable to get issuer keyid:../crypto/x509/v3_akid.c:177:
801B3213B57F0000:error:11000080:X509 V3 routines:X509V3_EXT_nconf_int:error in extension:../crypto/x509/v3_conf.c:48:section=apiserver_ext, name=authorityKeyIdentifier, value=keyid>

    解決方法：

    1. 使用 SSH 連線至管理主機。詳情請參閱「使用 SSH 連線至管理員叢集節點」。
    2. 建立副本 /etc/startup/pki-yaml.sh 並命名為 /etc/startup/pki-yaml-copy.sh
    3. 編輯「/etc/startup/pki-yaml-copy.sh」。在下列擴充功能的區段中，找出 authorityKeyIdentifier=keyidset 並變更為 authorityKeyIdentifier=keyid,issuer：apiserver_ext、client_ext、etcd_server_ext 和 kubelet_server_ext。例如：
            [ apiserver_ext ]
      keyUsage = critical, digitalSignature, keyEncipherment
      extendedKeyUsage=serverAuth
      basicConstraints = critical,CA:false
      authorityKeyIdentifier = keyid,issuer
      subjectAltName = @apiserver_alt_names
    4. 儲存對「/etc/startup/pki-yaml-copy.sh」所做的變更。
    5. 使用文字編輯器開啟 /opt/bin/master.sh，尋找並將所有 /etc/startup/pki-yaml.sh 換成 /etc/startup/pki-yaml-copy.sh，然後儲存變更。
    6. 執行 /opt/bin/master.sh 產生憑證，並完成機器啟動。
    7. 再次執行 gkectl upgrade admin，升級管理員叢集。
    8. 升級完成後，請按照「開始輪替」一文的說明，輪替管理員和使用者叢集的葉子憑證。
    9. 憑證輪替完成後，請對 /etc/startup/pki-yaml-copy.sh 進行與先前相同的編輯，然後執行 /opt/bin/master.sh。
    設定 1.29.0

    當您執行 gkectl 建立、更新或升級已啟用 Dataplane V2 的叢集時，系統會輸出下列錯誤警告訊息：

    WARNING: Your user cluster is currently running our original architecture with
[DataPlaneV1(calico)]. To enable new and advanced features we strongly recommend
to update it to the newer architecture with [DataPlaneV2] once our migration
tool is available.

    gkectl 存在錯誤，只要未使用 dataplaneV2.forwardMode，即使您已在叢集設定檔中設定 enableDataplaneV2: true，系統一律會顯示這項警告。

    解決方法：

    您可以放心忽略這則警告。
    設定 1.28.0-1.28.400、1.29.0

    建立高可用性管理員叢集時，前置檢查會顯示下列錯誤訊息：

    - Validation Category: Network Configuration
    - [FAILURE] CIDR, VIP and static IP (availability and overlapping): needed
    at least X+1 IP addresses for admin cluster with X nodes

    1.28 以上版本的高可用性管理員叢集不再有附加元件節點，因此不適用這項規定。此外，由於管理員叢集設定檔的 network.controlPlaneIPBlock 區段中指定了 3 個管理員叢集控制層節點 IP，因此 IP 區塊檔案中的 IP 僅適用於 kubeception 使用者叢集控制層節點。

    解決方法：

    如要在非固定版本中略過不正確的預檢，請在 gkectl 指令中加入 --skip-validation-net-config。
    作業 1.29.0-1.29.100

    如果您 從非高可用性管理員叢集遷移至高可用性管理員叢集，管理員叢集中的 Connect 代理程式會與 gkeconnect.googleapis.com 中斷連線，並顯示「Failed to verify JWT signature」錯誤。這是因為在遷移期間，KSA 簽署金鑰會變更，因此需要重新註冊，才能重新整理 OIDC JWK。

    解決方法：

    如要將管理員叢集重新連線至 Google Cloud，請按照下列步驟操作，觸發重新註冊：

    首先，請取得 gke-connect 部署作業名稱：

    kubectl --kubeconfig KUBECONFIG get deployment -n gke-connect

    刪除 gke-connect 部署作業：

    kubectl --kubeconfig KUBECONFIG delete deployment GKE_CONNECT_DEPLOYMENT -n gke-connect

    如要觸發 onprem-admin-cluster-controller 的強制對帳，請在 onpremadmincluster CR 中加入「force-reconcile」註解：

    kubectl --kubeconfig KUBECONFIG patch onpremadmincluster ADMIN_CLUSTER_NAME -n kube-system --type merge -p '
metadata:
  annotations:
    onprem.cluster.gke.io/force-reconcile: "true"
'

    這個概念是，如果找不到可用的現有 gke-connect 部署作業，onprem-admin-cluster-controller 一律會重新部署 gke-connect 部署作業，並重新註冊叢集。

    完成解決方法後 (控制器可能需要幾分鐘才能完成調解)，您可以確認 gke-connect-agent 記錄中已沒有「Failed to verify JWT signature」400 錯誤：

    kubectl --kubeconfig KUBECONFIG logs GKE_CONNECT_POD_NAME -n gke-connect
    安裝、作業系統 1.28.0-1.28.500、1.29.0

    Google Distributed Cloud 會在 Docker 設定中指定專屬子網路 --bip=169.254.123.1/24 做為 Docker 橋接器 IP，避免保留預設的 172.17.0.1/16 子網路。不過，在 1.28.0-1.28.500 和 1.29.0 版中，由於 COS 作業系統映像檔發生迴歸，Google Distributed Cloud 自訂 Docker 設定後，Docker 服務並未重新啟動。因此，Docker 會選擇預設的 172.17.0.1/16 做為橋接器 IP 位址子網路。如果該 IP 位址範圍內已有工作負載在執行，可能會導致 IP 位址衝突。

    解決方法：

    如要解決這個問題，請重新啟動 Docker 服務：

    sudo systemctl restart docker

    確認 Docker 選擇的橋接 IP 位址是否正確：

    ip a | grep docker0

    重新建立 VM 後，這項解決方案就會失效。每當重新建立 VM 時，您都必須重新套用這項解決方法。
    update 1.28.0-1.28.400、1.29.0-1.29.100

    受影響版本 OS 映像檔未包含標準 CNI 二進位檔 bridge, ipvlan, vlan, macvlan, dhcp, tuning, host-local, ptp, portmap。這些 CNI 二進位檔不會由資料平面 v2 使用，但可用於多個網路介面功能中的其他網路介面。

    使用這些 CNI 外掛程式時，多個網路介面無法運作。

    解決方法：

    如果您使用這項功能，請升級至修正問題的版本。
    update 1.15、1.16、1.28

    在叢集節點上安裝 multipathd 會干擾 vSphere CSI 驅動程式，導致使用者工作負載無法啟動。

    解決方法：

    • 停用「multipathd」
    更新 1.15、1.16

    如果管理員叢集中的部分必要設定為空白 (因為略過驗證)，管理員叢集 Webhook 可能會封鎖這些設定。舉例來說，如果現有管理員叢集未設定 gkeConnect 欄位，使用 gkectl update admin 指令新增該欄位時，可能會收到下列錯誤訊息：

    admission webhook "vonpremadmincluster.onprem.cluster.gke.io" denied the request: connect: Required value: GKE connect is required for user clusters
    Kubernetes API 伺服器和 Webhook 之間偶爾可能會發生通訊問題。發生這種情況時，您可能會看到下列錯誤訊息：
    failed to apply OnPremAdminCluster 'kube-system/gke-admin-btncc': Internal error occurred: failed calling webhook "monpremadmincluster.onprem.cluster.gke.io": failed to call webhook: Post "https://onprem-admin-cluster-controller.kube-system.svc:443/mutate-onprem-cluster-gke-io-v1alpha1-onpremadmincluster?timeout=10s": dial tcp 10.96.55.208:443: connect: connection refused

    解決方法：

    如果遇到上述任一錯誤，請根據您的版本採取下列任一解決方法：
    • 如果是 1.15 版管理員叢集，請執行 gkectl update admin 指令並加上 --disable-admin-cluster-webhook 標記。例如： 
              gkectl update admin --config ADMIN_CLUSTER_CONFIG_FILE --kubeconfig ADMIN_CLUSTER_KUBECONFIG --disable-admin-cluster-webhook
    • 如果是 1.16 版管理叢集，請執行 gkectl update admin 指令並加上 --force 標記。例如： 
              gkectl update admin --config ADMIN_CLUSTER_CONFIG_FILE --kubeconfig ADMIN_CLUSTER_KUBECONFIG --force
    設定 1.15.0-1.15.10、1.16.0-1.16.6、1.28.0-1.28.200

    如果您將使用手動負載平衡器 (loadBalancer.kind 設為 "ManualLB")，則在 1.16 以上版本中，您不需要為高可用性 (HA) 管理員叢集設定設定檔中的 loadBalancer.manualLB 區段。但如果這個區段空白，Google Distributed Cloud 會為所有 NodePort 指派預設值，包括 manualLB.controlPlaneNodePort，導致叢集建立作業失敗，並顯示下列錯誤訊息：

    - Validation Category: Manual LB
  - [FAILURE] NodePort configuration: manualLB.controlPlaneNodePort must
   not be set when using HA admin cluster, got: 30968

    解決方法：

    在 HA 管理員叢集的管理員叢集設定中指定 manualLB.controlPlaneNodePort: 0：

    loadBalancer:
  ...
  kind: ManualLB
  manualLB:
    controlPlaneNodePort: 0
  ...
    儲存空間 1.28.0-1.28.100

    Ubuntu OS 映像檔缺少 nfs-common，可能會導致使用 NetApp 等 NFS 相關驅動程式的客戶發生問題。

    如果升級至 1.28 後，記錄包含類似下列的項目，則您會受到這個問題影響： 
    Warning FailedMount 63s (x8 over 2m28s) kubelet MountVolume.SetUp failed for volume "pvc-xxx-yyy-zzz" : rpc error: code = Internal desc = error mounting NFS volume 10.0.0.2:/trident_pvc_xxx-yyy-zzz on mountpoint /var/lib/kubelet/pods/aaa-bbb-ccc/volumes/kubernetes.io~csi/pvc-xxx-yyy-zzz/mount: exit status 32".

    解決方法：

    確認節點可以從 Canonical 下載套件。

    接下來，請將下列 DaemonSet 套用至叢集，安裝 nfs-common：

    apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: install-nfs-common
  labels:
    name: install-nfs-common
  namespace: kube-system
spec:
  selector:
    matchLabels:
      name: install-nfs-common
  minReadySeconds: 0
  updateStrategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 100%
  template:
    metadata:
      labels:
        name: install-nfs-common
    spec:
      hostPID: true
      hostIPC: true
      hostNetwork: true
      initContainers:
      - name: install-nfs-common
        image: ubuntu
        imagePullPolicy: IfNotPresent
        securityContext:
          privileged: true
        command:
        - chroot
        - /host
        - bash
        - -c
        args:
        - |
          apt install -y nfs-common
        volumeMounts:
        - name: host
          mountPath: /host
      containers:
      - name: pause
        image: gcr.io/gke-on-prem-release/pause-amd64:3.1-gke.5
        imagePullPolicy: IfNotPresent
      volumes:
      - name: host
        hostPath:
          path: /
    儲存空間 1.28.0-1.28.100

    管理員叢集中的 SPBM 支援 1.28.0 以上版本。但設定檔範本中缺少 vCenter.storagePolicyName 欄位。

    解決方法：

    如要為管理員叢集設定儲存空間政策，請在管理員叢集設定檔中新增 `vCenter.storagePolicyName` 欄位。請參閱操作說明。
    記錄和監控 1.28.0-1.28.100

    最近新增的 API kubernetesmetadata.googleapis.com 不支援 VPC-SC。這會導致中繼資料收集代理程式無法在 VPC-SC 下連線至這個 API，進而導致缺少指標中繼資料標籤。

    解決方法：

    在 `kube-system` 命名空間中，將 CR `stackdriver` 的 `featureGates.disableExperimentalMetadataAgent` 欄位設為 `true`，方法是執行下列指令：

    `kubectl -n kube-system patch stackdriver stackdriver -p '{"spec":{"featureGates":{"disableExperimentalMetadataAgent":true}}}'`

    然後執行

    `kubectl -n kube-system patch deployment stackdriver-operator -p '{"spec":{"template":{"spec":{"containers":[{"name":"stackdriver-operator","env":[{"name":"ENABLE_LEGACY_METADATA_AGENT","value":"true"}]}]}}}}'`

    升級、更新 1.15.0-1.15.7、1.16.0-1.16.4、1.28.0

    如果啟用 ControlPlane V2 的管理員叢集和任何使用者叢集使用不同的 vSphere 憑證 (例如更新管理員叢集的 vSphere 憑證後)，叢集 API 控制器可能會在重新啟動後無法連線至 vCenter。查看在管理叢集的 `kube-system` 命名空間中執行的 clusterapi-controller 記錄，

    kubectl logs -f -l component=clusterapi-controllers -c vsphere-controller-manager \
    -n kube-system --kubeconfig KUBECONFIG
     如果記錄包含類似下列內容的項目，表示您受到這個問題影響： 
    E1214 00:02:54.095668       1 machine_controller.go:165] Error checking existence of machine instance for machine object gke-admin-node-77f48c4f7f-s8wj2: Failed to check if machine gke-admin-node-77f48c4f7f-s8wj2 exists: failed to find datacenter "VSPHERE_DATACENTER": datacenter 'VSPHERE_DATACENTER' not found

    解決方法：

    更新 vSphere 憑證，確保管理員叢集和所有已啟用 Controlplane V2 的使用者叢集都使用相同的 vSphere 憑證。
    記錄和監控 1.14

    Prometheus 可能會回報類似下列範例的警示：

    Alert Name: cluster:gke-admin-test1: Etcd cluster kube-system/kube-etcd: 100% of requests for Watch failed on etcd instance etcd-test-xx-n001.

    如要檢查這則快訊是否為可忽略的誤判，請完成下列步驟：

    1. 請根據警示訊息中提供的 grpc_method，檢查原始 grpc_server_handled_total 指標。在本例中，請檢查 grpc_code 的 Watch 標籤。

      您可以使用 Cloud Monitoring 和下列 MQL 查詢來檢查這項指標： 
      fetch
    k8s_container | metric 'kubernetes.io/anthos/grpc_server_handled_total' | align rate(1m) | every 1m
    2. 如果程式碼不是下列其中之一，可以放心忽略 OK 以外的所有程式碼警示：
      Unknown|FailedPrecondition|ResourceExhausted|Internal|Unavailable|DataLoss|DeadlineExceeded

    解決方法：

    如要設定 Prometheus 忽略這些誤判警報，請查看下列選項：

    1. 透過 Alert Manager UI 忽略快訊。
    2. 如果無法關閉警報，請按照下列步驟操作，避免系統誤判：
      1. 將監控運算子縮減至 0 個副本，以便保留修改內容。
      2. 修改 prometheus-config configmap，並在 etcdHighNumberOfFailedGRPCRequests 警報設定中新增 grpc_method!="Watch"，如下列範例所示：
        • 原版： 
          rate(grpc_server_handled_total{cluster="CLUSTER_NAME",grpc_code!="OK",job=~".*etcd.*"}[5m])
        • 修改日期： 
          rate(grpc_server_handled_total{cluster="CLUSTER_NAME",grpc_code=~"Unknown|FailedPrecondition|ResourceExhausted|Internal|Unavailable|DataLoss|DeadlineExceeded",grpc_method!="Watch",job=~".*etcd.*"}[5m])
           將下列 CLUSTER_NAME 替換為叢集名稱。
      3. 重新啟動 Prometheus 和 Alertmanager Statefulset，即可套用新設定。
    3. 如果程式碼屬於其中一種有問題的情況，請檢查 etcd 記錄和 kube-apiserver 記錄，進一步進行偵錯。
    網路 1.16.0-1.16.2、1.28.0

    如果沒有流量，輸出 NAT 連線可能會在連線建立後 5 到 10 分鐘內遭到捨棄。

    由於連線追蹤只在傳入方向 (叢集的外部連線) 中重要，因此只有在連線一段時間未傳輸任何資訊，然後目的地端傳輸某些內容時，才會發生這個問題。如果輸出 NAT 的 Pod 一律會例項化訊息，就不會發生這個問題。

    發生這個問題的原因是 anetd 垃圾收集作業不慎移除了精靈認為未使用的 conntrack 項目。上游修正 最近已整合至 anetd，可修正此行為。


    解決方法：

    沒有簡單的解決方法，而且我們尚未發現 1.16 版有此行為的問題。如果發現長期連線因這個問題而中斷，解決方法是在與輸出 IP 位址相同的節點上使用工作負載，或持續在 TCP 連線上傳送訊息。
    作業 1.14、1.15、1.16

    如果您使用 expirationSeconds 建立 CertificateSigningRequest (CSR)，系統會忽略 expirationSeconds。

    解決方法：

    如果受到這個問題影響，您可以在使用者叢集設定檔中新增 disableNodeIDVerificationCSRSigning: true，然後執行 gkectl update cluster 指令，使用這項設定更新叢集，即可更新使用者叢集。
    網路、升級、更新 1.16.0-1.16.3

    如果您嘗試為現有叢集停用隨附的 Ingress，gkectl update cluster 指令會失敗，並顯示類似下列範例的錯誤：

    [FAILURE] Config: ingress IP is required in user cluster spec

    發生這項錯誤的原因是 gkectl 會在預檢期間檢查負載平衡器 Ingress IP 位址。雖然停用隨附的 Ingress 時不需要進行這項檢查，但如果 disableBundledIngress 設為 true，gkectl 前置檢查就會失敗。


    解決方法：

    更新叢集時，請使用 --skip-validation-load-balancer 參數，如以下範例所示：

    gkectl update cluster \
  --kubeconfig ADMIN_CLUSTER_KUBECONFIG --config USER_CLUSTER_CONFIG  \
  --skip-validation-load-balancer

    詳情請參閱如何為現有叢集停用隨附的 Ingress。
    升級、更新 1.13、1.14、1.15.0-1.15.6

    如果輪換管理員叢集憑證授權單位 (CA) 憑證，後續嘗試執行 gkectl update admin 指令都會失敗。傳回的錯誤訊息類似於下列內容：

    failed to get last CARotationStage: configmaps "ca-rotation-stage" not found

    解決方法：

    如果受到這個問題影響，可以使用 gkectl update admin 指令搭配 --disable-update-from-checkpoint 旗標，更新管理員叢集：

    gkectl update admin --config ADMIN_CONFIG_file \
    --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    --disable-update-from-checkpoint

    使用 --disable-update-from-checkpoint 旗標時，更新指令不會在叢集更新期間，將檢查點檔案做為基準真相。檢查點檔案仍會更新，以供日後使用。
    儲存空間 1.15.0-1.15.6、1.16.0-1.16.2

    在預檢期間，CSI 工作負載驗證檢查會在 default 命名空間中安裝 Pod。CSI 工作負載 Pod 會驗證 vSphere CSI 驅動程式是否已安裝，以及是否能動態佈建磁碟區。如果這個 Pod 未啟動，CSI 工作負載驗證檢查就會失敗。

    有幾個已知問題會導致這個 Pod 無法啟動：

    • 如果 Pod 未指定資源限制 (某些已安裝許可控制 Webhook 的叢集會發生這種情況)，Pod 就不會啟動。
    • 如果叢集已安裝 Cloud Service Mesh，且 default 命名空間已啟用自動 Istio 補充資訊植入功能，CSI 工作負載 Pod 就不會啟動。

    如果 CSI Workload Pod 未啟動，您會在前置驗證期間看到類似下列的逾時錯誤：

    - [FAILURE] CSI Workload: failure in CSIWorkload validation: failed to create writer Job to verify the write functionality using CSI: Job default/anthos-csi-workload-writer-<run-id> replicas are not in Succeeded phase: timed out waiting for the condition

    如要確認失敗是否是因為缺少 Pod 資源集所致，請執行下列指令來檢查 anthos-csi-workload-writer-<run-id> 工作狀態：

    kubectl describe job anthos-csi-workload-writer-<run-id>

    如果 CSI 工作負載 Pod 的資源限制未正確設定，作業狀態會包含類似以下的錯誤訊息：

    CPU and memory resource limits is invalid, as it are not defined for container: volume-tester

    如果 CSI 工作負載 Pod 因 Istio 補充資訊植入功能而無法啟動，可以暫時在 default 命名空間中停用自動 Istio 補充資訊植入功能。檢查命名空間的標籤，並使用下列指令刪除以 istio.io/rev 開頭的標籤：

    kubectl label namespace default istio.io/rev-

    如果 Pod 設定錯誤，請手動確認使用 vSphere CSI 驅動程式的動態磁碟區佈建功能是否正常運作：

    1. 建立使用 standard-rwo StorageClass 的 PVC。
    2. 建立使用 PVC 的 Pod。
    3. 確認 Pod 可以讀取/寫入磁碟區的資料。
    4. 確認運作正常後，請移除 Pod 和 PVC。

    如果使用 vSphere CSI 驅動程式的動態磁碟區佈建功能正常運作，請執行 gkectl diagnose 或 gkectl upgrade，並加上 --skip-validation-csi-workload 旗標，略過 CSI 工作負載檢查。
    作業 1.16.0-1.16.2

    登入 使用者管理的管理員工作站時，gkectl update cluster 指令可能會逾時，導致使用者叢集更新失敗。如果管理員叢集版本為 1.15，且您在執行 gkectl update cluster 之前執行 gkectl update admin，就會發生這種情況。發生這類故障時，嘗試更新叢集會看到下列錯誤： 

          Preflight check failed with failed to run server-side preflight checks: server-side preflight checks failed: timed out waiting for the condition
Preflight check failed with failed to run server-side preflight checks: server-side preflight checks failed: timed out waiting for the condition

    更新 1.15 管理員叢集時，系統會從叢集中移除觸發預檢的 validation-controller。如果嘗試更新使用者叢集，預檢作業會暫停，直到達到逾時時間為止。

    解決方法：

    1. 執行下列指令，重新部署 validation-controller： 
            gkectl prepare --kubeconfig ADMIN_KUBECONFIG --bundle-path BUNDLE_PATH --upgrade-platform
    2. 準備作業完成後，請再次執行 gkectl update cluster，更新使用者叢集。
    作業 1.16.0-1.16.2

    登入 使用者代管的管理工作站時，gkectl create cluster指令可能會逾時，導致使用者叢集建立失敗。如果管理員叢集版本為 1.15，就會發生這種情況。發生這類失敗時，嘗試建立叢集會看到下列錯誤： 

          Preflight check failed with failed to run server-side preflight checks: server-side preflight checks failed: timed out waiting for the condition
Preflight check failed with failed to run server-side preflight checks: server-side preflight checks failed: timed out waiting for the condition

    由於 validation-controller 是在 1.16 版中新增，因此使用 1.15 版管理員叢集時，負責觸發預檢的 validation-controller 會遺失。因此，嘗試建立使用者叢集時，預檢會暫停，直到達到逾時時間為止。

    解決方法：

    1. 執行下列指令來部署 validation-controller： 
            gkectl prepare --kubeconfig ADMIN_KUBECONFIG --bundle-path BUNDLE_PATH --upgrade-platform
    2. 準備作業完成後，請再次執行 gkectl create cluster，建立使用者叢集。
    升級、更新 1.16.0-1.16.2

    將管理員叢集從 1.15.x 版升級至 1.16.x 版，或在更新管理員叢集時新增 connect、stackdriver、cloudAuditLogging 或 gkeOnPremAPI 設定，管理員叢集 webhook 可能會拒絕這項作業。系統可能會顯示下列其中一則錯誤訊息：

    • "projects for connect, stackdriver and cloudAuditLogging must be the same when specified during cluster creation."
    • "locations for connect, gkeOnPremAPI, stackdriver and cloudAuditLogging must be in the same region when specified during cluster creation."
    • "locations for stackdriver and cloudAuditLogging must be the same when specified during cluster creation."

    更新或升級管理員叢集時，需要 onprem-admin-cluster-controller 在 Kind 叢集中調解管理員叢集。在 kind 叢集中還原管理員叢集狀態時，管理員叢集 webhook 無法區分 OnPremAdminCluster 物件是為了建立管理員叢集，還是為了繼續更新或升級作業。更新和升級時，系統會意外叫用部分僅限建立時的驗證。


    解決方法：

    將 onprem.cluster.gke.io/skip-project-location-sameness-validation: true 註解新增至 OnPremAdminCluster 物件：

    1. 編輯 onpremadminclusters 叢集資源： 
      kubectl edit onpremadminclusters ADMIN_CLUSTER_NAME -n kube-system –kubeconfig ADMIN_CLUSTER_KUBECONFIG
       取代下列項目：
      • ADMIN_CLUSTER_NAME：管理員叢集的名稱。
      • ADMIN_CLUSTER_KUBECONFIG：管理員叢集 kubeconfig 檔案的路徑。
    2. 新增 onprem.cluster.gke.io/skip-project-location-sameness-validation: true 註解，然後儲存自訂資源。
    3. 請根據管理員叢集類型，完成下列其中一個步驟：
      • 對於具有檢查點檔案的非 HA 管理員叢集：在更新指令中新增 disable-update-from-checkpoint 參數，或在升級指令中新增 `disable-upgrade-from-checkpoint` 參數。下次執行 update 或 upgrade 指令時，才需要這些參數： 
        • gkectl update admin --config ADMIN_CONFIG_file --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
  --disable-update-from-checkpoint
        • gkectl upgrade admin --config ADMIN_CONFIG_file --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
  --disable-upgrade-from-checkpoint
      • 如果是高可用性管理員叢集或檢查點檔案已停用： 照常更新或升級管理員叢集。更新或升級指令不需要額外參數。
    作業 1.16.0-1.16.2

    登入 使用者管理的管理員工作站時，gkectl delete cluster指令可能會逾時，導致使用者叢集刪除作業失敗。如果您先在使用者管理的管理員工作站上執行 gkectl，建立、更新或升級使用者叢集，就會發生這種情況。發生這類故障時，嘗試刪除叢集會看到下列錯誤：

          failed to wait for user cluster management namespace "USER_CLUSTER_NAME-gke-onprem-mgmt"
      to be deleted: timed out waiting for the condition

    刪除叢集時，系統會先刪除叢集中的所有物件。在建立、更新或升級期間建立的驗證物件刪除作業，會停滯在刪除階段。這是因為終結器會封鎖物件刪除作業，導致叢集刪除作業失敗。

    解決方法：

    1. 取得所有 Validation 物件的名稱： 
               kubectl  --kubeconfig ADMIN_KUBECONFIG get validations \
           -n USER_CLUSTER_NAME-gke-onprem-mgmt
    2. 針對每個 Validation 物件，執行下列指令，從 Validation 物件中移除終結器：
            kubectl --kubeconfig ADMIN_KUBECONFIG patch validation/VALIDATION_OBJECT_NAME \
        -n USER_CLUSTER_NAME-gke-onprem-mgmt -p '{"metadata":{"finalizers":[]}}' --type=merge

      從所有驗證物件移除終結器後，物件就會移除，使用者叢集刪除作業也會自動完成。你不需要採取其他行動。

    網路 1.15、1.16

    如果來源 Pod 和輸出 NAT 閘道 Pod 位於兩個不同的工作節點，來源 Pod 的流量就無法連線至任何外部服務。如果 Pod 位於同一部主機上，連線至外部服務或應用程式就會成功。

    啟用通道聚合時，vSphere 會捨棄 VXLAN 封包，導致發生這個問題。NSX 和 VMware 有個已知問題，只會透過已知的 VXLAN 連接埠 (4789) 傳送匯總流量。


    解決方法：

    將 Cilium 使用的 VXLAN 通訊埠變更為 4789：

    1. 編輯 cilium-config ConfigMap： 
      kubectl edit cm -n kube-system cilium-config --kubeconfig USER_CLUSTER_KUBECONFIG
    2. 在 cilium-config ConfigMap 中新增以下內容： 
      tunnel-port: 4789
    3. 重新啟動 anetd DaemonSet： 
      kubectl rollout restart ds anetd -n kube-system --kubeconfig USER_CLUSTER_KUBECONFIG

    叢集升級時，這項解決方法會還原。每次升級後，都必須重新設定。VMware 必須在 vSphere 中解決問題，才能永久修正。
    升級 1.15.0-1.15.4

    由於控制器產生的加密金鑰與管理員主資料磁碟上保留的金鑰不符，因此啟用 永遠開啟的密文加密時，從 1.14.x 升級至 1.15.x 的管理員叢集會失敗。gkectl upgrade admin 的輸出內容包含下列錯誤訊息： 

          E0926 14:42:21.796444   40110 console.go:93] Exit with error:
      E0926 14:42:21.796491   40110 console.go:93] Failed to upgrade the admin cluster: failed to create admin cluster: failed to wait for OnPremAdminCluster "admin-cluster-name" to become ready: failed to wait for OnPremAdminCluster "admin-cluster-name" to be ready: error: timed out waiting for the condition, message: failed to wait for OnPremAdminCluster "admin-cluster-name" to stay in ready status for duration "2m0s": OnPremAdminCluster "non-prod-admin" is not ready: ready condition is not true: CreateOrUpdateControlPlane: Creating or updating credentials for cluster control plane

    執行 kubectl get secrets -A --kubeconfig KUBECONFIG` 時會失敗，並顯示下列錯誤： 

          Internal error occurred: unable to transform key "/registry/secrets/anthos-identity-service/ais-secret": rpc error: code = Internal desc = failed to decrypt: unknown jwk

    解決方法

    如果您有管理員叢集的備份檔，請按照下列步驟操作，解決升級失敗的問題：

    1. 在管理員叢集設定檔中停用 secretsEncryption，然後使用下列指令更新叢集： 
      gkectl update admin --config ADMIN_CLUSTER_CONFIG_FILE --kubeconfig KUBECONFIG
    2. 建立新的管理員主 VM 後，請透過 SSH 連線至管理員主 VM，然後將資料磁碟上的新金鑰換成備份中的舊金鑰。金鑰位於管理主機的 /opt/data/gke-k8s-kms-plugin/generatedkeys 。
    3. 更新 /etc/kubernetes/manifests 中的 kms-plugin.yaml 靜態 Pod 資訊清單，將 --kek-id 更新為與原始加密金鑰中的 kid 欄位相符。
    4. 將 /etc/kubernetes/manifests/kms-plugin.yaml 移至其他目錄，然後移回，即可重新啟動 kms-plugin 靜態 Pod。
    5. 再次執行 gkectl upgrade admin，繼續升級管理員叢集。

    防止升級失敗

    如果您尚未升級，建議不要升級至 1.15.0-1.15.4。如果必須升級至受影響的版本，請在升級管理員叢集前執行下列步驟：

    1. 備份管理員叢集。
    2. 在管理員叢集設定檔中停用 secretsEncryption，然後使用下列指令更新叢集： 
      gkectl update admin --config ADMIN_CLUSTER_CONFIG_FILE --kubeconfig KUBECONFIG
    3. 升級管理員叢集。
    4. 重新啟用永久密碼加密。
    儲存空間 1.11-1.16

    Google Distributed Cloud 不支援磁碟的變更區塊追蹤 (CBT)。部分備份軟體會使用 CBT 功能追蹤磁碟狀態並執行備份，導致磁碟無法連線至執行 Google Distributed Cloud 的 VM。詳情請參閱 VMware 知識庫文章。


    解決方法：

    請勿備份 Google Distributed Cloud VM，因為第三方備份軟體可能會在磁碟上啟用 CBT。不必備份這些 VM。

    請勿在節點上啟用 CBT，因為這項變更不會在更新或升級後保留。

    如果您已啟用 CBT 的磁碟，請按照 VMware 知識庫文章中的「解決方案」步驟，停用 First Class Disk 的 CBT。
    儲存空間 1.14、1.15、1.16

    如果使用 Nutanix 儲存陣列為主機提供 NFSv3 共用，可能會發生資料損毀或 Pod 無法順利執行的問題。這個問題是由特定 VMware 和 Nutanix 版本之間的已知相容性問題所導致。詳情請參閱相關的 VMware 知識庫文章。


    解決方法：

    VMware 知識庫文章指出目前沒有解決方案，但這項資訊已過時。如要解決這個問題，請將主機上的 ESXi 更新至最新版本，並將儲存陣列上的 Nutanix 更新至最新版本。
    作業系統 1.13.10、1.14.6、1.15.3

    在某些 Google Distributed Cloud 版本中，節點上執行的 kubelet 版本與 Kubernetes 控制層不同。OS 映像檔預先載入的 kubelet 二進位檔使用不同版本，因此發生不符情況。

    下表列出已識別的版本不符情形：

    Google Distributed Cloud 版本 kubelet 版本 Kubernetes 版本
    1.13.10 v1.24.11-gke.1200 v1.24.14-gke.2100
    1.14.6 v1.25.8-gke.1500 v1.25.10-gke.1200
    1.15.3 v1.26.2-gke.1001 v1.26.5-gke.2100

    解決方法：

    因此你不必採取任何行動。不一致的只有 Kubernetes 修補程式版本，且這個版本差異並未造成任何問題。
    升級、更新 1.15.0-1.15.4

    如果管理員叢集的憑證授權單位 (CA) 版本大於 1，由於 Webhook 中的 CA 版本驗證，更新或升級會失敗。「gkectl upgrade/update」的輸出內容包含下列錯誤訊息：

        CAVersion must start from 1

    解決方法：

    • 在管理員叢集中縮減 auto-resize-controller 部署作業，即可停用節點大小自動調整功能。這是必要步驟，因為 1.15 版管理叢集自訂資源中導入的新欄位，可能會在 auto-resize-controller 中導致空指標錯誤。
       kubectl scale deployment auto-resize-controller -n kube-system --replicas=0 --kubeconfig KUBECONFIG
    • 執行加上 --disable-admin-cluster-webhook 旗標的 gkectl 指令。例如：
              gkectl upgrade admin --config ADMIN_CLUSTER_CONFIG_FILE --kubeconfig KUBECONFIG --disable-admin-cluster-webhook
    作業 1.13、1.14.0-1.14.8、1.15.0-1.15.4、1.16.0-1.16.1

    刪除非 HA Controlplane V2 叢集時，叢集會卡在節點刪除程序，直到逾時為止。

    解決方法：

    如果叢集包含具有重要資料的 StatefulSet，請與 Cloud Customer Care 團隊聯絡，解決這個問題。

    如否，請按照下列步驟操作：

    • 從 vSphere 刪除所有叢集 VM。您可以透過 vSphere UI 刪除 VM，也可以執行下列指令： 
            govc vm.destroy
      。
    • 再次強制刪除叢集： 
           gkectl delete cluster --cluster USER_CLUSTER_NAME --kubeconfig ADMIN_KUBECONFIG --force

    儲存空間 1.15.0 以上版本、1.16.0 以上版本

    如果叢集包含樹內 vSphere 永久磁碟區 (例如使用 standard StorageClass 建立的 PVC)，您會發現 vCenter 每分鐘都會觸發 com.vmware.cns.tasks.attachvolume 工作。


    解決方法：

    編輯 vSphere CSI 功能 configMap，並將 list-volumes 設為 false：

         kubectl edit configmap internal-feature-states.csi.vsphere.vmware.com -n kube-system --kubeconfig KUBECONFIG

    重新啟動 vSphere CSI 控制器 Pod：

         kubectl rollout restart deployment vsphere-csi-controller -n kube-system --kubeconfig KUBECONFIG
    儲存空間 1.16.0

    如果叢集包含 in-tree vSphere 永久磁碟區，在驗證叢集儲存空間設定時，gkectl diagnose 和 gkectl upgrade 指令可能會對永久磁碟區要求 (PVC) 提出錯誤警告。警告訊息如下所示：

        CSIPrerequisites pvc/pvc-name: PersistentVolumeClaim pvc-name bounds to an in-tree vSphere volume created before CSI migration enabled, but it doesn't have the annotation pv.kubernetes.io/migrated-to set to csi.vsphere.vmware.com after CSI migration is enabled

    解決方法：

    執行下列指令，檢查 PVC 的註解是否包含上述警告：

        kubectl get pvc PVC_NAME -n PVC_NAMESPACE -oyaml --kubeconfig KUBECONFIG

    如果輸出內容中的 annotations 欄位包含下列項目，您可以放心忽略警告：

          pv.kubernetes.io/bind-completed: "yes"
      pv.kubernetes.io/bound-by-controller: "yes"
      volume.beta.kubernetes.io/storage-provisioner: csi.vsphere.vmware.com
    升級、更新 1.15.0 以上版本、1.16.0 以上版本

    如果叢集未使用私有登錄檔，且元件存取服務帳戶金鑰和記錄與監控 (或連線與註冊) 服務帳戶金鑰已過期，當您輪替服務帳戶金鑰時，gkectl update credentials會失敗，並顯示類似下列的錯誤：

    Error: reconciliation failed: failed to update platform: ...

    解決方法：

    首先，請輪替元件存取服務帳戶金鑰。雖然系統會顯示相同的錯誤訊息，但在元件存取服務帳戶金鑰輪替後，您應該就能輪替其他金鑰。

    如果更新仍未成功，請與 Cloud Customer Care 團隊聯絡，解決這個問題。
    升級 1.16.0-1.16.5

    在使用者叢集升級期間，使用者叢集控制器升級至 1.16 後，如果您有其他由相同管理員叢集管理的 1.15 使用者叢集，這些叢集的使用者主機可能會意外重建。

    1.16 使用者叢集控制器存在錯誤，可能會觸發 1.15 使用者主機重新建立作業。

    解決方法取決於您遇到這個問題的方式。

    使用 Google Cloud 控制台升級使用者叢集時的解決方法：

    選項 1：使用已修正的 GKE on VMware 1.16.6 以上版本。

    方法 2：請按照下列步驟操作：

    1. 使用下列指令手動新增重新執行註解： 
      kubectl edit onpremuserclusters USER_CLUSTER_NAME -n USER_CLUSTER_NAME-gke-onprem-mgmt --kubeconfig ADMIN_KUBECONFIG

      重新執行註解：

      onprem.cluster.gke.io/server-side-preflight-rerun: true
    2. 如要監控升級進度，請檢查 OnPremUserCluster 的 status 欄位。

    使用自己的管理員工作站升級使用者叢集時的解決方法：

    選項 1：使用已修正的 GKE on VMware 1.16.6 以上版本。

    方法 2：請按照下列步驟操作：

    1. 新增建構資訊檔案 /etc/cloud/build.info，並加入以下內容。這會導致系統在本機管理工作站上執行預檢，而不是在伺服器上執行。 
      gke_on_prem_version: GKE_ON_PREM_VERSION
       例如： 
      gke_on_prem_version: 1.16.0-gke.669
    2. 重新執行升級指令。
    3. 升級完成後，請刪除 build.info 檔案。
    建立 1.16.0-1.16.5、1.28.0-1.28.100

    建立叢集時，如果沒有為 IP 區塊檔案中的每個 IP 位址指定主機名稱，系統會顯示下列錯誤訊息，導致前置檢查失敗： 

    multiple VMs found by DNS name  in xxx datacenter. Anthos Onprem doesn't support duplicate hostname in the same vCenter and you may want to rename/delete the existing VM.`

    前置檢查作業有錯誤，會將空白主機名稱視為重複。

    解決方法：

    方法 1：使用修正後的版本。

    方法 2：新增 --skip-validation-net-config 旗標，略過這項預檢。

    方法 3：在 IP 區塊檔案中，為每個 IP 位址指定不重複的主機名稱。
    升級、更新 1.16

    對於非高可用性管理員叢集和控制層 v1 使用者叢集，當您升級或更新管理員叢集時，管理員叢集主機重新建立作業可能會與使用者叢集主機重新啟動作業同時發生，這可能會導致競爭情況。 這會導致使用者叢集控制層 Pod 無法與管理員叢集控制層通訊，進而導致使用者叢集控制層上的 kube-etcd 和 kube-apiserver 發生磁碟區連結問題。

    如要驗證問題，請對受影響的 Pod 執行下列指令：

    kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG --namespace USER_CLUSTER_NAME describe pod IMPACTED_POD_NAME
     您會看到類似下列的事件： 
    Events:
  Type     Reason       Age                  From               Message
  ----     ------       ----                 ----               -------
  Warning  FailedMount  101s                 kubelet            Unable to attach or mount volumes: unmounted volumes=[kube-audit], unattached volumes=[], failed to process volumes=[]: timed out waiting for the condition
  Warning  FailedMount  86s (x2 over 3m28s)  kubelet            MountVolume.SetUp failed for volume "pvc-77cd0635-57c2-4392-b191-463a45c503cb" : rpc error: code = FailedPrecondition desc = volume ID: "bd313c62-d29b-4ecd-aeda-216648b0f7dc" does not appear staged to "/var/lib/kubelet/plugins/kubernetes.io/csi/csi.vsphere.vmware.com/92435c96eca83817e70ceb8ab994707257059734826fedf0c0228db6a1929024/globalmount"

    解決方法：

    1. 透過 SSH 連線至使用者控制層節點，由於這是控制層 V1 使用者叢集，因此使用者控制層節點位於管理員叢集。
    2. 使用下列指令重新啟動 kubelet： 
          sudo systemctl restart kubelet
      重新啟動後，kubelet 即可正確重建階段全域掛接。
    升級、更新 1.16.0

    升級或更新管理員叢集時，競爭情況可能會導致 vSphere 雲端控制器管理員意外刪除新的控制層節點。這會導致 clusterapi-controller 停滯，等待節點建立完成，最終升級/更新作業會逾時。在本例中，gkectl 升級/更新指令的輸出內容如下所示：

        controlplane 'default/gke-admin-hfzdg' is not ready: condition "Ready": condition is not ready with reason "MachineInitializing", message "Wait for the control plane machine "gke-admin-hfzdg-6598459f9zb647c8-0\" to be rebooted"...

    如要找出症狀，請執行下列指令，在管理員叢集中登入 vSphere Cloud Controller Manager：

        kubectl get pods --kubeconfig ADMIN_KUBECONFIG -n kube-system | grep vsphere-cloud-controller-manager
    kubectl logs -f vsphere-cloud-controller-manager-POD_NAME_SUFFIX --kubeconfig ADMIN_KUBECONFIG -n kube-system

    以下是上述指令的錯誤訊息範例：

        node name: 81ff17e25ec6-qual-335-1500f723 has a different uuid. Skip deleting this node from cache.

    解決方法：

    1. 重新啟動失敗的機器，重新建立已刪除的節點物件。
    2. 透過 SSH 連線至每個控制層節點，然後重新啟動 vSphere 雲端控制器管理員靜態 Pod： 
            sudo crictl ps | grep vsphere-cloud-controller-manager | awk '{print $1}'
      sudo crictl stop PREVIOUS_COMMAND_OUTPUT
    3. 重新執行升級/更新指令。
    作業 1.16

    如果同一資料中心內有重複的主機名稱，升級 1.15 叢集或建立具有靜態 IP 的 1.16 叢集就會失敗。發生這項錯誤的原因是 vSphere 雲端控制器管理員無法在節點物件中新增外部 IP 和供應商 ID。這會導致叢集升級/建立作業逾時。

    如要找出問題，請取得叢集的 vSphere Cloud Controller Manager Pod 記錄。您使用的指令取決於叢集類型，如下所示：

    • 管理員叢集： 
            kubectl get pods --kubeconfig ADMIN_KUBECONFIG -n kube-system | grep vsphere-cloud-controller-manager
      kubectl logs -f vsphere-cloud-controller-manager-POD_NAME_SUFFIX --kubeconfig ADMIN_KUBECONFIG -n kube-system
    • 使用者叢集 (含 enableControlplaneV2 false)： 
            kubectl get pods --kubeconfig ADMIN_KUBECONFIG -n USER_CLUSTER_NAME | grep vsphere-cloud-controller-manager
      kubectl logs -f vsphere-cloud-controller-manager-POD_NAME_SUFFIX --kubeconfig ADMIN_KUBECONFIG -n USER_CLUSTER_NAME
    • 使用者叢集 (含 enableControlplaneV2 true)： 
            kubectl get pods --kubeconfig USER_KUBECONFIG -n kube-system | grep vsphere-cloud-controller-manager
      kubectl logs -f vsphere-cloud-controller-manager-POD_NAME_SUFFIX --kubeconfig USER_KUBECONFIG -n kube-system

    以下是錯誤訊息範例：

        I1003 17:17:46.769676       1 search.go:152] Finding node admin-vm-2 in vc=vcsa-53598.e5c235a1.asia-northeast1.gve.goog and datacenter=Datacenter
    E1003 17:17:46.771717       1 datacenter.go:111] Multiple vms found VM by DNS Name. DNS Name: admin-vm-2

    檢查資料中心內是否有重複的主機名稱：

    您可以按照下列方法檢查主機名稱是否重複，並視需要採取因應措施。
              export GOVC_DATACENTER=GOVC_DATACENTER
          export GOVC_URL=GOVC_URL
          export GOVC_USERNAME=GOVC_USERNAME
          export GOVC_PASSWORD=GOVC_PASSWORD
          export GOVC_INSECURE=true
          govc find . -type m -guest.hostName HOSTNAME
    指令和輸出內容範例： 
              export GOVC_DATACENTER=mtv-lifecycle-vc01
          export GOVC_URL=https://mtv-lifecycle-vc01.anthos/sdk
          export GOVC_USERNAME=xxx
          export GOVC_PASSWORD=yyy
          export GOVC_INSECURE=true
          govc find . -type m -guest.hostName f8c3cd333432-lifecycle-337-xxxxxxxz
          ./vm/gke-admin-node-6b7788cd76-wkt8g
          ./vm/gke-admin-node-6b7788cd76-99sg2
          ./vm/gke-admin-master-5m2jb

    您採取的解決方法取決於失敗的作業。

    升級的解決方法：

    針對適用的叢集類型採取因應措施。

    • 使用者叢集：
      1. 在 user-ip-block.yaml 中，將受影響機器的名稱更新為專屬名稱，並觸發強制更新：
                  gkectl update cluster --kubeconfig ADMIN_KUBECONFIG --config NEW_USER_CLUSTER_CONFIG --force
      2. 重新執行 gkectl upgrade cluster
    • 管理員叢集：
      1. 在 admin-ip-block.yaml 中，將受影響機器的名稱更新為專屬名稱，然後觸發強制更新：
                  gkectl update admin --kubeconfig ADMIN_KUBECONFIG --config NEW_ADMIN_CLUSTER_CONFIG --force --skip-cluster-ready-check
      2. 如果是非高可用性管理員叢集，且您發現管理員主機 VM 使用重複的主機名稱，則還需要：
        取得管理員主機的機器名稱 
                  kubectl get machine --kubeconfig ADMIN_KUBECONFIG -owide -A
        更新管理員主機物件
        注意：NEW_ADMIN_MASTER_HOSTNAME 應與您在步驟 1 的 admin-ip-block.yaml 中設定的相同。
                  kubectl patch machine ADMIN_MASTER_MACHINE_NAME --kubeconfig ADMIN_KUBECONFIG --type='json' -p '[{"op": "replace", "path": "/spec/providerSpec/value/networkSpec/address/hostname", "value":"NEW_ADMIN_MASTER_HOSTNAME"}]'
        確認管理主機物件中的主機名稱已更新：
                  kubectl get machine ADMIN_MASTER_MACHINE_NAME --kubeconfig ADMIN_KUBECONFIG -oyaml
          kubectl get machine ADMIN_MASTER_MACHINE_NAME --kubeconfig ADMIN_KUBECONFIG -o jsonpath='{.spec.providerSpec.value.networkSpec.address.hostname}'
      3. 停用檢查點後，重新執行管理員叢集升級：
                  gkectl upgrade admin --kubeconfig ADMIN_KUBECONFIG --config ADMIN_CLUSTER_CONFIG --disable-upgrade-from-checkpoint

    安裝解決方法：

    針對適用的叢集類型採取因應措施。
    作業 1.16.0、1.16.1、1.16.2、1.16.3

    如果 vSphere 使用者名稱或密碼包含 $ 或 `，下列作業就會失敗：

    • 將啟用 Controlplane V2 的 1.15 使用者叢集升級至 1.16
    • 將 1.15 高可用性 (HA) 管理員叢集升級至 1.16
    • 建立啟用 Controlplane V2 的 1.16 使用者叢集
    • 建立 1.16 版高可用性管理員叢集

    使用修正後的 Google Distributed Cloud 1.16.4 以上版本，或執行下列因應措施。您採取的解決方法取決於失敗的作業。

    升級的解決方法：

    1. 在 vCenter 端變更 vCenter 使用者名稱或密碼，即可移除 $ 和 `。
    2. 在憑證設定檔中更新 vCenter 使用者名稱或密碼。
    3. 強制更新叢集。
      • 使用者叢集： 
                gkectl update cluster --kubeconfig ADMIN_KUBECONFIG --config USER_CLUSTER_CONFIG --force
      • 管理員叢集： 
                gkectl update admin --kubeconfig ADMIN_KUBECONFIG --config ADMIN_CLUSTER_CONFIG --force --skip-cluster-ready-check

    安裝解決方法：

    1. 在 vCenter 端變更 vCenter 使用者名稱或密碼，即可移除 $ 和 `。
    2. 在憑證設定檔中更新 vCenter 使用者名稱或密碼。
    3. 針對適用的叢集類型採取因應措施。
    儲存空間 1.11 以上版本、1.12 以上版本、1.13 以上版本、1.14 以上版本、1.15 以上版本、1.16

    刪除節點後，如果以相同節點名稱重新建立節點，後續建立 PersistentVolumeClaim (PVC) 時，可能會發生類似下列的錯誤：

        The object 'vim.VirtualMachine:vm-988369' has already been deleted or has not been completely created

    這是因為競爭條件，導致 vSphere CSI 控制器不會從快取中刪除已移除的機器。


    解決方法：

    重新啟動 vSphere CSI 控制器 Pod：

        kubectl rollout restart deployment vsphere-csi-controller -n kube-system --kubeconfig KUBECONFIG
    作業 1.16.0

    在高可用性管理員叢集上執行 gkectl repair admin-master 指令時，gkectl 會傳回下列錯誤訊息： 

      Exit with error: Failed to repair: failed to select the template: failed to get cluster name from kubeconfig, please contact Google support. failed to decode kubeconfig data: yaml: unmarshal errors:
    line 3: cannot unmarshal !!seq into map[string]*api.Cluster
    line 8: cannot unmarshal !!seq into map[string]*api.Context

    解決方法：

    在指令中新增 --admin-master-vm-template= 標記，並提供要修復機器的 VM 範本： 

      gkectl repair admin-master --kubeconfig=ADMIN_CLUSTER_KUBECONFIG \
      --config ADMIN_CLUSTER_CONFIG_FILE \
      --admin-master-vm-template=/DATA_CENTER/vm/VM_TEMPLATE_NAME

    如要找出機器的 VM 範本，請按照下列步驟操作：

    1. 前往 vSphere 用戶端的「Hosts and Clusters」(主機和叢集) 頁面。
    2. 按一下「VM 範本」，然後依管理員叢集名稱篩選。

      您應該會看到管理員叢集的三個 VM 範本。

    3. 複製與要修復的機器名稱相符的 VM 範本名稱，並在修復指令中使用該範本名稱。
      gkectl repair admin-master \
      --config=/home/ubuntu/admin-cluster.yaml \
      --kubeconfig=/home/ubuntu/kubeconfig \
      --admin-master-vm-template=/atl-qual-vc07/vm/gke-admin-98g94-zx...7vx-0-tmpl
    網路 1.10.0 以上版本、1.11.0 以上版本、1.12.0 以上版本、1.13.0 以上版本、1.14.0-1.14.7、1.15.0-1.15.3、1.16.0

    如果叢集使用 Seesaw 做為負載平衡器類型，且您發現 Seesaw VM 停止運作或無法開機，vSphere 控制台中可能會顯示下列錯誤訊息：

        GRUB_FORCE_PARTUUID set, initrdless boot failed. Attempting with initrd

    這個錯誤表示 VM 的磁碟空間不足，因為在 Seesaw VM 上執行的 fluent-bit 未設定正確的記錄檔輪替。


    解決方法：

    使用 du -sh -- /var/lib/docker/containers/* | sort -rh 找出占用最多磁碟空間的記錄檔。清除最大的記錄檔，然後重新啟動 VM。

    注意：如果無法存取 VM，請將磁碟附加至正常運作的 VM (例如管理工作站)，從附加的磁碟中移除檔案，然後將磁碟重新附加至原始 Seesaw VM。

    為避免再次發生這個問題，請連線至 VM 並修改 /etc/systemd/system/docker.fluent-bit.service 檔案。在 Docker 指令中新增 --log-opt max-size=10m --log-opt max-file=5，然後執行 systemctl restart docker.fluent-bit.service
    作業 1.13、1.14.0-1.14.6、1.15

    嘗試升級 (gkectl upgrade admin) 或更新 (gkectl update admin) 啟用檢查點的非高可用性管理員叢集時，升級或更新作業可能會失敗，並顯示下列錯誤： 

    Checking admin cluster certificates...FAILURE
    Reason: 20 admin cluster certificates error(s).
Unhealthy Resources:
    AdminMaster clusterCA bundle: failed to get clusterCA bundle on admin master, command [ssh -o IdentitiesOnly=yes -i admin-ssh-key -o StrictHostKeyChecking=no -o ConnectTimeout=30 ubuntu@AdminMasterIP -- sudo cat /etc/kubernetes/pki/ca-bundle.crt] failed with error: exit status 255, stderr: Authorized uses only. All activity may be monitored and reported.
    ubuntu@AdminMasterIP: Permission denied (publickey).
     
    failed to ssh AdminMasterIP, failed with error: exit status 255, stderr: Authorized uses only. All activity may be monitored and reported.
    ubuntu@AdminMasterIP: Permission denied (publickey)
     
    error dialing ubuntu@AdminMasterIP: failed to establish an authenticated SSH connection: ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey]...


    解決方法：

    如果無法升級至含有修正程式的 Google Distributed Cloud 修補程式版本，請與 Google 支援團隊聯絡以尋求協助。
    升級 1.13.0-1.13.9、1.14.0-1.14.6、1.15.1-1.15.2

    管理員叢集註冊 GKE On-Prem API 後，如果將管理員叢集升級至受影響的版本，可能會因為無法更新機群成員資格而失敗。發生這類故障時，嘗試升級叢集會看到下列錯誤：

        failed to register cluster: failed to apply Hub Membership: Membership API request failed: rpc error: code = InvalidArgument desc = InvalidFieldError for field endpoint.on_prem_cluster.resource_link: field cannot be updated

    當您明確註冊叢集，或是使用 GKE On-Prem API 用戶端升級使用者叢集時，管理員叢集會註冊 API。


    解決方法：

    取消註冊管理員叢集： 
        gcloud alpha container vmware admin-clusters unenroll ADMIN_CLUSTER_NAME --project CLUSTER_PROJECT --location=CLUSTER_LOCATION --allow-missing
    並 繼續升級管理員叢集。您可能會暫時看到過時的「無法註冊叢集」錯誤。過一段時間後，系統應該就會自動更新。
    升級、更新 1.13.0-1.13.9、1.14.0-1.14.4、1.15.0

    管理員叢集向 GKE On-Prem API 註冊時，資源連結註解會套用至 OnPremAdminCluster 自訂資源，但由於使用的註解金鑰有誤，後續更新管理員叢集時不會保留這項註解。這可能會導致管理員叢集再次誤註冊至 GKE On-Prem API。

    當您明確註冊叢集，或是使用 GKE On-Prem API 用戶端升級使用者叢集時，管理員叢集會註冊 API。


    解決方法：

    取消註冊管理員叢集： 
        gcloud alpha container vmware admin-clusters unenroll ADMIN_CLUSTER_NAME --project CLUSTER_PROJECT --location=CLUSTER_LOCATION --allow-missing
    並再次註冊 管理員叢集。
    網路 1.15.0-1.15.2

    OrderPolicy 不會被視為參數，也不會使用。Google Distributed Cloud 一律會使用 Random。

    發生這個問題的原因是 CoreDNS 範本未更新，導致系統忽略 orderPolicy。


    解決方法：

    更新 CoreDNS 範本並套用修正程式。這項修正會持續有效，直到升級為止。

    1. 編輯現有範本： 
      kubectl edit cm -n kube-system coredns-template
       將範本內容替換為下列內容： 
      coredns-template: |-
  .:53 {
    errors
    health {
      lameduck 5s
    }
    ready
    kubernetes cluster.local in-addr.arpa ip6.arpa {
      pods insecure
      fallthrough in-addr.arpa ip6.arpa
    }
{{- if .PrivateGoogleAccess }}
    import zones/private.Corefile
{{- end }}
{{- if .RestrictedGoogleAccess }}
    import zones/restricted.Corefile
{{- end }}
    prometheus :9153
    forward . {{ .UpstreamNameservers }} {
      max_concurrent 1000
      {{- if ne .OrderPolicy "" }}
      policy {{ .OrderPolicy }}
      {{- end }}
    }
    cache 30
{{- if .DefaultDomainQueryLogging }}
    log
{{- end }}
    loop
    reload
    loadbalance
}{{ range $i, $stubdomain := .StubDomains }}
{{ $stubdomain.Domain }}:53 {
  errors
{{- if $stubdomain.QueryLogging }}
  log
{{- end }}
  cache 30
  forward . {{ $stubdomain.Nameservers }} {
    max_concurrent 1000
    {{- if ne $.OrderPolicy "" }}
    policy {{ $.OrderPolicy }}
    {{- end }}
  }
}
{{- end }}
    升級、更新 1.10、1.11、1.12、1.13.0-1.13.7、1.14.0-1.14.3

    某些競爭條件可能會導致檢查點和實際 CR 之間的 OnPremAdminCluster 狀態不一致。發生問題時，升級管理員叢集後更新時，可能會遇到下列錯誤：

    Exit with error:
E0321 10:20:53.515562  961695 console.go:93] Failed to update the admin cluster: OnPremAdminCluster "gke-admin-rj8jr" is in the middle of a create/upgrade ("" -> "1.15.0-gke.123"), which must be completed before it can be updated
Failed to update the admin cluster: OnPremAdminCluster "gke-admin-rj8jr" is in the middle of a create/upgrade ("" -> "1.15.0-gke.123"), which must be completed before it can be updated
     如要解決這個問題，您必須編輯檢查點或停用檢查點以進行升級/更新，請與支援團隊聯絡，以繼續進行解決程序。
    作業 1.13.0-1.13.9、1.14.0-1.14.5、1.15.0-1.15.1

    Google Distributed Cloud 會在每次協調程序 (例如叢集升級期間) 中，變更管理員叢集控制層的管理員憑證。這種行為會增加管理員叢集取得無效憑證的可能性，特別是 1.15 版叢集。

    如果受到這個問題影響，您可能會遇到下列問題：

    • 無效的憑證可能會導致下列指令逾時並傳回錯誤：
      • gkectl create admin
      • gkectl upgrade amdin
      • gkectl update admin

      這些指令可能會傳回授權錯誤，例如：

      Failed to reconcile admin cluster: unable to populate admin clients: failed to get admin controller runtime client: Unauthorized
    • 管理員叢集的 kube-apiserver 記錄可能包含下列錯誤： 
      Unable to authenticate the request" err="[x509: certificate has expired or is not yet valid...

    解決方法：

    升級至已修正此問題的 Google Distributed Cloud 版本：1.13.10 以上、1.14.6 以上、1.15.2 以上。如果無法升級，請與 Cloud Customer Care 團隊聯絡，解決這個問題。
    網路、作業 1.10、1.11、1.12、1.13、1.14

    kube-system 中的網路閘道 Pod 可能會顯示 Pending 或 Evicted 狀態，如下列簡要範例輸出內容所示：

    $ kubectl -n kube-system get pods | grep ang-node
ang-node-bjkkc     2/2     Running     0     5d2h
ang-node-mw8cq     0/2     Evicted     0     6m5s
ang-node-zsmq7     0/2     Pending     0     7h

    這些錯誤表示作業撤銷事件，或是因節點資源而無法排定 Pod。由於 Anthos Network Gateway Pod 沒有 PriorityClass，因此與其他工作負載的預設優先順序相同。如果節點資源受限，網路閘道 Pod 可能會遭到撤銷。這項行為對 ang-node DaemonSet 特別不利，因為這些 Pod 必須排定在特定節點上，且無法遷移。


    解決方法：

    升級至 1.15 以上版本。

    如要短期解決問題，您可以手動將 PriorityClass 指派給 Anthos Network Gateway 元件。在叢集升級等協調程序中，Google Distributed Cloud 控制器會覆寫這些手動變更。

    • 將 system-cluster-critical PriorityClass 指派給 ang-controller-manager 和 autoscaler 叢集控制器 Deployment。
    • 將 system-node-critical PriorityClass 指派給 ang-daemon 節點 DaemonSet。
    升級、更新 1.12、1.13、1.14、1.15.0-1.15.2

    使用 gcloud 註冊管理員叢集時，如果 gkeConnect 區段不為空白，嘗試升級叢集時可能會看到下列錯誤：

    failed to register cluster: failed to apply Hub Mem\
bership: Membership API request failed: rpc error: code = InvalidArgument desc = InvalidFieldError for field endpoint.o\
n_prem_cluster.admin_cluster: field cannot be updated

    刪除 gke-connect 命名空間： 

    kubectl delete ns gke-connect --kubeconfig=ADMIN_KUBECONFIG
     取得管理員叢集名稱： 
    kubectl get onpremadmincluster -n kube-system --kubeconfig=ADMIN_KUBECONFIG
     刪除機群成員資格： 
    gcloud container fleet memberships delete ADMIN_CLUSTER_NAME
     並 繼續升級管理員叢集。
    作業 1.13.0-1.13.8、1.14.0-1.14.5、1.15.0-1.15.1

    gkectl diagnose snapshot --log-since 無法限制在叢集節點上執行的 journalctl 指令時間範圍

    這不會影響叢集快照的擷取功能，因為快照仍會包含在叢集節點上執行 journalctl 時，依預設收集的所有記錄。因此不會遺漏任何偵錯資訊。
    安裝、升級、更新 1.9 以上版本、1.10 以上版本、1.11 以上版本、1.12 以上版本

    在 1.13 之前的 Google Distributed Cloud 版本中，gkectl prepare windows 無法安裝 Docker，因為 MicrosoftDockerProvider 已淘汰。


    解決方法：

    解決這個問題的一般做法是升級至 Google Distributed Cloud 1.13，然後使用 1.13 gkectl 建立 Windows VM 範本，接著建立 Windows 節點集區。如要從目前版本升級至 Google Distributed Cloud 1.13，有兩種方式，如下所示。

    注意：我們提供解決目前版本問題的替代方案，不需升級至 1.13 版，但需要更多手動步驟。如要考慮這個選項，請與支援團隊聯絡。


    選項 1：藍綠升級

    您可以使用 Google Distributed Cloud 1.13 以上版本建立含 Windows 節點集區的新叢集，然後將工作負載遷移至新叢集，再拆除目前的叢集。建議使用最新 Google Distributed Cloud 次要版本。

    注意：佈建新叢集需要額外資源，但現有工作負載的停機時間和中斷次數較少。


    方法 2：刪除 Windows 節點集區，並在升級至 Google Distributed Cloud 1.13 時重新新增

    注意：如果選擇這個選項，叢集升級至 1.13 版並重新新增 Windows 節點集區後，Windows 工作負載才能執行。

    1. 從 user-cluster.yaml 檔案中移除 Windows 節點集區設定，然後執行下列指令，刪除現有的 Windows 節點集區：
      gkectl update cluster --kubeconfig=ADMIN_KUBECONFIG --config USER_CLUSTER_CONFIG_FILE
    2. 請按照對應目標子版本的 升級使用者指南，將僅限 Linux 的管理員和使用者叢集升級至 1.12。
    3. (請務必在升級至 1.13 前執行這個步驟) 確認 enableWindowsDataplaneV2: true 已在 OnPremUserCluster CR 中設定，否則叢集會繼續使用 Windows 節點集區的 Docker，這與新建立的 1.13 Windows VM 範本不相容，因為該範本未安裝 Docker。如果未設定或設為 False，請更新叢集，在 user-cluster.yaml 中將其設為 True，然後執行： 
      gkectl update cluster --kubeconfig=ADMIN_KUBECONFIG --config USER_CLUSTER_CONFIG_FILE
    4. 按照 升級使用者指南，將僅限 Linux 的管理員和使用者叢集升級至 1.13。
    5. 使用 1.13 版 gkectl 準備 Windows VM 範本： 
      gkectl prepare windows --base-vm-template BASE_WINDOWS_VM_TEMPLATE_NAME --bundle-path 1.13_BUNDLE_PATH --kubeconfig=ADMIN_KUBECONFIG
    6. 將 Windows 節點集區設定新增回 user-cluster.yaml，並將 OSImage 欄位設為新建立的 Windows VM 範本。
    7. 更新叢集以新增 Windows 節點集區 
      gkectl update cluster --kubeconfig=ADMIN_KUBECONFIG --config USER_CLUSTER_CONFIG_FILE
    安裝、升級、更新 1.13.0-1.13.9、1.14.0-1.14.5、1.15.0-1.15.1

    節點會使用 RootDistanceMaxSec 的 5 秒預設值，而非預期的 20 秒設定。如果透過 SSH 登入 VM 並檢查節點啟動記錄 (位於 `/var/log/startup.log`)，您會發現下列錯誤：

    + has_systemd_unit systemd-timesyncd
/opt/bin/master.sh: line 635: has_systemd_unit: command not found

    如果時鐘偏移量超過 5 秒，使用 5 秒的 RootDistanceMaxSec 可能會導致系統時鐘與 NTP 伺服器不同步。


    解決方法：

    將下列 DaemonSet 套用至叢集，即可設定 RootDistanceMaxSec：

    apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: change-root-distance
  namespace: kube-system
spec:
  selector:
    matchLabels:
      app: change-root-distance
  template:
    metadata:
      labels:
        app: change-root-distance
    spec:
      hostIPC: true
      hostPID: true
      tolerations:
      # Make sure pods gets scheduled on all nodes.
      - effect: NoSchedule
        operator: Exists
      - effect: NoExecute
        operator: Exists
      containers:
      - name: change-root-distance
        image: ubuntu
        command: ["chroot", "/host", "bash", "-c"]
        args:
        - |
          while true; do
            conf_file="/etc/systemd/timesyncd.conf.d/90-gke.conf"
            if [ -f $conf_file ] && $(grep -q "RootDistanceMaxSec=20" $conf_file); then
              echo "timesyncd has the expected RootDistanceMaxSec, skip update"
            else
              echo "updating timesyncd config to RootDistanceMaxSec=20"
              mkdir -p /etc/systemd/timesyncd.conf.d
              cat > $conf_file << EOF
          [Time]
          RootDistanceMaxSec=20
          EOF
              systemctl restart systemd-timesyncd
            fi
            sleep 600
          done
        volumeMounts:
        - name: host
          mountPath: /host
        securityContext:
          privileged: true
      volumes:
      - name: host
        hostPath:
          path: /
    升級、更新 1.12.0-1.12.6、1.13.0-1.13.6、1.14.0-1.14.2

    使用 1.13 版 gkectl 更新 1.12 版管理員叢集時，可能會看到下列錯誤：

    Failed to update the admin cluster: updating OS image type in admin cluster
is not supported in "1.12.x-gke.x"

    在 1.13 或 1.14 版叢集使用 gkectl update admin 時，回應中可能會顯示以下訊息：

    Exit with error:
Failed to update the cluster: the update contains multiple changes. Please
update only one feature at a time

    如果您查看 gkectl 記錄，可能會發現多項變更包括將 osImageType 從空字串設為 ubuntu_containerd。

    這些更新錯誤是因管理員叢集設定中的 osImageType 欄位回填不當所致，因為該欄位是在 1.9 版中推出。


    解決方法：

    升級至已修正問題的 Google Distributed Cloud 版本。如果無法升級，請與 Cloud Customer Care 團隊聯絡，解決這個問題。
    安裝、安全性 1.13、1.14、1.15、1.16

    啟用 Controlplane V2 ( enableControlplaneV2: true) 時，無法為使用者叢集的 Kubernetes API 伺服器提供額外的服務憑證 ( authentication.sni)。


    解決方法：

    在 Google Distributed Cloud 修補程式推出前，如需使用 SNI，請停用 Controlplane V2 (enableControlplaneV2: false)。
    安裝 1.0-1.11、1.12、1.13.0-1.13.9、1.14.0-1.14.5、1.15.0-1.15.1

    如果私人登錄檔使用者名稱包含 $，管理員控制層機器就無法啟動。 檢查管理控制平面電腦時，您會看到下列錯誤訊息：/var/log/startup.log

    ++ REGISTRY_CA_CERT=xxx
++ REGISTRY_SERVER=xxx
/etc/startup/startup.conf: line 7: anthos: unbound variable

    解決方法：

    使用不含 $ 的私人登錄檔使用者名稱，或使用已修正問題的 Google Distributed Cloud 版本。
    升級、更新 1.12.0-1.12.4

    更新管理員叢集時，記錄中會顯示下列誤判警告，您可以忽略這些警告。

        console.go:47] detected unsupported changes: &v1alpha1.OnPremAdminCluster{
      ...
      -         CARotation:        &v1alpha1.CARotationConfig{Generated: &v1alpha1.CARotationGenerated{CAVersion: 1}},
      +         CARotation:        nil,
      ...
    }
    升級、更新 1.13.0-1.13.9、1.14.0-1.14.5、1.15.0-1.15.1

    輪替 KSA 簽署金鑰並 更新使用者叢集後，gkectl update 可能會失敗，並顯示下列錯誤訊息：

    Failed to apply OnPremUserCluster 'USER_CLUSTER_NAME-gke-onprem-mgmt/USER_CLUSTER_NAME':
admission webhook "vonpremusercluster.onprem.cluster.gke.io" denied the request:
requests must not decrement *v1alpha1.KSASigningKeyRotationConfig Version, old version: 2, new version: 1"


    解決方法：

    將 KSA 簽署金鑰版本改回 1，但保留最新金鑰資料：
    1. 在管理員叢集的 USER_CLUSTER_NAME 命名空間下檢查密碼，並取得 ksa-signing-key 密碼的名稱： 
      kubectl --kubeconfig=ADMIN_KUBECONFIG -n=USER_CLUSTER_NAME get secrets | grep ksa-signing-key
    2. 複製 ksa-signing-key 密鑰，並將複製的密鑰命名為 service-account-cert： 
      kubectl --kubeconfig=ADMIN_KUBECONFIG -n=USER_CLUSTER_NAME get secret KSA-KEY-SECRET-NAME -oyaml | \
sed 's/ name: .*/ name: service-account-cert/' | \
kubectl --kubeconfig=ADMIN_KUBECONFIG -n=USER_CLUSTER_NAME apply -f -
    3. 刪除先前的 ksa-signing-key 密鑰： 
      kubectl --kubeconfig=ADMIN_KUBECONFIG -n=USER_CLUSTER_NAME delete secret KSA-KEY-SECRET-NAME
    4. 將 ksa-signing-key-rotation-stage configmap 中的 data.data 欄位更新為 '{"tokenVersion":1,"privateKeyVersion":1,"publicKeyVersions":[1]}'： 
      kubectl --kubeconfig=ADMIN_KUBECONFIG -n=USER_CLUSTER_NAME \
edit configmap ksa-signing-key-rotation-stage
    5. 停用驗證 Webhook，以便在 OnPremUserCluster 自訂資源中編輯版本資訊： 
      kubectl --kubeconfig=ADMIN_KUBECONFIG patch validatingwebhookconfiguration onprem-user-cluster-controller -p '
webhooks:
- name: vonpremnodepool.onprem.cluster.gke.io
  rules:
  - apiGroups:
    - onprem.cluster.gke.io
    apiVersions:
    - v1alpha1
    operations:
    - CREATE
    resources:
    - onpremnodepools
- name: vonpremusercluster.onprem.cluster.gke.io
  rules:
  - apiGroups:
    - onprem.cluster.gke.io
    apiVersions:
    - v1alpha1
    operations:
    - CREATE
    resources:
    - onpremuserclusters
'
    6. 將 OnPremUserCluster 自訂資源中的 spec.ksaSigningKeyRotation.generated.ksaSigningKeyRotation 欄位更新為 1： 
      kubectl --kubeconfig=ADMIN_KUBECONFIG -n=USER_CLUSTER_NAME-gke-onprem-mgmt \
edit onpremusercluster USER_CLUSTER_NAME
    7. 等待目標使用者叢集準備就緒，您可以透過下列方式檢查狀態： 
      kubectl --kubeconfig=ADMIN_KUBECONFIG -n=USER_CLUSTER_NAME-gke-onprem-mgmt \
get onpremusercluster
    8. 還原使用者叢集的驗證 Webhook： 
      kubectl --kubeconfig=ADMIN_KUBECONFIG patch validatingwebhookconfiguration onprem-user-cluster-controller -p '
webhooks:
- name: vonpremnodepool.onprem.cluster.gke.io
  rules:
  - apiGroups:
    - onprem.cluster.gke.io
    apiVersions:
    - v1alpha1
    operations:
    - CREATE
    - UPDATE
    resources:
    - onpremnodepools
- name: vonpremusercluster.onprem.cluster.gke.io
  rules:
  - apiGroups:
    - onprem.cluster.gke.io
    apiVersions:
    - v1alpha1
    operations:
    - CREATE
    - UPDATE
    resources:
    - onpremuserclusters
'
    9. 在叢集升級至修正版本前，請避免再次輪替 KSA 簽署金鑰。
    作業 1.13.1 以上版本、1.14、1.15、1.16

    使用 Terraform 刪除含有 F5 BIG-IP 負載平衡器的使用者叢集時，系統不會在刪除叢集後移除 F5 BIG-IP 虛擬伺服器。


    解決方法：

    如要移除 F5 資源，請按照步驟清除使用者叢集 F5 分區 。
    安裝、升級、更新 1.13.8、1.14.4

    如果您建立 1.13.8 或 1.14.4 版管理員叢集，或是將管理員叢集升級至 1.13.8 或 1.14.4 版，則 kind 叢集會從 docker.io提取下列容器映像檔：

  • docker.io/kindest/kindnetd
  • docker.io/kindest/local-path-provisioner
  • docker.io/kindest/local-path-helper

    • 如果無法從管理員工作站存取 docker.io，管理員叢集建立或升級作業就會失敗，無法啟動 kind 叢集。在管理員工作站上執行下列指令，即可查看待處理的對應容器 (使用 ErrImagePull)：

    docker exec gkectl-control-plane kubectl get pods -A

    回應包含類似下列的項目：

    ...
kube-system         kindnet-xlhmr                             0/1
    ErrImagePull  0    3m12s
...
local-path-storage  local-path-provisioner-86666ffff6-zzqtp   0/1
    Pending       0    3m12s
...

    這些容器映像檔應預先載入至 kind 叢集容器映像檔。不過，kind v0.18.0 預先載入的容器映像檔有問題，導致系統誤從網際網路提取映像檔。


    解決方法：

    在管理員工作站上執行下列指令，同時管理員叢集正在等待建立或升級：

    docker exec gkectl-control-plane ctr -n k8s.io images tag docker.io/kindest/kindnetd:v20230330-48f316cd@sha256:c19d6362a6a928139820761475a38c24c0cf84d507b9ddf414a078cf627497af docker.io/kindest/kindnetd:v20230330-48f316cd
docker exec gkectl-control-plane ctr -n k8s.io images tag docker.io/kindest/kindnetd:v20230330-48f316cd@sha256:c19d6362a6a928139820761475a38c24c0cf84d507b9ddf414a078cf627497af docker.io/kindest/kindnetd@sha256:c19d6362a6a928139820761475a38c24c0cf84d507b9ddf414a078cf627497af

docker exec gkectl-control-plane ctr -n k8s.io images tag docker.io/kindest/local-path-helper:v20230330-48f316cd@sha256:135203f2441f916fb13dad1561d27f60a6f11f50ec288b01a7d2ee9947c36270 docker.io/kindest/local-path-helper:v20230330-48f316cd
docker exec gkectl-control-plane ctr -n k8s.io images tag docker.io/kindest/local-path-helper:v20230330-48f316cd@sha256:135203f2441f916fb13dad1561d27f60a6f11f50ec288b01a7d2ee9947c36270 docker.io/kindest/local-path-helper@sha256:135203f2441f916fb13dad1561d27f60a6f11f50ec288b01a7d2ee9947c36270

docker exec gkectl-control-plane ctr -n k8s.io images tag docker.io/kindest/local-path-provisioner:v0.0.23-kind.0@sha256:f2d0a02831ff3a03cf51343226670d5060623b43a4cfc4808bd0875b2c4b9501 docker.io/kindest/local-path-provisioner:v0.0.23-kind.0
docker exec gkectl-control-plane ctr -n k8s.io images tag docker.io/kindest/local-path-provisioner:v0.0.23-kind.0@sha256:f2d0a02831ff3a03cf51343226670d5060623b43a4cfc4808bd0875b2c4b9501 docker.io/kindest/local-path-provisioner@sha256:f2d0a02831ff3a03cf51343226670d5060623b43a4cfc4808bd0875b2c4b9501
    作業 1.13.0-1.13.7、1.14.0-1.14.4、1.15.0

    如果叢集 VM 連接的交換器會篩除重複的 GARP (無償 ARP) 要求，keepalived 領導者選舉可能會遇到競爭條件，導致部分節點的 ARP 表格項目有誤。

    受影響的節點可以 ping 控制層 VIP，但與控制層 VIP 的 TCP 連線會逾時。


    解決方法：

    在受影響叢集的每個控制層節點上執行下列指令： 
        iptables -I FORWARD -i ens192 --destination CONTROL_PLANE_VIP -j DROP
    升級、更新 1.13.0-1.13.7、1.14.0-1.14.4、1.15.0

    vsphere-csi-controller應在 vCenter 憑證輪替後重新整理 vCenter 密碼。不過，目前的系統無法正確重新啟動 vsphere-csi-controller 的 Pod，導致 vsphere-csi-controller 在輪替後停止運作。

    解決方法：

    如果是以 1.13 以上版本建立的叢集，請按照下列指示重新啟動 vsphere-csi-controller 

    kubectl --kubeconfig=ADMIN_KUBECONFIG rollout restart deployment vsphere-csi-controller -n kube-system
    安裝 1.10.3-1.10.7、1.11、1.12、1.13.0-1.13.1

    即使在建立管理員叢集時叢集註冊失敗，gkectl create admin 指令也不會因錯誤而失敗，可能會成功。換句話說，管理員叢集「可能」會建立成功，但未註冊至機群。

    如要找出徵兆，請在 `gkectl create admin` 的記錄中尋找下列錯誤訊息： 
    Failed to register admin cluster

    您也可以在 Cloud 控制台的已註冊叢集中查看是否能找到該叢集。

    解決方法：

    如果是以 1.12 以上版本建立的叢集，請按照這篇文章的說明，在建立叢集後重新嘗試註冊管理員叢集。如果是以舊版建立的叢集，

    1. 在連線註冊 SA 金鑰檔案中附加虛假的鍵/值組合，例如「foo: bar」
    2. 執行 gkectl update admin 重新註冊管理員叢集。

    升級、更新 1.10、1.11、1.12、1.13.0-1.13.1

    升級管理員叢集時，如果升級使用者控制層節點逾時，管理員叢集就不會使用更新後的連線代理程式版本重新註冊。


    解決方法：

    檢查叢集是否顯示在已註冊的叢集中。 (選用步驟) 設定驗證後登入叢集。如果叢集仍處於註冊狀態，您可以略過下列重新嘗試註冊的指示。 如果叢集升級至 1.12 以上版本，請按照重新嘗試註冊管理員叢集的操作說明，在建立叢集後重新註冊。如果叢集升級至舊版，
    1. 在連線註冊 SA 金鑰檔案中附加虛假的鍵/值組合，例如「foo: bar」
    2. 執行 gkectl update admin 重新註冊管理員叢集。

    設定 1.15.0

    如果是高可用性管理員叢集，gkectl prepare 會顯示以下錯誤訊息：

    vCenter.dataDisk must be present in the AdminCluster spec

    解決方法：

    您可以放心忽略這則錯誤訊息。
    VMware 1.15.0

    建立使用 VM 主機親和性的節點集區時，競爭條件可能會導致系統建立多個同名的 VM 主機親和性規則。這可能會導致節點集區建立失敗。


    解決方法：

    移除舊的冗餘規則，以便繼續建立節點集區。 這些規則的名稱為 [USER_CLUSTER_NAME]-[HASH]。
    作業 1.15.0

    gkectl repair admin-master 指令可能會因競爭情況而失敗，並出現下列錯誤。

    Failed to repair: failed to delete the admin master node object and reboot the admin master VM


    解決方法：

    這個指令是等冪指令。可以安全地重新執行，直到指令成功為止。
    升級、更新 1.15.0

    重新建立或更新控制層節點後，由於 NodeAffinity 述詞失敗，某些 Pod 可能會處於 Failed 狀態。這些 Pod 失敗不會影響正常的叢集運作或健康狀態。


    解決方法：

    您可以放心忽略失敗的 Pod，或手動刪除這些 Pod。
    安全性、設定 1.15.0-1.15.1

    如果您使用預先準備的憑證和私人登錄檔，但尚未為私人登錄檔設定預先準備的憑證，OnPremUserCluster 可能無法就緒，您可能會看到下列錯誤訊息：

    failed to check secret reference for private registry …


    解決方法：

    請按照「設定準備好的憑證」一文的說明，準備使用者叢集的私有登錄檔憑證。
    升級、更新 1.15.0

    在 gkectl upgrade admin 期間，CSI 遷移的儲存空間前置檢查會驗證 StorageClass 是否有在 CSI 遷移後遭到忽略的參數。舉例來說，如果 StorageClass 含有 diskformat 參數，gkectl upgrade admin 就會標記 StorageClass，並在飛行前驗證中回報失敗。在 Google Distributed Cloud 1.10 之前建立的管理員叢集具有 StorageClass，但這會導致驗證失敗。不過，在 CSI 遷移後，這個 StorageClass 仍可正常運作。diskformat: thin這些失敗應視為警告。

    詳情請參閱「 將樹狀結構內 vSphere 磁碟區遷移至 vSphere Container Storage 外掛程式」一文中的 StorageClass 參數部分。


    解決方法：

    確認叢集有 StorageClass，且 CSI 遷移後會忽略參數，然後使用 --skip-validation-cluster-health 旗標執行 gkectl upgrade admin。
    儲存空間 1.15、1.16

    在特定情況下，磁碟可以唯讀模式連接至 Windows 節點。這會導致 Pod 內的對應磁碟區為唯讀狀態。如果新節點集取代舊節點集 (例如叢集升級或節點集區更新)，就更有可能發生這個問題。先前運作正常的有狀態工作負載，可能無法在新節點集上寫入磁碟區。


    解決方法：

    1. 取得無法寫入磁碟區的 Pod 的 UID： 
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get pod \
    POD_NAME --namespace POD_NAMESPACE \
    -o=jsonpath='{.metadata.uid}{"\n"}'
    2. 使用 PersistentVolumeClaim 取得 PersistentVolume 的名稱： 
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get pvc \
    PVC_NAME --namespace POD_NAMESPACE \
    -o jsonpath='{.spec.volumeName}{"\n"}'
    3. 判斷執行 Pod 的節點名稱： 
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIGget pods \
    --namespace POD_NAMESPACE \
    -o jsonpath='{.spec.nodeName}{"\n"}'
    4. 透過 SSH 或 vSphere 網頁介面取得節點的 PowerShell 存取權。
    5. 設定環境變數： 
      PS C:\Users\administrator> pvname=PV_NAME
PS C:\Users\administrator> podid=POD_UID
    6. 找出與 PersistentVolume 相關聯的磁碟號碼：
      PS C:\Users\administrator> disknum=(Get-Partition -Volume (Get-Volume -UniqueId ("\\?\"+(Get-Item (Get-Item
"C:\var\lib\kubelet\pods\$podid\volumes\kubernetes.io~csi\$pvname\mount").Target).Target))).DiskNumber
    7. 確認磁碟為 readonly： 
      PS C:\Users\administrator> (Get-Disk -Number $disknum).IsReadonly
       結果應為 True。
    8. 將 readonly 設為 false。 
      PS C:\Users\administrator> Set-Disk -Number $disknum -IsReadonly $false
PS C:\Users\administrator> (Get-Disk -Number $disknum).IsReadonly
    9. 刪除 Pod，讓系統重新啟動： 
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG delete pod POD_NAME \
    --namespace POD_NAMESPACE
    10. Pod 應排定在相同節點上。但如果 Pod 排程到新節點，您可能需要在新節點上重複上述步驟。
    升級、更新 1.12、1.13.0-1.13.7、1.14.0-1.14.4

    vsphere-csi-secret未在 gkectl update credentials vsphere --admin-cluster 後更新

    如果您在更新叢集憑證後更新管理員叢集的 vSphere 憑證，可能會發現管理員叢集 kube-system 命名空間下的 vsphere-csi-secret 仍使用舊憑證。


    解決方法：

    1. 取得 vsphere-csi-secret 密鑰名稱： 
      kubectl --kubeconfig=ADMIN_KUBECONFIG -n=kube-system get secrets | grep vsphere-csi-secret
    2. 更新從上述步驟取得的 vsphere-csi-secret 密鑰資料： 
      kubectl --kubeconfig=ADMIN_KUBECONFIG -n=kube-system patch secret CSI_SECRET_NAME -p \
  "{\"data\":{\"config\":\"$( \
    kubectl --kubeconfig=ADMIN_KUBECONFIG -n=kube-system get secrets CSI_SECRET_NAME -ojsonpath='{.data.config}' \
      | base64 -d \
      | sed -e '/user/c user = \"VSPHERE_USERNAME_TO_BE_UPDATED\"' \
      | sed -e '/password/c password = \"VSPHERE_PASSWORD_TO_BE_UPDATED\"' \
      | base64 -w 0 \
    )\"}}"
    3. 重新啟動 vsphere-csi-controller： 
      kubectl --kubeconfig=ADMIN_KUBECONFIG -n=kube-system rollout restart deployment vsphere-csi-controller
    4. 您可以使用下列指令追蹤推出狀態： 
      kubectl --kubeconfig=ADMIN_KUBECONFIG -n=kube-system rollout status deployment vsphere-csi-controller
       部署作業順利推出後，控制器應會使用更新後的 vsphere-csi-secret。
    升級、更新 1.10、1.11、1.12.0-1.12.6、1.13.0-1.13.6、1.14.0-1.14.2

    audit-proxy可能會因 --cluster-name 為空而進入當機迴圈。 這是更新邏輯中的錯誤所致，叢集名稱不會傳播至稽核 Proxy Pod / 容器資訊清單。


    解決方法：

    如果是使用 enableControlplaneV2: true 的控制層 v2 使用者叢集，請使用 SSH 連線至使用者控制層機器，然後使用 --cluster_name=USER_CLUSTER_NAME 更新 /etc/kubernetes/manifests/audit-proxy.yaml。

    如果是控制層 V1 使用者叢集，請編輯 kube-apiserver StatefulSet 中的 audit-proxy 容器，加入 --cluster_name=USER_CLUSTER_NAME：

    kubectl edit statefulset kube-apiserver -n USER_CLUSTER_NAME --kubeconfig=ADMIN_CLUSTER_KUBECONFIG
    升級、更新 1.11、1.12、1.13.0-1.13.5、1.14.0-1.14.1

    gkectl upgrade cluster後，控制層 Pod 可能會再次重新部署。 叢集狀態從「gkectl list clusters」變更為「RUNNING」到「RECONCILING」。 對使用者叢集的要求可能會逾時。

    這是因為控制平面憑證會在 gkectl upgrade cluster 後自動輪替。

    只有未使用控制層 v2 的使用者叢集會發生這個問題。


    解決方法：

    等待叢集狀態在 gkectl list clusters 中再次變更回 RUNNING，或升級至已修正問題的版本：1.13.6 以上、1.14.2 以上或 1.15 以上。
    升級、更新 1.12.7

    Google Distributed Cloud 1.12.7-gke.19 是不良版本，不建議使用。構件已從 Cloud Storage bucket 中移除。

    解決方法：

    請改用 1.12.7-gke.20 版本。
    升級、更新 1.12.0 以上版本、1.13.0 至 1.13.7 版、1.14.0 至 1.14.3 版

    如果您使用下列其中一種方法更新登錄憑證：

    • gkectl update credentials componentaccess 如果未使用私人登錄檔
    • gkectl update credentials privateregistry (如果使用私人登錄檔)

    您可能會發現 gke-connect-agent 繼續使用舊版映像檔，或 gke-connect-agent Pod 無法因 ImagePullBackOff 而提取。

    Google Distributed Cloud 1.13.8、1.14.4 和後續版本將修正這個問題。


    解決方法：

    選項 1：手動重新部署 gke-connect-agent：

    1. 刪除 gke-connect 命名空間： 
      kubectl --kubeconfig=KUBECONFIG delete namespace gke-connect
    2. 使用原始的註冊服務帳戶金鑰重新部署 gke-connect-agent (不需更新金鑰)：

      管理員叢集： 
      gkectl update credentials register --kubeconfig=ADMIN_CLUSTER_KUBECONFIG --config ADMIN_CLUSTER_CONFIG_FILE --admin-cluster
       使用者叢集： 
      gkectl update credentials register --kubeconfig=ADMIN_CLUSTER_KUBECONFIG --config USER_CLUSTER_CONFIG_FILE

    方法 2：您可以手動變更 gke-connect-agent 部署作業使用的映像檔提取密鑰資料：regcred

    kubectl --kubeconfig=KUBECONFIG -n=gke-connect patch secrets regcred -p "{\"data\":{\".dockerconfigjson\":\"$(kubectl --kubeconfig=KUBECONFIG -n=kube-system get secrets private-registry-creds -ojsonpath='{.data.\.dockerconfigjson}')\"}}"

    選項 3：您可以在gke-connect-agent部署作業中，透過下列方式為叢集新增預設的映像檔提取密鑰：

    1. 將預設密鑰複製到 gke-connect 命名空間： 
      kubectl --kubeconfig=KUBECONFIG -n=kube-system get secret private-registry-creds -oyaml | sed 's/ namespace: .*/ namespace: gke-connect/' | kubectl --kubeconfig=KUBECONFIG -n=gke-connect apply -f -
    2. 取得 gke-connect-agent 部署作業名稱： 
      kubectl --kubeconfig=KUBECONFIG -n=gke-connect get deployment | grep gke-connect-agent
    3. 將預設密鑰新增至 gke-connect-agent 部署作業： 
      kubectl --kubeconfig=KUBECONFIG -n=gke-connect patch deployment DEPLOYMENT_NAME -p '{"spec":{"template":{"spec":{"imagePullSecrets": [{"name": "private-registry-creds"}, {"name": "regcred"}]}}}}'
    安裝 1.13、1.14

    如果您在以手動負載平衡器建立叢集前執行 gkectl check-config 驗證設定，指令會失敗並顯示下列錯誤訊息。

     - Validation Category: Manual LB    Running validation check for "Network
configuration"...panic: runtime error: invalid memory address or nil pointer
dereference

    解決方法：

    方法 1：使用包含修正程式的修補程式版本 1.13.7 和 1.14.4。

    方法 2：您也可以執行相同指令來驗證設定，但略過負載平衡器驗證。

    gkectl check-config --skip-validation-load-balancer
    作業 1.0、1.1、1.2、1.3、1.4、1.5、1.6、1.7、1.8、1.9、1.10、1.11、1.12、1.13 和 1.14

    如果叢集執行的 etcd 版本為 3.4.13 或更早，可能會發生監控資源無法運作，導致監控作業資源不足的問題，進而引發下列問題：

    • Pod 排程中斷
    • 節點無法註冊
    • kubelet 未觀察到 Pod 變更

    這些問題可能會導致叢集無法運作。

    Google Distributed Cloud 1.12.7、1.13.6、1.14.3 和後續版本已修正這個問題。這些較新版本使用 etcd 3.4.21 版。所有先前的 Google Distributed Cloud 版本都會受到這個問題影響。

    解決方法

    如果無法立即升級，可以減少叢集中的節點數量，降低叢集故障的風險。移除節點，直到 etcd_network_client_grpc_sent_bytes_total 指標低於 300 MBps 為止。

    如要在 Metrics Explorer 中查看這項指標，請按照下列步驟操作：

    1. 前往 Google Cloud 控制台的 Metrics Explorer：

      前往 Metrics Explorer

    2. 選取「設定」分頁標籤。
    3. 展開「選取指標」，在篩選列中輸入 Kubernetes Container ，然後使用子選單選取指標：
      1. 在「Active resources」(有效資源) 選單中，選取「Kubernetes Container」(Kubernetes 容器)。
      2. 在「Active metric categories」(使用中的指標類別) 選單中，選取「Anthos」。
      3. 在「Active metrics」(使用中的指標) 選單中，選取 etcd_network_client_grpc_sent_bytes_total。
      4. 按一下「套用」。
    升級、更新 1.10、1.11、1.12、1.13 和 1.14

    叢集重新啟動或升級時，GKE Identity Service 可能會因流量過大而無法負荷，這些流量包含透過驗證 Webhook 從 kube-apiserver 轉送至 GKE Identity Service 的過期 JWT 權杖。雖然 GKE Identity Service 不會進入無限迴圈，但會停止回應，且不再處理後續要求。這個問題最終會導致控制層延遲時間變長。

    下列 Google Distributed Cloud 版本已修正這個問題：

    • 1.12.6+
    • 1.13.6+
    • 1.14.2+

    如要判斷是否受到這個問題影響，請按照下列步驟操作：

    1. 檢查是否可從外部連線至 GKE Identity Service 端點： 
      curl -s -o /dev/null -w "%{http_code}" \
    -X POST https://CLUSTER_ENDPOINT/api/v1/namespaces/anthos-identity-service/services/https:ais:https/proxy/authenticate -d '{}'

      將 CLUSTER_ENDPOINT 替換為叢集的控制層 VIP 和控制層負載平衡器通訊埠 (例如 172.16.20.50:443)。

      如果受到這個問題影響，指令會傳回 400 狀態碼。如果要求逾時，請重新啟動 ais Pod，然後重新執行 curl 指令，看看是否能解決問題。如果收到 000 狀態碼，表示問題已解決，您不必再採取任何行動。如果仍收到 400 狀態碼，表示 GKE Identity Service HTTP 伺服器未啟動。在這種情況下，請繼續操作。

    2. 檢查 GKE Identity Service 和 kube-apiserver 記錄：
      1. 檢查 GKE Identity Service 記錄： 
        kubectl logs -f -l k8s-app=ais -n anthos-identity-service \
    --kubeconfig KUBECONFIG

        如果記錄包含類似下列內容的項目，表示您受到這個問題影響：

        I0811 22:32:03.583448      32 authentication_plugin.cc:295] Stopping OIDC authentication for ???. Unable to verify the OIDC ID token: JWT verification failed: The JWT does not appear to be from this identity provider. To match this provider, the 'aud' claim must contain one of the following audiences:
      2. 檢查叢集的 kube-apiserver 記錄：

        在下列指令中，KUBE_APISERVER_POD 是指定叢集上 kube-apiserver Pod 的名稱。

        管理員叢集：

        kubectl --kubeconfig ADMIN_KUBECONFIG logs \
    -n kube-system KUBE_APISERVER_POD kube-apiserver

        使用者叢集：

        kubectl --kubeconfig ADMIN_KUBECONFIG logs \
    -n USER_CLUSTER_NAME KUBE_APISERVER_POD kube-apiserver

        如果 kube-apiserver 記錄包含下列項目，表示您受到這個問題影響：

        E0811 22:30:22.656085       1 webhook.go:127] Failed to make webhook authenticator request: error trying to reach service: net/http: TLS handshake timeout
E0811 22:30:22.656266       1 authentication.go:63] "Unable to authenticate the request" err="[invalid bearer token, error trying to reach service: net/http: TLS handshake timeout]"

    解決方法

    如果無法立即升級叢集來修正問題，可以找出並重新啟動違規 Pod 做為解決方法：

    1. 將 GKE Identity Service 詳細程度層級提高至 9： 
      kubectl patch deployment ais -n anthos-identity-service --type=json \
    -p='[{"op": "add", "path": "/spec/template/spec/containers/0/args/-", \
    "value":"--vmodule=cloud/identity/hybrid/charon/*=9"}]' \
    --kubeconfig KUBECONFIG
    2. 檢查 GKE Identity Service 記錄，找出無效的權杖內容： 
      kubectl logs -f -l k8s-app=ais -n anthos-identity-service \
    --kubeconfig KUBECONFIG
    3. 如要取得與每個無效權杖內容相關聯的權杖酬載，請使用下列指令剖析每個相關服務帳戶密鑰：
      kubectl -n kube-system get secret SA_SECRET \
    --kubeconfig KUBECONFIG \
    -o jsonpath='{.data.token}' | base64 --decode
    4. 如要解碼權杖並查看來源 Pod 名稱和命名空間，請將權杖複製到 jwt.io 的偵錯工具。
    5. 根據權杖重新啟動 Pod。
    作業 1.8、1.9、1.10

    使用 etcddefrag:gke_master_etcddefrag_20210211.00_p0 映像檔的 etcd 維護 Pod 會受到影響。在每個重整週期中，`etcddefrag` 容器都會開啟與 etcd 伺服器的新連線，而舊連線不會清除。


    解決方法：

    方法 1：將版本從 1.8 升級至 1.11 的最新修補程式版本，其中包含修正措施。

    方法 2：如果您使用的修補程式版本早於 1.9.6 和 1.10.3，請縮減管理員和使用者叢集的 etcd-maintenance Pod：

    kubectl scale --replicas 0 deployment/gke-master-etcd-maintenance -n USER_CLUSTER_NAME --kubeconfig ADMIN_CLUSTER_KUBECONFIG
kubectl scale --replicas 0 deployment/gke-master-etcd-maintenance -n kube-system --kubeconfig ADMIN_CLUSTER_KUBECONFIG
    作業 1.9、1.10、1.11、1.12、1.13

    叢集健康狀態控制器和 gkectl diagnose cluster 指令都會執行一組健康狀態檢查，包括跨命名空間的 Pod 健康狀態檢查。不過，他們開始誤略過使用者控制層 Pod。如果您使用控制層 v2 模式，這項異動不會影響叢集。


    解決方法：

    這不會影響任何工作負載或叢集管理。如要檢查控制層 Pod 的健康狀態，可以執行下列指令：

    kubectl get pods -owide -n USER_CLUSTER_NAME --kubeconfig ADMIN_CLUSTER_KUBECONFIG
    升級、更新 1.6 以上版本、1.7 以上版本

    1.6 和 1.7 版管理員叢集升級作業可能會受到 k8s.gcr.io -> registry.k8s.io 重新導向影響

    Kubernetes 已在 2023 年 3 月 20 日將流量從 k8s.gcr.io重新導向至 registry.k8s.io。在 Google Distributed Cloud 1.6.x 和 1.7.x 中，管理員叢集升級作業會使用 k8s.gcr.io/pause:3.2 容器映像檔。如果管理工作站使用 Proxy，且 Proxy 不允許 registry.k8s.io，而容器映像檔 k8s.gcr.io/pause:3.2 未在本機快取，則在提取容器映像檔時，管理員叢集升級作業會失敗。


    解決方法：

    將 registry.k8s.io 新增至管理工作站的 Proxy 許可清單。
    網路 1.10、1.11、1.12.0-1.12.6、1.13.0-1.13.6、1.14.0-1.14.2

    gkectl create loadbalancer 失敗，錯誤訊息如下：

    - Validation Category: Seesaw LB - [FAILURE] Seesaw validation: xxx cluster lb health check failed: LB"xxx.xxx.xxx.xxx" is not healthy: Get "http://xxx.xxx.xxx.xxx:xxx/healthz": dial tcpxxx.xxx.xxx.xxx:xxx: connect: no route to host

    這是因為系統已存在 Seesaw 群組檔案。預檢會嘗試驗證不存在的 Seesaw 負載平衡器。

    解決方法：

    移除這個叢集的現有 Seesaw 群組檔案。檔案名稱為管理員叢集的 seesaw-for-gke-admin.yaml，以及使用者叢集的 seesaw-for-{CLUSTER_NAME}.yaml。
    網路 1.14

    使用 Ubuntu 或 COS 作業系統映像檔時，Google Distributed Cloud 1.14 版容易發生 netfilter 連線追蹤 (conntrack) 表格插入失敗問題。插入失敗會導致應用程式隨機逾時，即使 conntrack 表格有空間容納新項目，也可能發生這種情況。失敗原因為核心 5.15 以上版本有變更，會根據鏈結長度限制表格插入作業。

    如要確認是否受到這個問題影響，請在每個節點上執行下列指令，檢查核心內連線追蹤系統統計資料：

    sudo conntrack -S

    回應的形式如下所示：

    cpu=0       found=0 invalid=4 insert=0 insert_failed=0 drop=0 early_drop=0 error=0 search_restart=0 clash_resolve=0 chaintoolong=0
cpu=1       found=0 invalid=0 insert=0 insert_failed=0 drop=0 early_drop=0 error=0 search_restart=0 clash_resolve=0 chaintoolong=0
cpu=2       found=0 invalid=16 insert=0 insert_failed=0 drop=0 early_drop=0 error=0 search_restart=0 clash_resolve=0 chaintoolong=0
cpu=3       found=0 invalid=13 insert=0 insert_failed=0 drop=0 early_drop=0 error=0 search_restart=0 clash_resolve=0 chaintoolong=0
cpu=4       found=0 invalid=9 insert=0 insert_failed=0 drop=0 early_drop=0 error=0 search_restart=0 clash_resolve=0 chaintoolong=0
cpu=5       found=0 invalid=1 insert=0 insert_failed=0 drop=0 early_drop=0 error=519 search_restart=0 clash_resolve=126 chaintoolong=0
...

    如果回應中的 chaintoolong 值為非零數字，表示您受到這個問題影響。

    解決方法

    短期解決方法是增加 netfiler 雜湊表 (nf_conntrack_buckets) 和 netfilter 連線追蹤表 (nf_conntrack_max) 的大小。在每個叢集節點上使用下列指令，即可增加表格大小：

    sysctl -w net.netfilter.nf_conntrack_buckets=TABLE_SIZE
sysctl -w net.netfilter.nf_conntrack_max=TABLE_SIZE

    將 TABLE_SIZE 替換為新的位元組大小。預設的表格大小值為 262144。建議您將值設為節點上核心數的 65,536 倍。舉例來說，如果節點有八個核心，請將表格大小設為 524288。
    網路 1.13.0-1.13.2

    啟用 Controlplane V2 後，calico-typha 或 anetd-operator 可能會排定至 Windows 節點，並進入當機迴圈。

    原因是這兩項部署作業可容許所有汙點，包括 Windows 節點汙點。


    解決方法：

    請升級至 1.13.3 以上版本，或執行下列指令來編輯 `calico-typha` 或 `anetd-operator` 部署作業：

        # If dataplane v2 is not used.
    kubectl edit deployment -n kube-system calico-typha --kubeconfig USER_CLUSTER_KUBECONFIG
    # If dataplane v2 is used.
    kubectl edit deployment -n kube-system anetd-operator --kubeconfig USER_CLUSTER_KUBECONFIG

    移除下列 spec.template.spec.tolerations：

        - effect: NoSchedule
      operator: Exists
    - effect: NoExecute
      operator: Exists

    並新增下列容錯：

        - key: node-role.kubernetes.io/master
      operator: Exists
    設定 1.14.0-1.14.2

    如果您在 privateRegistry 區段中指定憑證 fileRef，可能無法建立使用者叢集。預檢可能會失敗，並顯示以下訊息： 

    [FAILURE] Docker registry access: Failed to login.


    解決方法：

    • 如果不想指定欄位，或想使用與管理員叢集相同的私有登錄檔憑證，只要移除或註解使用者叢集設定檔中的 privateRegistry 區段即可。
    • 如要為使用者叢集使用特定私有登錄檔憑證，可以暫時指定 privateRegistry 區段，如下所示：
      privateRegistry:
  address: PRIVATE_REGISTRY_ADDRESS
  credentials:
    username: PRIVATE_REGISTRY_USERNAME
    password: PRIVATE_REGISTRY_PASSWORD
  caCertPath: PRIVATE_REGISTRY_CACERT_PATH
       (注意：這只是暫時的修正方式，這些欄位已遭淘汰，升級至 1.14.3 以上版本時，請考慮使用憑證檔案。)

    作業 1.10 以上版本

    Dataplane V2 會接管負載平衡，並建立核心通訊端，而非以封包為基礎的 DNAT。也就是說，由於 Pod 會遭到略過，且從未使用 IPTables，因此 Cloud Service Mesh 無法檢查封包。

    在 kube-proxy 自由模式中，如果服務的連線中斷或流量轉送錯誤，就表示發生這種情況，因為 Cloud Service Mesh 無法以 Sidecar 形式檢查封包。

    Google Distributed Cloud 1.10 的所有版本都有這個問題，但部分較新的 1.10 版本 (1.10.2 以上) 有解決方法。


    解決方法：

    如要完全相容，請升級至 1.11 版；如果執行的是 1.10.2 以上版本，請執行下列指令：

        kubectl edit cm -n kube-system cilium-config --kubeconfig USER_CLUSTER_KUBECONFIG

    將 bpf-lb-sock-hostns-only: true 新增至 configmap，然後重新啟動 anetd daemonset：

          kubectl rollout restart ds anetd -n kube-system --kubeconfig USER_CLUSTER_KUBECONFIG

    儲存空間 1.12 以上版本、1.13.3

    在 6 分鐘後卸離 PV/PVC 時，kube-controller-manager 可能會逾時，並強制卸離 PV/PVC。kube-controller-manager 的詳細記錄會顯示類似下列的事件：

    $ cat kubectl_logs_kube-controller-manager-xxxx | grep "DetachVolume started" | grep expired

kubectl_logs_kube-controller-manager-gke-admin-master-4mgvr_--container_kube-controller-manager_--kubeconfig_kubeconfig_--request-timeout_30s_--namespace_kube-system_--timestamps:2023-01-05T16:29:25.883577880Z W0105 16:29:25.883446       1 reconciler.go:224] attacherDetacher.DetachVolume started for volume "pvc-8bb4780b-ba8e-45f4-a95b-19397a66ce16" (UniqueName: "kubernetes.io/csi/csi.vsphere.vmware.com^126f913b-4029-4055-91f7-beee75d5d34a") on node "sandbox-corp-ant-antho-0223092-03-u-tm04-ml5m8-7d66645cf-t5q8f"
This volume is not safe to detach, but maxWaitForUnmountDuration 6m0s expired, force detaching

    如要驗證問題，請登入節點並執行下列指令：

    # See all the mounting points with disks
lsblk -f

# See some ext4 errors
sudo dmesg -T

    kubelet 記錄中會顯示類似下列的錯誤：

    Error: GetDeviceMountRefs check failed for volume "pvc-8bb4780b-ba8e-45f4-a95b-19397a66ce16" (UniqueName: "kubernetes.io/csi/csi.vsphere.vmware.com^126f913b-4029-4055-91f7-beee75d5d34a") on node "sandbox-corp-ant-antho-0223092-03-u-tm04-ml5m8-7d66645cf-t5q8f" :
the device mount path "/var/lib/kubelet/plugins/kubernetes.io/csi/pv/pvc-8bb4780b-ba8e-45f4-a95b-19397a66ce16/globalmount" is still mounted by other references [/var/lib/kubelet/plugins/kubernetes.io/csi/pv/pvc-8bb4780b-ba8e-45f4-a95b-19397a66ce16/globalmount

    解決方法：

    使用 SSH 連線至受影響的節點，然後重新啟動節點。
    升級、更新 1.12 以上版本、1.13 以上版本、1.14 以上版本

    如果您使用第三方 CSI 驅動程式，可能無法升級叢集。gkectl cluster diagnose 指令可能會傳回下列錯誤：

    "virtual disk "kubernetes.io/csi/csi.netapp.io^pvc-27a1625f-29e3-4e4f-9cd1-a45237cc472c" IS NOT attached to machine "cluster-pool-855f694cc-cjk5c" but IS listed in the Node.Status"


    解決方法：

    使用 --skip-validation-all 選項執行升級。
    作業 1.10 以上版本、1.11 以上版本、1.12 以上版本、1.13 以上版本、1.14 以上版本

    透過 gkectl repair admin-master 建立的管理員主節點使用的 VM 硬體版本可能低於預期。發生問題時，您會在gkectl diagnose cluster報表中看到錯誤訊息。

    CSIPrerequisites [VM Hardware]: The current VM hardware versions are lower than vmx-15 which is unexpected. Please contact Anthos support to resolve this issue.


    解決方法：

    關閉管理主節點，按照 https://kb.vmware.com/s/article/1003746 的說明將節點升級至錯誤訊息中提及的版本，然後啟動節點。
    作業系統 1.10 以上版本、1.11 以上版本、1.12 以上版本、1.13 以上版本、1.14 以上版本、1.15 以上版本、1.16 以上版本、1.28 以上版本、1.29 以上版本、1.30 以上版本、1.31 以上版本、1.32 以上版本

    在 systemd v244 中，systemd-networkd 的預設行為已變更，KeepConfiguration這項變更前，虛擬機器不會在關機或重新啟動時，將 DHCP 租約釋放訊息傳送至 DHCP 伺服器。變更後，虛擬機會傳送這類訊息，並將 IP 位址傳回 DHCP 伺服器。因此，釋出的 IP 可能會重新分配給其他 VM，且/或 VM 可能會獲派其他 IP，導致 IP 衝突 (在 Kubernetes 層級，而非 vSphere 層級) 和/或 VM 上的 IP 變更，進而以各種方式中斷叢集。

    例如，您可能會出現下列症狀。

    • vCenter UI 顯示沒有任何 VM 使用相同 IP，但 kubectl get nodes -o wide 會傳回具有重複 IP 的節點。 
      NAME   STATUS    AGE  VERSION          INTERNAL-IP    EXTERNAL-IP    OS-IMAGE            KERNEL-VERSION    CONTAINER-RUNTIME
node1  Ready     28h  v1.22.8-gke.204  10.180.85.130  10.180.85.130  Ubuntu 20.04.4 LTS  5.4.0-1049-gkeop  containerd://1.5.13
node2  NotReady  71d  v1.22.8-gke.204  10.180.85.130  10.180.85.130  Ubuntu 20.04.4 LTS  5.4.0-1049-gkeop  containerd://1.5.13
    • 由於 calico-node 錯誤，新節點無法啟動 
      2023-01-19T22:07:08.817410035Z 2023-01-19 22:07:08.817 [WARNING][9] startup/startup.go 1135: Calico node 'node1' is already using the IPv4 address 10.180.85.130.
2023-01-19T22:07:08.817514332Z 2023-01-19 22:07:08.817 [INFO][9] startup/startup.go 354: Clearing out-of-date IPv4 address from this node IP="10.180.85.130/24"
2023-01-19T22:07:08.825614667Z 2023-01-19 22:07:08.825 [WARNING][9] startup/startup.go 1347: Terminating
2023-01-19T22:07:08.828218856Z Calico node failed to start


    解決方法：

    在叢集上部署下列 DaemonSet，即可還原 systemd-networkd 的預設行為變更。執行這個 DaemonSet 的 VM 不會在關機/重新啟動時，將 IP 發布至 DHCP 伺服器。租用期滿時，DHCP 伺服器會自動釋出 IP。 

          apiVersion: apps/v1
      kind: DaemonSet
      metadata:
        name: set-dhcp-on-stop
      spec:
        selector:
          matchLabels:
            name: set-dhcp-on-stop
        template:
          metadata:
            labels:
              name: set-dhcp-on-stop
          spec:
            hostIPC: true
            hostPID: true
            hostNetwork: true
            containers:
            - name: set-dhcp-on-stop
              image: ubuntu
              tty: true
              command:
              - /bin/bash
              - -c
              - |
                set -x
                date
                while true; do
                  export CONFIG=/host/run/systemd/network/10-netplan-ens192.network;
                  grep KeepConfiguration=dhcp-on-stop "${CONFIG}" > /dev/null
                  if (( $? != 0 )) ; then
                    echo "Setting KeepConfiguration=dhcp-on-stop"
                    sed -i '/\[Network\]/a KeepConfiguration=dhcp-on-stop' "${CONFIG}"
                    cat "${CONFIG}"
                    chroot /host systemctl restart systemd-networkd
                  else
                    echo "KeepConfiguration=dhcp-on-stop has already been set"
                  fi;
                  sleep 3600
                done
              volumeMounts:
              - name: host
                mountPath: /host
              resources:
                requests:
                  memory: "10Mi"
                  cpu: "5m"
              securityContext:
                privileged: true
            volumes:
            - name: host
              hostPath:
                path: /
            tolerations:
            - operator: Exists
              effect: NoExecute
            - operator: Exists
              effect: NoSchedule

    作業、升級、更新 1.12.0-1.12.5、1.13.0-1.13.5、1.14.0-1.14.1

    這項問題只會影響從 1.11.x 升級的管理員叢集，不會影響 1.12 之後新建立的管理員叢集。

    將 1.11.x 叢集升級至 1.12.x 後，admin-cluster-creds 密鑰中的 component-access-sa-key 欄位會遭到清除。執行下列指令即可檢查： 

    kubectl --kubeconfig ADMIN_KUBECONFIG -n kube-system get secret admin-cluster-creds -o yaml | grep 'component-access-sa-key'
     如果輸出內容為空白，表示金鑰已清除。

    刪除元件存取服務帳戶金鑰後，安裝新使用者叢集或升級現有使用者叢集都會失敗。以下列出您可能會遇到的錯誤訊息：

    • 驗證前置作業失敗，錯誤訊息："Failed to create the test VMs: failed to get service account key: service account is not configured."
    • 「Prepare by gkectl prepare」失敗，錯誤訊息： "Failed to prepare OS images: dialing: unexpected end of JSON input"
    • 如果您使用 Google Cloud 控制台或 gcloud CLI 升級 1.13 版使用者叢集，當您執行gkectl update admin --enable-preview-user-cluster-central-upgrade部署升級平台控制器時，指令會失敗並顯示以下訊息："failed to download bundle to disk: dialing: unexpected end of JSON input" (您可以在 kubectl --kubeconfig ADMIN_KUBECONFIG -n kube-system get onprembundle -oyaml 輸出內容的 status 欄位中看到這則訊息)。


    解決方法：

    執行下列指令，手動將元件存取服務帳戶金鑰重新新增至密鑰：

    kubectl --kubeconfig ADMIN_KUBECONFIG -n kube-system get secret admin-cluster-creds -ojson | jq --arg casa "$(cat COMPONENT_ACESS_SERVICE_ACOOUNT_KEY_PATH | base64 -w 0)" '.data["component-access-sa-key"]=$casa' | kubectl --kubeconfig ADMIN_KUBECONFIG apply -f -

    作業 1.13.0 以上版本、1.14.0 以上版本

    如果使用者叢集是透過啟用 Controlplane V2 建立，則啟用自動調度資源的節點集區一律會在 user-cluster.yaml 中使用 autoscaling.minReplicas。叢集自動配置器 Pod 的記錄檔會顯示類似下列的錯誤：

      > kubectl --kubeconfig $USER_CLUSTER_KUBECONFIG -n kube-system \
  logs $CLUSTER_AUTOSCALER_POD --container_cluster-autoscaler
 TIMESTAMP  1 gkeonprem_provider.go:73] error getting onpremusercluster ready status: Expected to get a onpremusercluster with id foo-user-cluster-gke-onprem-mgmt/foo-user-cluster
 TIMESTAMP 1 static_autoscaler.go:298] Failed to get node infos for groups: Expected to get a onpremusercluster with id foo-user-cluster-gke-onprem-mgmt/foo-user-cluster
    執行下列指令，即可找到叢集自動配置器 Pod。 
      > kubectl --kubeconfig $USER_CLUSTER_KUBECONFIG -n kube-system \
   get pods | grep cluster-autoscaler
cluster-autoscaler-5857c74586-txx2c                          4648017n    48076Ki    30s


    解決方法：

    使用 `gkectl update cluster` 停用所有節點集區的自動調度功能，直到升級至修正版本為止
    安裝 1.12.0-1.12.4、1.13.0-1.13.3、1.14.0

    如果使用者在 IP 區塊檔案中使用 CIDR，設定驗證會失敗，並顯示下列錯誤： 

    - Validation Category: Config Check
    - [FAILURE] Config: AddressBlock for admin cluster spec is invalid: invalid IP:
172.16.20.12/30


    解決方法：

    在升級至修正版本 (1.12.5、1.13.4、1.14.1 以上版本) 前，請在 IP 區塊檔案中加入個別 IP。
    升級、更新 1.14.0-1.14.1

    在 admin-cluster.yaml 中更新控制層 OS 映像檔類型時，如果對應的使用者叢集是使用 enableControlplaneV2 設為 true 建立，使用者控制層機器可能不會在 gkectl 指令完成時完成重新建立作業。


    解決方法：

    更新完成後，請繼續等待使用者控制層機器完成重新建立作業，並使用 kubectl --kubeconfig USER_KUBECONFIG get nodes -owide 監控節點 OS 映像檔類型。舉例來說，如果從 Ubuntu 更新至 COS，即使更新指令完成，也應等待所有控制平面機器完全從 Ubuntu 變更為 COS。

    作業 1.10、1.11、1.12、1.13、1.14.0

    Google Distributed Cloud 1.14.0 中的 Calico 發生問題，導致 Pod 建立和刪除作業失敗，並在 kubectl describe pods 的輸出內容中顯示下列錯誤訊息：

      error getting ClusterInformation: connection is unauthorized: Unauthorized

    只有在叢集建立或升級至 1.14 後 24 小時，使用 Calico 時才會發生這個問題。

    管理員叢集一律使用 Calico，而使用者叢集則在 user-cluster.yaml 中有 `enableDataPlaneV2` 設定欄位。如果該欄位設為 `false` 或未指定，表示您在使用者叢集中使用 Calico。

    節點的 install-cni 容器會建立 kubeconfig，內含效期 24 小時的權杖。這個權杖需要由 calico-node Pod 定期更新。calico-node Pod 無法更新權杖，因為它無法存取節點上包含 kubeconfig 檔案的目錄。


    解決方法：

    Google Distributed Cloud 1.14.1 版已修正這個問題。請升級至這個版本或更新版本。

    如果無法立即升級，請在管理員和使用者叢集的 calico-node DaemonSet 中套用下列修補程式：

      kubectl -n kube-system get daemonset calico-node \
    --kubeconfig ADMIN_CLUSTER_KUBECONFIG -o json \
    | jq '.spec.template.spec.containers[0].volumeMounts += [{"name":"cni-net-dir","mountPath":"/host/etc/cni/net.d"}]' \
    | kubectl apply --kubeconfig ADMIN_CLUSTER_KUBECONFIG -f -

  kubectl -n kube-system get daemonset calico-node \
    --kubeconfig USER_CLUSTER_KUBECONFIG -o json \
    | jq '.spec.template.spec.containers[0].volumeMounts += [{"name":"cni-net-dir","mountPath":"/host/etc/cni/net.d"}]' \
    | kubectl apply --kubeconfig USER_CLUSTER_KUBECONFIG -f -
    取代下列項目：
    • ADMIN_CLUSTER_KUBECONFIG：管理員叢集 kubeconfig 檔案的路徑。
    • USER_CLUSTER_CONFIG_FILE：使用者叢集設定檔的路徑。
    安裝 1.12.0-1.12.4、1.13.0-1.13.3、1.14.0

    即使使用者設定正確，仍無法建立叢集。使用者會看到建立作業失敗，因為叢集的 IP 不足。


    解決方法：

    將 CIDR 拆分成多個較小的 CIDR 區塊，例如 10.0.0.0/30 會變成 10.0.0.0/31, 10.0.0.2/31。只要有 N+1 個 CIDR，其中 N 是叢集中的節點數量，這就足夠了。

    作業、升級、更新 1.11.0 - 1.11.1、1.10.0 - 1.10.4、1.9.0 - 1.9.6

    如果啟用永久密碼加密功能，且同時備份叢集，管理員叢集備份作業會無法納入永久密碼加密功能所需的加密金鑰和設定。因此，使用 gkectl repair admin-master --restore-from-backup 透過這項備份資料修復管理主機時，會導致下列錯誤：

    Validating admin master VM xxx ...
Waiting for kube-apiserver to be accessible via LB VIP (timeout "8m0s")...  ERROR
Failed to access kube-apiserver via LB VIP. Trying to fix the problem by rebooting the admin master
Waiting for kube-apiserver to be accessible via LB VIP (timeout "13m0s")...  ERROR
Failed to access kube-apiserver via LB VIP. Trying to fix the problem by rebooting the admin master
Waiting for kube-apiserver to be accessible via LB VIP (timeout "18m0s")...  ERROR
Failed to access kube-apiserver via LB VIP. Trying to fix the problem by rebooting the admin master

    作業、升級、更新 1.10 以上版本

    如果在建立叢集時未啟用永久啟用密鑰加密功能，但之後使用 gkectl update 作業啟用，則 gkectl repair admin-master 無法修復管理員叢集控制層節點。建議您在建立叢集時啟用永久密碼加密功能。目前沒有緩解措施。

    升級、更新 1.10

    將第一個使用者叢集從 1.9 升級至 1.10 時，可能會在同一管理員叢集下的其他使用者叢集重新建立節點。系統會以滾動方式執行重建作業。

    「disk_label」已從「MachineTemplate.spec.template.spec.providerSpec.machineVariables」中移除，導致所有「MachineDeployment」意外更新。


    解決方法：
    升級、更新 1.10.0

    將使用者叢集升級至 1.10.0 可能會導致 Docker 頻繁重新啟動。

    如要偵測這個問題，請執行 kubectl describe node NODE_NAME --kubeconfig USER_CLUSTER_KUBECONFIG

    節點狀況會顯示 Docker 是否經常重新啟動。以下是輸出範例：

    Normal   FrequentDockerRestart    41m (x2 over 141m)     systemd-monitor  Node condition FrequentDockerRestart is now: True, reason: FrequentDockerRestart

    如要瞭解根本原因，您需要透過 SSH 連線至出現徵兆的節點，並執行 sudo journalctl --utc -u docker 或 sudo journalctl -x 等指令


    解決方法：
    升級、更新 1.11、1.12

    如果您使用的 Google Distributed Cloud 版本低於 1.12，且已在叢集的 gmp-system 命名空間中手動設定 Google 管理的 Prometheus (GMP) 元件，則升級至 1.12.x 版時，這些元件不會保留。

    從 1.12 版開始，gmp-system 命名空間中的 GMP 元件和 CRD 會由 stackdriver 物件管理，且 enableGMPForApplications 旗標預設會設為 false。如果您在升級至 1.12 版前，手動在命名空間中部署 GMP 元件，stackdriver 會刪除這些資源。


    解決方法：
    作業 1.11、1.12、1.13.0 - 1.13.1

    在 system 情境中，叢集快照不包含 default 命名空間下的任何資源。

    不過，這個命名空間下的部分 Kubernetes 資源 (例如 Cluster API 物件) 包含實用的偵錯資訊。叢集快照應包含這些項目。


    解決方法：

    您可以手動執行下列指令，收集偵錯資訊。

    export KUBECONFIG=USER_CLUSTER_KUBECONFIG
kubectl get clusters.cluster.k8s.io -o yaml
kubectl get controlplanes.cluster.k8s.io -o yaml
kubectl get machineclasses.cluster.k8s.io -o yaml
kubectl get machinedeployments.cluster.k8s.io -o yaml
kubectl get machines.cluster.k8s.io -o yaml
kubectl get machinesets.cluster.k8s.io -o yaml
kubectl get services -o yaml
kubectl describe clusters.cluster.k8s.io
kubectl describe controlplanes.cluster.k8s.io
kubectl describe machineclasses.cluster.k8s.io
kubectl describe machinedeployments.cluster.k8s.io
kubectl describe machines.cluster.k8s.io
kubectl describe machinesets.cluster.k8s.io
kubectl describe services
     where:

    USER_CLUSTER_KUBECONFIG 是使用者叢集的 kubeconfig 檔案。
    升級、更新 1.11.0-1.11.4、1.12.0-1.12.3、1.13.0-1.13.1

    刪除、更新或升級使用者叢集時，節點排空作業可能會在下列情況下停滯：

    • 管理員叢集自 1.12.x 版起，就已在 vSAN 上使用 vSphere CSI 驅動程式，且
    • 管理員和使用者叢集中，沒有由樹內 vSphere 外掛程式建立的 PVC/PV 物件。

    如要找出症狀，請執行下列指令：

    kubectl logs clusterapi-controllers-POD_NAME_SUFFIX  --kubeconfig ADMIN_KUBECONFIG -n USER_CLUSTER_NAMESPACE

    以下是上述指令的錯誤訊息範例：

    E0920 20:27:43.086567 1 machine_controller.go:250] Error deleting machine object [MACHINE]; Failed to delete machine [MACHINE]: failed to detach disks from VM "[MACHINE]": failed to convert disk path "kubevols" to UUID path: failed to convert full path "ds:///vmfs/volumes/vsan:[UUID]/kubevols": ServerFaultCode: A general system error occurred: Invalid fault

    kubevols 是 vSphere 樹狀結構內驅動程式的預設目錄。如果沒有建立 PVC/PV 物件，您可能會遇到錯誤，導致節點排空作業卡在尋找 kubevols 的階段，因為目前的實作方式假設 kubevols 一定存在。


    解決方法：

    在建立節點的資料儲存庫中建立 kubevols 目錄。這是在 user-cluster.yaml 或 admin-cluster.yaml 檔案的 vCenter.datastore 欄位中定義。
    設定 1.7、1.8、1.9、1.10、1.11、1.12、1.13、1.14

    刪除使用者叢集時，系統也會刪除叢集自動配置器的對應 clusterrole 和 clusterrolebinding。這會影響同一管理員叢集上所有其他已啟用叢集自動調度資源功能的使用者叢集。這是因為同一個管理員叢集內的所有叢集自動調度器 Pod 都使用相同的 clusterrole 和 clusterrolebinding。

    症狀如下：

    • cluster-autoscaler 記錄
      • kubectl logs --kubeconfig ADMIN_CLUSTER_KUBECONFIG -n kube-system \
cluster-autoscaler
       其中 ADMIN_CLUSTER_KUBECONFIG 是管理員叢集的 kubeconfig 檔案。 以下是您可能會看到的錯誤訊息範例： 
      2023-03-26T10:45:44.866600973Z W0326 10:45:44.866463       1 reflector.go:424] k8s.io/client-go/dynamic/dynamicinformer/informer.go:91: failed to list *unstructured.Unstructured: onpremuserclusters.onprem.cluster.gke.io is forbidden: User "..." cannot list resource "onpremuserclusters" in API group "onprem.cluster.gke.io" at the cluster scope
2023-03-26T10:45:44.866646815Z E0326 10:45:44.866494       1 reflector.go:140] k8s.io/client-go/dynamic/dynamicinformer/informer.go:91: Failed to watch *unstructured.Unstructured: failed to list *unstructured.Unstructured: onpremuserclusters.onprem.cluster.gke.io is forbidden: User "..." cannot list resource "onpremuserclusters" in API group "onprem.cluster.gke.io" at the cluster scope

    解決方法：

    設定 1.7、1.8、1.9、1.10、1.11、1.12、1.13

    刪除使用者叢集時，系統也會刪除對應的 clusterrole，導致自動修復和 vSphere 指標匯出工具無法運作

    症狀如下：

    • cluster-health-controller 記錄
      • kubectl logs --kubeconfig ADMIN_CLUSTER_KUBECONFIG -n kube-system \
cluster-health-controller
       其中 ADMIN_CLUSTER_KUBECONFIG 是管理員叢集的 kubeconfig 檔案。 以下是您可能會看到的錯誤訊息範例： 
      error retrieving resource lock default/onprem-cluster-health-leader-election: configmaps "onprem-cluster-health-leader-election" is forbidden: User "system:serviceaccount:kube-system:cluster-health-controller" cannot get resource "configmaps" in API group "" in the namespace "default": RBAC: clusterrole.rbac.authorization.k8s.io "cluster-health-controller-role" not found
    • vsphere-metrics-exporter 記錄
      • kubectl logs --kubeconfig ADMIN_CLUSTER_KUBECONFIG -n kube-system \
vsphere-metrics-exporter
       其中 ADMIN_CLUSTER_KUBECONFIG 是管理員叢集的 kubeconfig 檔案。 以下是您可能會看到的錯誤訊息範例： 
      vsphere-metrics-exporter/cmd/vsphere-metrics-exporter/main.go:68: Failed to watch *v1alpha1.Cluster: failed to list *v1alpha1.Cluster: clusters.cluster.k8s.io is forbidden: User "system:serviceaccount:kube-system:vsphere-metrics-exporter" cannot list resource "clusters" in API group "cluster.k8s.io" in the namespace "default"

    解決方法：

    設定 1.12.1-1.12.3、1.13.0-1.13.2

    已知問題：可能導致 gkectl check-config 失敗，且不會執行 gkectl prepare。這會造成混淆，因為我們建議先執行指令，再執行 gkectl prepare

    徵兆是 gkectl check-config 指令會失敗，並顯示下列錯誤訊息：

    Validator result: {Status:FAILURE Reason:os images [OS_IMAGE_NAME] don't exist, please run `gkectl prepare` to upload os images. UnhealthyResources:[]}

    解決方法：

    方法 1：執行 gkectl prepare 上傳缺少的 OS 映像檔。

    選項 2：使用 gkectl check-config --skip-validation-os-images 略過 OS 映像檔驗證。
    升級、更新 1.11、1.12、1.13

    已知問題：更新 anti affinity groups 時，gkectl update admin/cluster 可能會失敗。

    徵兆是 gkectl update 指令會失敗，並顯示下列錯誤訊息：

    Waiting for machines to be re-deployed...  ERROR
Exit with error:
Failed to update the cluster: timed out waiting for the condition

    解決方法：
    安裝、升級、更新 1.13.0-1.13.8、1.14.0-1.14.4、1.15.0

    在叢集建立、升級、更新和節點自動修復期間，如果 ipMode.type 為 static，且IP 區塊檔案中設定的主機名稱包含一或多個半形句號，節點註冊就會失敗。在這種情況下，系統不會自動核准節點的憑證簽署要求 (CSR)。

    如要查看節點的待處理 CSR，請執行下列指令：

    kubectl get csr -A -o wide

    檢查下列記錄檔中的錯誤訊息：

    • 查看管理員叢集中 clusterapi-controller-manager 容器的記錄檔 (位於 clusterapi-controllers Pod 中)：
      kubectl logs clusterapi-controllers-POD_NAME \
    -c clusterapi-controller-manager -n kube-system \
    --kubeconfig ADMIN_CLUSTER_KUBECONFIG
    • 如要在使用者叢集中查看相同記錄，請執行下列指令：
      kubectl logs clusterapi-controllers-POD_NAME \
    -c clusterapi-controller-manager -n USER_CLUSTER_NAME \
    --kubeconfig ADMIN_CLUSTER_KUBECONFIG
       其中：
      • ADMIN_CLUSTER_KUBECONFIG 是管理員叢集的 kubeconfig 檔案。
      • USER_CLUSTER_NAME 是使用者叢集的名稱。
      以下是您可能會看到的錯誤訊息範例："msg"="failed to validate token id" "error"="failed to find machine for node node-worker-vm-1" "validate"="csr-5jpx9"
    • 查看有問題節點上的 kubelet 記錄： 
      journalctl --u kubelet
       以下是您可能會看到的錯誤訊息範例："Error getting node" err="node \"node-worker-vm-1\" not found"

    如果您在 IP 封鎖檔案的主機名稱欄位中指定網域名稱，系統會忽略第一個半形句號後方的所有字元。舉例來說，如果將主機名稱指定為 bob-vm-1.bank.plc，VM 主機名稱和節點名稱就會設為 bob-vm-1。

    啟用節點 ID 驗證後，CSR 核准者會比較節點名稱與機器規格中的主機名稱，並無法調解名稱。核准者拒絕 CSR，節點無法啟動。


    解決方法：

    使用者群組

    如要停用節點 ID 驗證，請完成下列步驟：

    1. 在使用者叢集設定檔中新增下列欄位： 
      disableNodeIDVerification: true
disableNodeIDVerificationCSRSigning: true
    2. 儲存檔案，然後執行下列指令更新使用者叢集：
      gkectl update cluster --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    --config USER_CLUSTER_CONFIG_FILE
       取代下列項目：
      • ADMIN_CLUSTER_KUBECONFIG：管理員叢集 kubeconfig 檔案的路徑。
      • USER_CLUSTER_CONFIG_FILE：使用者叢集設定檔的路徑。

    管理員叢集

    1. 開啟 OnPremAdminCluster 自訂資源進行編輯：
      kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    edit onpremadmincluster -n kube-system
    2. 將下列註解新增至自訂資源： 
      features.onprem.cluster.gke.io/disable-node-id-verification: enabled
    3. 在管理員叢集控制層中編輯 kube-controller-manager 資訊清單：
      1. 透過 SSH 連線至管理員叢集控制層節點。
      2. 開啟 kube-controller-manager 資訊清單進行編輯：
        sudo vi /etc/kubernetes/manifests/kube-controller-manager.yaml
      3. 找出 controllers 清單： 
        --controllers=*,bootstrapsigner,tokencleaner,-csrapproving,-csrsigning
      4. 請將下列區段更新為： 
        --controllers=*,bootstrapsigner,tokencleaner
    4. 開啟 Deployment Cluster API 控制器進行編輯： 
      kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    edit deployment clusterapi-controllers -n kube-system
    5. 將 node-id-verification-enabled 和 node-id-verification-csr-signing-enabled 的值變更為 false：
      --node-id-verification-enabled=false
--node-id-verification-csr-signing-enabled=false
    安裝、升級、更新 1.11.0-1.11.4

    管理員叢集建立/升級作業永遠停留在下列記錄，最終會逾時：

    Waiting for Machine gke-admin-master-xxxx to become ready...

    在 1.11 版說明文件中， 外部叢集快照中的 Cluster API 控制器記錄包含下列記錄：

    Invalid value 'XXXX' specified for property startup-data

    以下是 Cluster API 控制器記錄的檔案路徑範例：

    kubectlCommands/kubectl_logs_clusterapi-controllers-c4fbb45f-6q6g6_--container_vsphere-controller-manager_--kubeconfig_.home.ubuntu..kube.kind-config-gkectl_--request-timeout_30s_--namespace_kube-system_--timestamps
    
    VMware has a 64k vApp property size limit. In the identified versions,
    the data passed via vApp property is close to the limit. When the private
    registry certificate contains a certificate bundle, it may cause the final
    data to exceed the 64k limit.
    
    
    Workaround:
    
    
    Only include the required certificates in the private registry
    certificate file configured in privateRegistry.caCertPath in
    the admin cluster config file.
    
    
    Or upgrade to a version with the fix when available.
    Networking 1.10, 1.11.0-1.11.3, 1.12.0-1.12.2, 1.13.0

    In networkgatewaygroups.status.nodes, some nodes switch between NotHealthy and Up.

    Logs for the ang-daemon Pod running on that node reveal repeated errors: 

    2022-09-16T21:50:59.696Z ERROR ANGd Failed to report status {"angNode": "kube-system/my-node", "error": "updating Node CR status: sending Node CR update: Operation cannot be fulfilled on networkgatewaynodes.networking.gke.io \"my-node\": the object has been modified; please apply your changes to the latest version and try again"}

    NotHealthy 狀態會禁止控制器將額外的浮動 IP 指派給節點。這可能會導致其他節點的負擔增加，或是缺乏高可用性的備援機制。

    資料平面活動不會受到影響。

    networkgatewaygroup 物件發生爭用，導致重試處理程序發生錯誤，因此部分狀態更新作業失敗。如果太多狀態更新失敗，ang-controller-manager 會將節點視為超過心跳時間限制，並標記節點 NotHealthy。

    後續版本已修正重試處理程序中的錯誤。


    解決方法：

    如有修正版本，請升級至該版本。
    升級、更新 1.12.0-1.12.2、1.13.0

    已知問題：叢集升級或更新作業可能會停滯，等待舊機器物件刪除。這是因為無法從機器物件中移除終結器。這會影響節點集區的所有滾動更新作業。

    徵兆是 gkectl 指令逾時，並顯示下列錯誤訊息：

    E0821 18:28:02.546121   61942 console.go:87] Exit with error:
E0821 18:28:02.546184   61942 console.go:87] error: timed out waiting for the condition, message: Node pool "pool-1" is not ready: ready condition is not true: CreateOrUpdateNodePool: 1/3 replicas are updated
Check the status of OnPremUserCluster 'cluster-1-gke-onprem-mgmt/cluster-1' and the logs of pod 'kube-system/onprem-user-cluster-controller' for more detailed debugging information.

    在 clusterapi-controller Pod 記錄中，錯誤如下所示：

    $ kubectl logs clusterapi-controllers-[POD_NAME_SUFFIX] -n cluster-1
    -c vsphere-controller-manager --kubeconfig [ADMIN_KUBECONFIG]
    | grep "Error removing finalizer from machine object"
[...]
E0821 23:19:45.114993       1 machine_controller.go:269] Error removing finalizer from machine object cluster-1-pool-7cbc496597-t5d5p; Operation cannot be fulfilled on machines.cluster.k8s.io "cluster-1-pool-7cbc496597-t5d5p": the object has been modified; please apply your changes to the latest version and try again

    即使沒有這個問題，成功執行的同一部電腦也會重複發生錯誤幾分鐘，大部分時間可以快速完成，但有時可能會卡在這個競爭條件中好幾個小時。

    問題在於基礎 VM 已在 vCenter 中刪除，但對應的機器物件無法移除，由於其他控制器非常頻繁地更新，因此最終移除程序會卡住。這可能會導致 gkectl 指令逾時，但控制器會持續調解叢集，因此升級或更新程序最終會完成。


    解決方法：

    我們針對這個問題準備了幾種不同的解決方案，具體做法視您的環境和需求而定。

    • 選項 1：等待系統自行完成升級。

      根據您環境中的分析和重現結果，升級最終可能會自行完成，無須手動介入。但請注意，我們無法確定每個機器物件的終結器移除作業需要多久時間。如果運氣好，可以立即完成，但如果機器集控制器協調速度過快，機器控制器在協調之間沒有機會移除終結器，則可能需要數小時。

      好消息是，您不必採取任何行動，工作負載也不會中斷。升級作業需要較長的時間才能完成。
    • 選項 2：對所有舊機器物件套用自動修復註解。

      機器集控制器會篩除具有自動修復註解且刪除時間戳記不為零的機器，並停止對這些機器發出刪除呼叫，這有助於避免競爭狀況。

      缺點是機器上的 Pod 會直接刪除，而不是逐出，這表示系統不會遵守 PDB 設定，可能會導致工作負載停機。

      取得所有電腦名稱的指令： 
      kubectl --kubeconfig CLUSTER_KUBECONFIG get machines
       為每部機器套用自動修復註解的指令： 
      kubectl annotate --kubeconfig CLUSTER_KUBECONFIG \
    machine MACHINE_NAME \
    onprem.cluster.gke.io/repair-machine=true

    如果發生這個問題，且升級或更新程序長時間無法完成，請與支援團隊聯絡，尋求解決方法。
    安裝、升級、更新 1.10.2、1.11、1.12、1.13

    gkectl prepare 指令失敗，原因如下：

    - Validation Category: OS Images
    - [FAILURE] Admin cluster OS images exist: os images [os_image_name] don't exist, please run `gkectl prepare` to upload os images.

    gkectl prepare 的預檢包含不正確的驗證。


    解決方法：

    執行相同指令，並加上額外旗標 --skip-validation-os-images。
    安裝 1.7、1.8、1.9、1.10、1.11、1.12、1.13

    無法建立管理員叢集，原因如下：

    Exit with error:
Failed to create root cluster: unable to apply admin base bundle to external cluster: error: timed out waiting for the condition, message:
Failed to apply external bundle components: failed to apply bundle objects from admin-vsphere-credentials-secret 1.x.y-gke.z to cluster external: Secret "vsphere-dynamic-credentials" is invalid:
[data[https://xxx.xxx.xxx.username]: Invalid value: "https://xxx.xxx.xxx.username": a valid config key must consist of alphanumeric characters, '-', '_' or '.'
(e.g. 'key.name', or 'KEY_NAME', or 'key-name', regex used for validation is '[-._a-zA-Z0-9]+'), data[https://xxx.xxx.xxx.password]:
Invalid value: "https://xxx.xxx.xxx.password": a valid config key must consist of alphanumeric characters, '-', '_' or '.'
(e.g. 'key.name', or 'KEY_NAME', or 'key-name', regex used for validation is '[-._a-zA-Z0-9]+')]

    網址會做為密鑰的一部分，但密鑰不支援「/」或「:」。


    解決方法：

    從管理員叢集或使用者叢集設定 YAML 的 vCenter.Address 欄位中移除 https:// 或 http:// 前置字元。
    安裝、升級、更新 1.10、1.11、1.12、1.13

    gkectl prepare 可能會發生恐慌，並顯示下列堆疊追蹤：

    panic: runtime error: invalid memory address or nil pointer dereference [signal SIGSEGV: segmentation violation code=0x1 addr=0x18 pc=0xde0dfa]

goroutine 1 [running]:
gke-internal.googlesource.com/syllogi/cluster-management/pkg/util.CheckFileExists(0xc001602210, 0x2b, 0xc001602210, 0x2b) pkg/util/util.go:226 +0x9a
gke-internal.googlesource.com/syllogi/cluster-management/gkectl/pkg/config/util.SetCertsForPrivateRegistry(0xc000053d70, 0x10, 0xc000f06f00, 0x4b4, 0x1, 0xc00015b400)gkectl/pkg/config/util/utils.go:75 +0x85
...

    問題在於 gkectl prepare 建立私有登錄檔憑證目錄時，權限有誤。


    解決方法：

    如要修正這個問題，請在管理員工作站執行下列指令：

    sudo mkdir -p /etc/docker/certs.d/PRIVATE_REGISTRY_ADDRESS
sudo chmod 0755 /etc/docker/certs.d/PRIVATE_REGISTRY_ADDRESS
    升級、更新 1.10、1.11、1.12、1.13

    管理員叢集升級嘗試失敗後，請勿執行 gkectl repair admin-master。這麼做可能會導致後續的管理員升級嘗試失敗，並發生管理員主機無法啟動電源或無法存取 VM 等問題。


    解決方法：

    如果已發生這種失敗情況，請與支援團隊聯絡。
    升級、更新 1.10、1.11

    如果管理員控制層機器在恢復管理員叢集升級作業後未重新建立，管理員控制層 VM 範本就會遭到刪除。管理員控制層 VM 範本是管理員主節點的範本，用於透過 gkectl repair admin-master 復原控制層機器。


    解決方法：

    下次升級管理員叢集時，系統會重新產生管理員控制層 VM 範本。
    作業系統 1.12、1.13

    在 1.12.0 版中，Container Optimized OS (COS) 節點預設會啟用 cgroup v2 (統一)。這可能會導致 COS 叢集中的工作負載不穩定。


    解決方法：

    我們在 1.12.1 版中切換回 cgroup v1 (混合式)。如果您使用 COS 節點，建議您在 1.12.1 版發布後盡快升級。
    身分識別 1.10、1.11、1.12、1.13

    gkectl update 會還原您對 ClientConfig 自訂資源所做的任何手動變更。


    解決方法：

    強烈建議您在每次手動變更後備份 ClientConfig 資源。
    安裝 1.10、1.11、1.12、1.13

    找不到 F5 BIG-IP 分區，因此驗證失敗 (即使分區存在)。

    F5 BIG-IP API 的問題可能會導致驗證失敗。


    解決方法：

    請再次執行 gkectl check-config。
    安裝 1.12

    如果 apiserver/etcd 速度緩慢，您可能會看到因 cert-manager-cainjector 處於 crashloop 狀態而導致的安裝失敗：

    # These are logs from `cert-manager-cainjector`, from the command
# `kubectl --kubeconfig USER_CLUSTER_KUBECONFIG -n kube-system
  cert-manager-cainjector-xxx`

I0923 16:19:27.911174       1 leaderelection.go:278] failed to renew lease kube-system/cert-manager-cainjector-leader-election: timed out waiting for the condition

E0923 16:19:27.911110       1 leaderelection.go:321] error retrieving resource lock kube-system/cert-manager-cainjector-leader-election-core:
  Get "https://10.96.0.1:443/api/v1/namespaces/kube-system/configmaps/cert-manager-cainjector-leader-election-core": context deadline exceeded

I0923 16:19:27.911593       1 leaderelection.go:278] failed to renew lease kube-system/cert-manager-cainjector-leader-election-core: timed out waiting for the condition

E0923 16:19:27.911629       1 start.go:163] cert-manager/ca-injector "msg"="error running core-only manager" "error"="leader election lost"

    解決方法：
    VMware 1.10、1.11、1.12、1.13

    如果 vCenter (7.0U2 以下版本) 在升級或其他情況後重新啟動，vCenter 提供的 VM 資訊中的網路名稱會不正確，導致機器處於 Unavailable 狀態。這最終會導致節點自動修復，並建立新節點。

    相關 govmomi 錯誤。


    解決方法：

    VMware 支援團隊提供的解決方法如下：

    1. 這項問題已在 vCenter 7.0U2 以上版本中修正。
    2. 如果是較舊的版本，請在主機上按一下滑鼠右鍵，然後依序選取「連線」>「中斷連線」。接著重新連線，強制更新 VM 的連接埠群組。
    作業系統 1.10、1.11、1.12、1.13

    如果是 Google Distributed Cloud 1.7.2 以上版本，Ubuntu 作業系統映像檔會以 CIS L1 伺服器基準強化。

    為符合 CIS 規則「5.2.16 Ensure SSH Idle Timeout Interval is configured」，/etc/ssh/sshd_config 具有下列設定：

    ClientAliveInterval 300
ClientAliveCountMax 0

    這些設定的目的是在閒置 5 分鐘後終止用戶端工作階段。不過，ClientAliveCountMax 0 值會導致非預期的行為。在管理工作站或叢集節點上使用 SSH 工作階段時，即使 SSH 用戶端並未閒置 (例如執行耗時的指令)，SSH 連線仍可能會中斷，且指令可能會終止並顯示下列訊息：

    Connection to [IP] closed by remote host.
Connection to [IP] closed.

    解決方法：

    你可以採取下列任一做法：

    • 使用 nohup 可防止指令在 SSH 中斷連線時終止，
      nohup gkectl upgrade admin --config admin-cluster.yaml \
    --kubeconfig kubeconfig
    • 更新 sshd_config，使用非零的 ClientAliveCountMax 值。CIS 規則建議使用小於 3 的值：
      sudo sed -i 's/ClientAliveCountMax 0/ClientAliveCountMax 1/g' \
    /etc/ssh/sshd_config
sudo systemctl restart sshd

    請務必重新連線 SSH 工作階段。
    安裝 1.10、1.11、1.12、1.13

    在 1.13 版中，monitoring-operator 會在 cert-manager 命名空間中安裝 cert-manager。如果基於特定原因需要自行安裝 cert-manager，請按照下列操作說明進行，以免發生衝突：

    每個叢集只需套用一次這個解決方法，且變更會在叢集升級後保留。

    注意：安裝自己的 cert-manager 時，常見的症狀是 cert-manager 版本或映像檔 (例如 v1.7.2) 可能會還原為舊版。這是因為 monitoring-operator 嘗試調解 cert-manager，並在過程中還原版本。

    解決方法：

    <p避免升級期間發生衝突

    1. 解除安裝 cert-manager。如果您定義了自己的資源，建議備份 這些資源。
    2. 執行升級。
    3. 請按照下列指示還原自己的 cert-manager。

    在使用者叢集中還原自己的 cert-manager

    • 將 monitoring-operator Deployment 調整為 0： 
      kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    -n USER_CLUSTER_NAME \
    scale deployment monitoring-operator --replicas=0
    • 將 monitoring-operator 管理的 cert-manager 部署作業規模調整為 0：
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    -n cert-manager scale deployment cert-manager --replicas=0
kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    -n cert-manager scale deployment cert-manager-cainjector\
    --replicas=0
kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    -n cert-manager scale deployment cert-manager-webhook --replicas=0
    • 重新安裝 cert-manager 版本。 還原自訂資源 (如有)。
    • 如果您使用 上游預設的 cert-manager 安裝，或確定 cert-manager 安裝在 cert-manager 命名空間中，則可略過這個步驟。否則，請從 cert-manager 將 metrics-ca cert-manager.io/v1 憑證和 metrics-pki.cluster.local簽發者資源複製到已安裝 cert-manager 的叢集資源命名空間。
      relevant_fields='
{
  apiVersion: .apiVersion,
  kind: .kind,
  metadata: {
    name: .metadata.name,
    namespace: "YOUR_INSTALLED_CERT_MANAGER_NAMESPACE"
  },
  spec: .spec
}
'
f1=$(mktemp)
f2=$(mktemp)
kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    get issuer -n cert-manager metrics-pki.cluster.local -o json \
    | jq "${relevant_fields}" > $f1
kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    get certificate -n cert-manager metrics-ca -o json \
    | jq "${relevant_fields}" > $f2
kubectl apply --kubeconfig USER_CLUSTER_KUBECONFIG -f $f1
kubectl apply --kubeconfig USER_CLUSTER_KUBECONFIG -f $f2

    在管理員叢集中還原自己的 cert-manager

    一般來說，您不需要在管理員叢集中重新安裝 cert-manager，因為管理員叢集只會執行 Google Distributed Cloud 控制層工作負載。在極少數情況下，您也需要在管理員叢集中安裝自己的 cert-manager，請按照下列指示操作，以免發生衝突。請注意，如果您是 Apigee 客戶，且只需要 Apigee 的 cert-manager，就不必執行管理員叢集指令。

    • 將 monitoring-operator Deployment 資源調度為 0。 
      kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    -n kube-system scale deployment monitoring-operator --replicas=0
    • 將 monitoring-operator 管理的 cert-manager 部署作業規模縮減為 0。
      kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    -n cert-manager scale deployment cert-manager \
    --replicas=0

kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
     -n cert-manager scale deployment cert-manager-cainjector \
     --replicas=0

kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    -n cert-manager scale deployment cert-manager-webhook \
    --replicas=0
    • 重新安裝 cert-manager 版本。 還原自訂資源 (如有)。
    • 如果您使用 上游預設的 cert-manager 安裝，或確定 cert-manager 安裝在 cert-manager 命名空間中，則可略過這個步驟。否則，請從 cert-manager 將 metrics-ca cert-manager.io/v1 憑證和 metrics-pki.cluster.local簽發者資源複製到已安裝 cert-manager 的叢集資源命名空間。
      relevant_fields='
{
  apiVersion: .apiVersion,
  kind: .kind,
  metadata: {
    name: .metadata.name,
    namespace: "YOUR_INSTALLED_CERT_MANAGER_NAMESPACE"
  },
  spec: .spec
}
'
f3=$(mktemp)
f4=$(mktemp)
kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \n
    get issuer -n cert-manager metrics-pki.cluster.local -o json \
    | jq "${relevant_fields}" > $f3
kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    get certificate -n cert-manager metrics-ca -o json \
    | jq "${relevant_fields}" > $f4
kubectl apply --kubeconfig ADMIN_CLUSTER_KUBECONFIG -f $f3
kubectl apply --kubeconfig ADMIN_CLUSTER_KUBECONFIG -f $f4
    </p
    作業系統 1.10、1.11、1.12、1.13

    Google Distributed Cloud 隨附的 Ubuntu OS 映像檔中，Docker、containerd 和 runc 會使用 Ubuntu PPA 固定為特定版本。這可確保每次發布前，Google Distributed Cloud 都會先驗證所有容器執行階段變更。

    不過，Ubuntu CVE Tracker並不知道這些特殊版本，而各種 CVE 掃描工具都會使用這個追蹤器做為安全漏洞動態消息。因此，您會在 Docker、containerd 和 runc 安全漏洞掃描結果中看到誤判。

    舉例來說，您可能會在 CVE 掃描結果中看到下列誤判。Google Distributed Cloud 的最新修補程式版本已修正這些 CVE。

    如需任何 CVE 修復程式，請參閱版本資訊。


    解決方法：

    Canonical 已知悉這個問題，並在 https://github.com/canonical/sec-cvescan/issues/73 追蹤修正進度。

    升級、更新 1.10、1.11、1.12、1.13

    如果您要將非高可用性叢集從 1.9 版升級至 1.10 版，可能會發現使用者叢集的 kubectl exec、kubectl log 和 Webhook 在短時間內無法使用。這段停機時間最多可能為一分鐘。這是因為傳入的要求 (kubectl exec、kubectl log 和 webhook) 是由使用者叢集的 kube-apiserver 處理。使用者 kube-apiserver 是 Statefulset。在非高可用性叢集中，Statefulset 只有一個副本。因此在升級期間，舊版 kube-apiserver 可能無法使用，而新版 kube-apiserver 尚未準備就緒。


    解決方法：

    只有在升級過程中才會發生停機情況。如要在升級期間縮短停機時間，建議您改用高可用性叢集。
    安裝、升級、更新 1.10、1.11、1.12、1.13

    如果您要建立或升級高可用性叢集，並發現叢集診斷中的連線就緒檢查失敗，在大多數情況下，這不會影響 Google Distributed Cloud 的功能 (kubectl exec、kubectl log 和 webhook)。有時，由於網路不穩定或其他問題，一或兩個連線副本可能會有一段時間處於未就緒狀態，因此會發生這種情況。


    解決方法：

    連線會自動恢復。等待 30 分鐘到 1 小時， 然後重新執行叢集診斷。
    作業系統 1.7、1.8、1.9、1.10、1.11

    從 Google Distributed Cloud 1.7.2 版開始，Ubuntu OS 映像檔會採用 CIS L1 伺服器基準強化。

    因此，系統已安裝 cron 指令碼 /etc/cron.daily/aide，以便排定 aide 檢查作業，確保遵循 CIS L1 伺服器規則「1.4.2 確保定期檢查檔案系統完整性」。

    這項 cron 工作每天會在世界標準時間上午 6:25 執行。視檔案系統中的檔案數量而定，您可能會在該時間前後遇到 CPU 和記憶體用量暴增的情況，這是由 aide 程序所致。


    解決方法：

    如果尖峰時段影響工作負載，您可以停用每日執行的 Cron 工作：

    sudo chmod -x /etc/cron.daily/aide
    網路 1.10、1.11、1.12、1.13

    部署 Google Distributed Cloud 1.9 以上版本時，如果部署作業在環境中使用 NSX-T 具狀態分散式防火牆規則，且環境中含有 Seesaw 組合式負載平衡器，stackdriver-operator 可能無法建立 gke-metrics-agent-conf ConfigMap，導致 gke-connect-agent Pod 進入當機迴圈。

    根本問題在於，有狀態的 NSX-T 分散式防火牆規則會透過 Seesaw 負載平衡器，終止從用戶端到使用者叢集 API 伺服器的連線，因為 Seesaw 使用非對稱連線流程。與 NSX-T 分散式防火牆規則的整合問題，會影響所有使用 Seesaw 的 Google Distributed Cloud 版本。當應用程式建立大小超過 32K 的大型 Kubernetes 物件時，您可能會在自己的應用程式中看到類似的連線問題。


    解決方法：

    在 1.13 版說明文件中，請按照 這些操作說明停用 NSX-T 分散式防火牆規則，或為 Seesaw VM 使用無狀態分散式防火牆規則。

    如果叢集使用手動負載平衡器，請按照 這些操作說明設定負載平衡器，以便在偵測到後端節點故障時重設用戶端連線。如果沒有這項設定，伺服器執行個體停止運作時，Kubernetes API 伺服器的用戶端可能會停止回應幾分鐘。
    記錄和監控 1.10、1.11、1.12、1.13、1.14、1.15

    對於 Google Distributed Cloud 1.10 至 1.15 版，部分客戶在「帳單」頁面中發現 Metrics volume 的帳單費用異常高。只有在符合下列所有情況時，這個問題才會影響您：

    • 已啟用應用程式記錄與監控功能 (enableStackdriverForApplications=true)
    • 應用程式 Pod 具有 prometheus.io/scrap=true 註解。(安裝 Cloud Service Mesh 時，也可以新增這項註解)。

    如要確認是否受到這個問題影響，請列出您定義的指標。如果看到以 external.googleapis.com/prometheus 名稱前置字串開頭的不必要指標費用，且 kubectl -n kube-system get stackdriver stackdriver -o yaml 回應中的 enableStackdriverForApplications 設為 true，則表示您遇到這個問題。


    解決方法

    如果受到這個問題影響，建議您將叢集升級至 1.12 以上版本，停止使用 enableStackdriverForApplications 旗標，並改用新的應用程式監控解決方案 managed-service-for-prometheus，這個解決方案不再依賴 prometheus.io/scrap=true 註解。使用這項新解決方案時，您也可以分別使用 enableCloudLoggingForApplications 和 enableGMPForApplications 旗標，控管應用程式的記錄和指標收集作業。

    如要停止使用 enableStackdriverForApplications 旗標，請開啟 `stackdriver` 物件進行編輯：

    kubectl --kubeconfig=USER_CLUSTER_KUBECONFIG --namespace kube-system edit stackdriver stackdriver

    移除 enableStackdriverForApplications: true 行，然後儲存並關閉編輯器。

    如果無法改用非註解式指標收集方式，請按照下列步驟操作：

    1. 找出產生不必要付費指標的來源 Pod 和服務。 
      kubectl --kubeconfig KUBECONFIG \
  get pods -A -o yaml | grep 'prometheus.io/scrape: "true"'
kubectl --kubeconfig KUBECONFIG get \
  services -A -o yaml | grep 'prometheus.io/scrape: "true"'
    2. 從 Pod 或服務中移除 prometheus.io/scrap=true 註解。如果註解是由 Cloud Service Mesh 新增，請考慮設定 Cloud Service Mesh 時不使用 Prometheus 選項，或關閉 Istio 指標合併功能。
    安裝 1.11、1.12、1.13

    如果自訂角色繫結的權限層級有誤，Google Distributed Cloud 安裝程式可能會失敗。

    角色繫結不正確時，使用 govc 建立 vSphere 資料磁碟會發生停滯，且建立的磁碟大小為 0。如要修正這個問題，請在 vSphere vCenter 層級 (根層級) 繫結自訂角色。


    解決方法：

    如要在 DC 層級 (或低於根層級) 繫結自訂角色，您也需要在根 vCenter 層級將唯讀角色繫結至使用者。

    如要進一步瞭解如何建立角色，請參閱 vCenter 使用者帳戶權限。
    記錄和監控 1.9.0-1.9.4、1.10.0-1.10.1

    即使是沒有使用者工作負載的新叢集，您也可能會看到高網路流量。monitoring.googleapis.com

    這個問題會影響 1.10.0-1.10.1 版和 1.9.0-1.9.4 版。這個問題已在 1.10.2 和 1.9.5 版中修正。


    解決方法：
    記錄和監控 1.10、1.11

    如果是 Google Distributed Cloud 1.10 以上版本，當 `enableStackdriverForApplications` 在 `stackdriver` 物件中設為 `true` 時，`gke-metrics-agent` DaemonSet 會頻繁發生 CrashLoopBackOff 錯誤。


    解決方法：

    如要解決這個問題，請執行下列指令，停用應用程式指標收集功能。這些指令不會停用應用程式記錄收集功能。

    1. 如要避免下列變更還原，請縮減stackdriver-operator：
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    --namespace kube-system scale deploy stackdriver-operator \
    --replicas=0
       將 USER_CLUSTER_KUBECONFIG 替換為使用者叢集 kubeconfig 檔案的路徑。
    2. 開啟 gke-metrics-agent-conf ConfigMap 進行編輯： 
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    --namespace kube-system edit configmap gke-metrics-agent-conf
    3. 在 services.pipelines 下方，將整個 metrics/app-metrics 區段註解排除： 
      services:
  pipelines:
    #metrics/app-metrics:
    #  exporters:
    #  - googlecloud/app-metrics
    #  processors:
    #  - resource
    #  - metric_to_resource
    #  - infer_resource
    #  - disk_buffer/app-metrics
    #  receivers:
    #  - prometheus/app-metrics
    metrics/metrics:
      exporters:
      - googlecloud/metrics
      processors:
      - resource
      - metric_to_resource
      - infer_resource
      - disk_buffer/metrics
      receivers:
      - prometheus/metrics
    4. 關閉編輯工作階段。
    5. 重新啟動 gke-metrics-agent DaemonSet： 
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    --namespace kube-system rollout restart daemonset gke-metrics-agent
    記錄和監控 1.11、1.12、1.13

    如果 OOTB 資訊主頁使用已淘汰的指標，您會看到一些空白圖表。如要在 Monitoring 資訊主頁中找出已淘汰的指標，請執行下列指令：

    gcloud monitoring dashboards list > all-dashboard.json

# find deprecated metrics
cat all-dashboard.json | grep -E \
  'kube_daemonset_updated_number_scheduled\
    |kube_node_status_allocatable_cpu_cores\
    |kube_node_status_allocatable_pods\
    |kube_node_status_capacity_cpu_cores'

    請將下列已淘汰的指標遷移至替代指標。

    已淘汰替換
    kube_daemonset_updated_number_scheduled kube_daemonset_status_updated_number_scheduled
    kube_node_status_allocatable_cpu_cores
    kube_node_status_allocatable_memory_bytes
    kube_node_status_allocatable_pods    		 kube_node_status_allocatable
    kube_node_status_capacity_cpu_cores
    kube_node_status_capacity_memory_bytes
    kube_node_status_capacity_pods    		 kube_node_status_capacity
    kube_hpa_status_current_replicas kube_horizontalpodautoscaler_status_current_replicas

    解決方法：

    如要取代已淘汰的指標

    1. 在 Google Cloud Monitoring 資訊主頁中刪除「GKE on-prem node status」(GKE On-Prem 節點狀態)。請按照 這些指示重新安裝「GKE On-Prem 節點狀態」。
    2. 在 Google Cloud Monitoring 資訊主頁中，刪除「GKE On-Prem 節點使用率」。請按照這些指示重新安裝「GKE On-Prem 節點使用率」。
    3. 在 Google Cloud Monitoring 資訊主頁中，刪除「GKE on-prem vSphere vm health」。請按照 這些操作說明，重新安裝「GKE on-prem vSphere VM health」。

      4. 由於 kube-state-metrics 代理程式從 v1.9 升級至 v2.4，因此需要淘汰這些指標。這是 Kubernetes 1.22 的必要條件。您可以替換自訂資訊主頁或快訊政策中所有已淘汰的 kube-state-metrics 指標 (前置字元為 kube_)。
    記錄和監控 1.10、1.11、1.12、1.13

    如果是 Google Distributed Cloud 1.10 以上版本，Cloud Monitoring 中的叢集資料可能包含不相關的摘要指標項目，例如：

    Unknown metric: kubernetes.io/anthos/go_gc_duration_seconds_summary_percentile

    其他可能含有不相關摘要指標的指標類型包括

    ：
    • apiserver_admission_step_admission_duration_seconds_summary
    • go_gc_duration_seconds
    • scheduler_scheduling_duration_seconds
    • gkeconnect_http_request_duration_seconds_summary
    • alertmanager_nflog_snapshot_duration_seconds_summary

    雖然這些摘要類型指標會顯示在指標清單中，但 gke-metrics-agent 目前不支援這些指標。
    記錄和監控 1.10、1.11、1.12、1.13

    您可能會發現部分節點缺少下列指標，但並非所有節點都缺少：

    • kubernetes.io/anthos/container_memory_working_set_bytes
    • kubernetes.io/anthos/container_cpu_usage_seconds_total
    • kubernetes.io/anthos/container_network_receive_bytes_total

    解決方法：

    如要修正這個問題，請按照下列步驟操作。如為 [1.9.5 以上版本、1.10.2 以上版本、1.11.0]：請按照步驟 1 至 4，增加 gke-metrics-agent 的 CPU

    1. 開啟 stackdriver 資源進行編輯： 
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    --namespace kube-system edit stackdriver stackdriver
    2. 如要將 gke-metrics-agent 的 CPU 要求從 10m 提高至 50m，並將 CPU 限制從 100m 提高至 200m，請在 stackdriver 資訊清單中新增下列 resourceAttrOverride 區段：
      spec:
  resourceAttrOverride:
    gke-metrics-agent/gke-metrics-agent:
      limits:
        cpu: 100m
        memory: 4608Mi
      requests:
        cpu: 10m
        memory: 200Mi
       編輯後的資源應如下所示： 
      spec:
  anthosDistribution: on-prem
  clusterLocation: us-west1-a
  clusterName: my-cluster
  enableStackdriverForApplications: true
  gcpServiceAccountSecretName: ...
  optimizedMetrics: true
  portable: true
  projectID: my-project-191923
  proxyConfigSecretName: ...
  resourceAttrOverride:
    gke-metrics-agent/gke-metrics-agent:
      limits:
        cpu: 200m
        memory: 4608Mi
      requests:
        cpu: 50m
        memory: 200Mi
    3. 儲存變更並關閉文字編輯器。
    4. 如要確認變更是否生效，請執行下列指令：
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    --namespace kube-system get daemonset gke-metrics-agent -o yaml \
    | grep "cpu: 50m"
       這項指令會尋找 cpu: 50m，確認編輯內容是否已生效。
    記錄和監控 1.11.0-1.11.2、1.12.0

    如果管理員叢集受到這個問題影響，排程器和控制器管理員指標就會遺失。舉例來說，這兩個指標缺少

    # scheduler metric example
scheduler_pending_pods
# controller-manager metric example
replicaset_controller_rate_limiter_use

    解決方法：

    升級至 v1.11.3 以上、v1.12.1 以上或 v1.13 以上版本。
    1.11.0-1.11.2、1.12.0

    如果使用者叢集受到這個問題影響，排程器和控制項管理員指標就會遺失。舉例來說，這兩個指標會遺失：

    # scheduler metric example
scheduler_pending_pods
# controller-manager metric example
replicaset_controller_rate_limiter_use

    解決方法：

    這個問題已在 Google Distributed Cloud 1.13.0 以上版本中修正。 將叢集升級至包含修正程式的版本。
    安裝、升級、更新 1.10、1.11、1.12、1.13

    如果您建立 1.9.x 或 1.10.0 版的管理員叢集，且管理員叢集在建立期間無法使用提供的 gkeConnect 規格註冊，就會收到下列錯誤訊息。

    Failed to create root cluster: failed to register admin cluster: failed to register cluster: failed to apply Hub Membership: Membership API request failed: rpc error:  ode = PermissionDenied desc = Permission 'gkehub.memberships.get' denied on PROJECT_PATH

    您仍可使用這個管理員叢集，但如果之後嘗試將管理員叢集升級至 1.10.y 版，就會收到下列錯誤訊息。

    failed to migrate to first admin trust chain: failed to parse current version "": invalid version: "" failed to migrate to first admin trust chain: failed to parse current version "": invalid version: ""

    解決方法：
    身分識別 1.10、1.11、1.12、1.13

    如果您使用 GKE Identity Service 功能管理 GKE Identity Service ClientConfig， Connect Agent 可能會意外重新啟動。


    解決方法：

    如果現有叢集發生這個問題，您可以採取下列任一做法：

    • 停用 GKE Identity Service。停用 GKE Identity Service 後，已部署的 GKE Identity Service 二進位檔或 GKE Identity Service ClientConfig 不會移除。如要停用 GKE Identity Service，請執行下列指令：
      gcloud container fleet identity-service disable \
    --project PROJECT_ID
       將 PROJECT_ID 替換為叢集 機群主機專案的 ID。
    • 將叢集更新至 1.9.3 以上版本，或 1.10.1 以上版本，即可升級 Connect 代理程式版本。
    網路 1.10、1.11、1.12、1.13

    Seesaw 會在 DSR 模式下執行，但由於資料平面 IP 學習，預設無法在 Cisco ACI 中運作。


    解決方法：

    可能的解決方法是在 Cisco 應用程式政策基礎架構控制器 (APIC) 中，將 Seesaw IP 位址新增為 L4-L7 虛擬 IP，藉此停用 IP 學習功能。

    如要設定 L4-L7 虛擬 IP 選項，請依序前往「Tenant」>「Application Profiles」>「Application EPGs」或「uSeg EPGs」。如果無法停用 IP 學習功能，IP 端點就會在 Cisco API 網狀架構中的不同位置之間擺盪。
    VMware 1.10、1.11、1.12、1.13

    VMWare 最近發現下列 vSphere 7.0 Update 3 版本有重大問題：

    • vSphere ESXi 7.0 Update 3 (組建 18644231)
    • vSphere ESXi 7.0 Update 3a (組建 18825058)
    • vSphere ESXi 7.0 Update 3b (建構版本 18905247)
    • vSphere vCenter 7.0 Update 3b (組建 18901211)

    解決方法：

    VMWare 隨後移除了這些版本。您應將 ESXi 和 vCenter Server 升級至較新版本。
    作業系統 1.10、1.11、1.12、1.13

    如為在節點上執行的 Pod，且節點使用 Container-Optimized OS (COS) 映像檔，則無法將 emptyDir 磁碟區掛接為 exec。它會掛接為 noexec，且您會收到下列錯誤：exec user process caused: permission denied。舉例來說，如果您部署下列測試 Pod，就會看到這則錯誤訊息：

    apiVersion: v1
kind: Pod
metadata:
  creationTimestamp: null
  labels:
    run: test
  name: test
spec:
  containers:
  - args:
    - sleep
    - "5000"
    image: gcr.io/google-containers/busybox:latest
    name: test
    volumeMounts:
      - name: test-volume
        mountPath: /test-volume
    resources:
      limits:
        cpu: 200m
        memory: 512Mi
  dnsPolicy: ClusterFirst
  restartPolicy: Always
  volumes:
    - emptyDir: {}
      name: test-volume

    在測試 Pod 中執行 mount | grep test-volume，會顯示 noexec 選項：

    /dev/sda1 on /test-volume type ext4 (rw,nosuid,nodev,noexec,relatime,commit=30)

    解決方法：
    升級、更新 1.10、1.11、1.12、1.13

    在節點集區上啟用及停用自動調度功能後，節點集區副本不會更新。


    解決方法：

    從對應節點集區的機器部署作業中，移除 cluster.x-k8s.io/cluster-api-autoscaler-node-group-max-size 和 cluster.x-k8s.io/cluster-api-autoscaler-node-group-min-size 註解。
    記錄和監控 1.11、1.12、1.13

    從 1.11 版開始，在立即可用的監控資訊主頁上，Windows Pod 狀態資訊主頁和 Windows 節點狀態資訊主頁也會顯示 Linux 叢集的資料。這是因為 Windows 節點和 Pod 指標也會在 Linux 叢集上公開。
    記錄和監控 1.10、1.11、1.12

    如果是 Google Distributed Cloud 1.10、1.11 和 1.12 版，當磁碟上有損毀的緩衝記錄時，stackdriver-log-forwarder DaemonSet 可能會發生 CrashLoopBackOff 錯誤。


    解決方法：

    如要緩解這個問題，我們需要在節點上清除緩衝記錄。

    1. 為避免發生非預期的行為，請縮減規模： stackdriver-log-forwarder: 
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    -n kube-system patch daemonset stackdriver-log-forwarder -p '{"spec": {"template": {"spec": {"nodeSelector": {"non-existing": "true"}}}}}'
       將 USER_CLUSTER_KUBECONFIG 替換為使用者叢集 kubeconfig 檔案的路徑。
    2. 部署清除 DaemonSet，清除損毀的區塊： 
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    -n kube-system -f - << EOF
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: fluent-bit-cleanup
  namespace: kube-system
spec:
  selector:
    matchLabels:
      app: fluent-bit-cleanup
  template:
    metadata:
      labels:
        app: fluent-bit-cleanup
    spec:
      containers:
      - name: fluent-bit-cleanup
        image: debian:10-slim
        command: ["bash", "-c"]
        args:
        - |
          rm -rf /var/log/fluent-bit-buffers/
          echo "Fluent Bit local buffer is cleaned up."
          sleep 3600
        volumeMounts:
        - name: varlog
          mountPath: /var/log
        securityContext:
          privileged: true
      tolerations:
      - key: "CriticalAddonsOnly"
        operator: "Exists"
      - key: node-role.kubernetes.io/master
        effect: NoSchedule
      - key: node-role.gke.io/observability
        effect: NoSchedule
      volumes:
      - name: varlog
        hostPath:
          path: /var/log
EOF
    3. 如要確認清除 DaemonSet 已清除所有區塊，可以執行下列指令。這兩項指令的輸出內容應等於叢集中的節點數：
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
  logs -n kube-system -l app=fluent-bit-cleanup | grep "cleaned up" | wc -l

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
  -n kube-system get pods -l app=fluent-bit-cleanup --no-headers | wc -l
    4. 刪除清除 DaemonSet： 
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
  -n kube-system delete ds fluent-bit-cleanup
    5. 繼續播放 stackdriver-log-forwarder： 
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
  -n kube-system patch daemonset stackdriver-log-forwarder --type json -p='[{"op": "remove", "path": "/spec/template/spec/nodeSelector/non-existing"}]'
    記錄和監控 1.10、1.11、1.12、1.13、1.14、1.15、1.16

    如果 Cloud Logging 中未顯示叢集的記錄，且記錄中出現下列錯誤： 

    2023-06-02T10:53:40.444017427Z [2023/06/02 10:53:40] [error] [input chunk] chunk 1-1685703077.747168499.flb would exceed total limit size in plugin stackdriver.0
2023-06-02T10:53:40.444028047Z [2023/06/02 10:53:40] [error] [input chunk] no available chunk
    記錄檔輸入速率可能超過記錄代理程式的上限，導致 stackdriver-log-forwarder 無法傳送記錄檔。 所有 Google Distributed Cloud 版本都會發生這個問題。

    解決方法：

    如要解決這個問題，請提高記錄代理程式的資源限制。

    1. 開啟 stackdriver 資源進行編輯： 
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    --namespace kube-system edit stackdriver stackdriver
    2. 如要增加 stackdriver-log-forwarder 的 CPU 要求，請在 stackdriver 資訊清單中新增下列 resourceAttrOverride 區段：
      spec:
  resourceAttrOverride:
    stackdriver-log-forwarder/stackdriver-log-forwarder:
      limits:
        cpu: 1200m
        memory: 600Mi
      requests:
        cpu: 600m
        memory: 600Mi
       編輯後的資源應如下所示： 
      spec:
  anthosDistribution: on-prem
  clusterLocation: us-west1-a
  clusterName: my-cluster
  enableStackdriverForApplications: true
  gcpServiceAccountSecretName: ...
  optimizedMetrics: true
  portable: true
  projectID: my-project-191923
  proxyConfigSecretName: ...
  resourceAttrOverride:
    stackdriver-log-forwarder/stackdriver-log-forwarder:
      limits:
        cpu: 1200m
        memory: 600Mi
      requests:
        cpu: 600m
        memory: 600Mi
    3. 儲存變更並關閉文字編輯器。
    4. 如要確認變更是否生效，請執行下列指令：
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    --namespace kube-system get daemonset stackdriver-log-forwarder -o yaml \
    | grep "cpu: 1200m"
       這項指令會尋找 cpu: 1200m，確認編輯內容是否已生效。
    安全性 1.13

    節點已就緒，但 kubelet 伺服器憑證尚未就緒，這段期間很短。kubectl exec和kubectl logs在這幾十秒內無法使用。這是因為新的伺服器憑證核准者需要時間，才能看到節點更新後的有效 IP。

    這項問題只會影響 kubelet 伺服器憑證，不會影響 Pod 排程。
    升級、更新 1.12

    使用者叢集升級失敗，原因如下：

    .LBKind in body is required (Check the status of OnPremUserCluster 'cl-stg-gdl-gke-onprem-mgmt/cl-stg-gdl' and the logs of pod 'kube-system/onprem-user-cluster-controller' for more detailed debugging information.

    管理員叢集尚未完全升級，狀態版本仍為 1.10。預檢不會阻礙使用者叢集升級至 1.12，但會因版本差異問題而失敗。


    解決方法：

    請先將管理員叢集升級至 1.11，再將使用者叢集升級至 1.12。
    儲存空間 1.10.0-1.10.5、1.11.0-1.11.2、1.12.0

    gkectl diagnose cluster 指令失敗，原因如下： 

    Checking VSphere Datastore FreeSpace...FAILURE
    Reason: vCenter datastore: [DATASTORE_NAME] insufficient FreeSpace, requires at least [NUMBER] GB

    資料儲存庫可用空間的驗證不應用於現有叢集節點集區，且已在 gkectl diagnose cluster 中誤增。


    解決方法：

    您可以忽略錯誤訊息，或使用 --skip-validation-infra 略過驗證。
    作業、網路 1.11、1.12.0-1.12.1

    如果管理員叢集是使用 MetalLB 負載平衡器設定建立，您可能無法新增使用者叢集。

    使用者叢集刪除程序可能因不明原因停滯，導致 MatalLB ConfigMap 失效。在此狀態下，您無法新增使用者叢集。


    解決方法：

    您可以 強制刪除使用者叢集。
    安裝、作業系統 1.10、1.11、1.12、1.13

    如果 osImageType 使用 cos 管理員叢集，且在建立管理員叢集後和建立使用者叢集前執行 gkectl check-config，則會發生下列錯誤：

    Failed to create the test VMs: VM failed to get IP addresses on the network.

    根據預設，為使用者叢集 check-config 建立的測試 VM 會使用管理員叢集的相同 osImageType，但測試 VM 目前與 COS 不相容。


    解決方法：

    為避免建立測試 VM 時進行緩慢的預檢，請使用 gkectl check-config --kubeconfig ADMIN_CLUSTER_KUBECONFIG --config USER_CLUSTER_CONFIG --fast。
    記錄和監控 1.12.0-1.12.1

    這個問題會影響在管理員叢集中使用 Grafana 的客戶，他們會監控 Google Distributed Cloud 1.12.0 和 1.12.1 版中的使用者叢集。這是因為使用者叢集中的 pushprox 用戶端憑證，與管理叢集中的 pushprox 伺服器允許清單不符。症狀是使用者叢集中的 pushprox-client 會列印類似下列內容的錯誤記錄：

    level=error ts=2022-08-02T13:34:49.41999813Z caller=client.go:166 msg="Error reading request:" err="invalid method \"RBAC:\""

    解決方法：
    其他 1.11.3

    gkectl repair admin-master 指令失敗，原因如下： 

    Failed to repair: failed to select the template: no VM templates is available for repairing the admin master (check if the admin cluster version >= 1.4.0 or contact support

    如果管理員控制層 VM 的名稱結尾為 t、m、p 或 l 字元，gkectl repair admin-master 就無法擷取用於修復管理員控制層 VM 的 VM 範本。


    解決方法：

    使用 --skip-validation 重新執行指令。
    記錄和監控 1.11、1.12、1.13、1.14、1.15、1.16

    Cloud Audit Logs 需要特殊權限設定，目前只有透過 GKE Hub，才能自動為使用者叢集執行這項設定。建議您至少有一個使用者叢集與管理員叢集使用相同的專案 ID 和服務帳戶，以利 Cloud Audit Logs 運作，這樣管理員叢集就會具備必要權限。

    不過，如果管理員叢集使用的專案 ID 或服務帳戶與任何使用者叢集不同，管理員叢集的稽核記錄就無法注入 Google Cloud。症狀是管理叢集中的 audit-proxy Pod 出現一連串 Permission Denied 錯誤。

    解決方法：
    作業、安全性 1.11

    如果工作站無法存取使用者叢集工作站節點，執行 gkectl diagnose 時會發生下列錯誤：

    Checking user cluster certificates...FAILURE
    Reason: 3 user cluster certificates error(s).
    Unhealthy Resources:
    Node kubelet CA and certificate on node xxx: failed to verify kubelet certificate on node xxx: dial tcp xxx.xxx.xxx.xxx:10250: connect: connection timed out
    Node kubelet CA and certificate on node xxx: failed to verify kubelet certificate on node xxx: dial tcp xxx.xxx.xxx.xxx:10250: connect: connection timed out
    Node kubelet CA and certificate on node xxx: failed to verify kubelet certificate on node xxx: dial tcp xxx.xxx.xxx.xxx:10250: connect: connection timed out

    如果工作站無法存取管理員叢集工作站節點或管理員叢集工作站節點，執行 gkectl diagnose 時會發生下列錯誤：

    Checking admin cluster certificates...FAILURE
    Reason: 3 admin cluster certificates error(s).
    Unhealthy Resources:
    Node kubelet CA and certificate on node xxx: failed to verify kubelet certificate on node xxx: dial tcp xxx.xxx.xxx.xxx:10250: connect: connection timed out
    Node kubelet CA and certificate on node xxx: failed to verify kubelet certificate on node xxx: dial tcp xxx.xxx.xxx.xxx:10250: connect: connection timed out
    Node kubelet CA and certificate on node xxx: failed to verify kubelet certificate on node xxx: dial tcp xxx.xxx.xxx.xxx:10250: connect: connection timed out

    解決方法：

    您可以放心忽略這些訊息。
    作業系統 1.8、1.9、1.10、1.11、1.12、1.13

    /var/log/audit/ 會填入稽核記錄。您可以執行 sudo du -h -d 1 /var/log/audit 來檢查磁碟用量。

    管理員工作站上的特定 gkectl 指令 (例如 gkectl diagnose snapshot) 會占用磁碟空間。

    自 Google Distributed Cloud 1.8 版起，Ubuntu 映像檔會根據 CIS Level 2 Benchmark 強化。其中一項法規遵循規則「4.1.2.2 Ensure audit logs are not automatically deleted」(確保稽核記錄不會自動刪除)，可確保 auditd 設定 max_log_file_action = keep_logs。這樣一來，磁碟上就會保留所有稽核規則。


    解決方法：
    網路 1.10、1.11.0-1.11.3、1.12.0-1.12.2、1.13.0

    由於下列驗證 Webhook 錯誤，使用者無法建立或更新 NetworkGatewayGroup 物件：

    [1] admission webhook "vnetworkgatewaygroup.kb.io" denied the request: NetworkGatewayGroup.networking.gke.io "default" is invalid: [Spec.FloatingIPs: Invalid value: "10.0.0.100": IP address conflicts with node address with name: "my-node-name"

    在受影響的版本中，kubelet 可能會錯誤地繫結至指派給節點的浮動 IP 位址，並在 node.status.addresses 中將其回報為節點位址。驗證 webhook 會根據叢集中的所有浮動 IP 位址檢查浮動 IP 位址，並將此視為衝突。NetworkGatewayGroupnode.status.addresses


    解決方法：

    在建立或更新 NetworkGatewayGroup 物件失敗的叢集中，暫時停用 ANG 驗證 Webhook，然後提交變更：

    1. 儲存 Webhook 設定，以便在最後還原： 
      kubectl -n kube-system get validatingwebhookconfiguration \
    ang-validating-webhook-configuration -o yaml > webhook-config.yaml
    2. 編輯 Webhook 設定： 
      kubectl -n kube-system edit validatingwebhookconfiguration \
    ang-validating-webhook-configuration
    3. 從 webhook 設定清單中移除 vnetworkgatewaygroup.kb.io 項目，然後關閉以套用變更。
    4. 建立或編輯 NetworkGatewayGroup 物件。
    5. 重新套用原始 Webhook 設定： 
      kubectl -n kube-system apply -f webhook-config.yaml
    安裝、升級、更新 1.10.0-1.10.2

    嘗試升級管理員叢集時，管理員控制層 VM 可能會在建立期間停滯。管理控制平面 VM 會在啟動期間進入無限等待迴圈，您會在 /var/log/cloud-init-output.log 檔案中看到下列無限迴圈錯誤：

    + echo 'waiting network configuration is applied'
waiting network configuration is applied
++ get-public-ip
+++ ip addr show dev ens192 scope global
+++ head -n 1
+++ grep -v 192.168.231.1
+++ grep -Eo 'inet ([0-9]{1,3}\.){3}[0-9]{1,3}'
+++ awk '{print $2}'
++ echo
+ '[' -n '' ']'
+ sleep 1
+ echo 'waiting network configuration is applied'
waiting network configuration is applied
++ get-public-ip
+++ ip addr show dev ens192 scope global
+++ grep -Eo 'inet ([0-9]{1,3}\.){3}[0-9]{1,3}'
+++ awk '{print $2}'
+++ grep -v 192.168.231.1
+++ head -n 1
++ echo
+ '[' -n '' ']'
+ sleep 1

    這是因為 Google Distributed Cloud 嘗試在啟動指令碼中取得節點 IP 位址時，會使用 grep -v ADMIN_CONTROL_PLANE_VIP 跳過管理員叢集控制層 VIP，而該 VIP 也可指派給 NIC。不過，這項指令也會略過任何前置字元為控制層 VIP 的 IP 位址，導致啟動指令碼停止運作。

    舉例來說，假設管理員叢集控制層 VIP 為 192.168.1.25。如果管理員叢集控制層 VM 的 IP 位址具有相同前置字元 (例如 192.168.1.254)，控制層 VM 在建立期間就會停滯。如果廣播位址與控制層 VIP 的前置字串相同 (例如 192.168.1.255)，也可能觸發這個問題。


    解決方法：

    • 如果管理員叢集建立作業逾時的原因是廣播 IP 位址，請在管理員叢集控制層 VM 上執行下列指令：
      ip addr add ${ADMIN_CONTROL_PLANE_NODE_IP}/32 dev ens192
       這會建立沒有廣播地址的行，並解除封鎖啟動程序。啟動指令碼解除封鎖後，請執行下列指令，移除新增的這一行：
      ip addr del ${ADMIN_CONTROL_PLANE_NODE_IP}/32 dev ens192
    • 不過，如果管理員叢集建立作業逾時的原因是控制層 VM 的 IP 位址，您就無法解除封鎖啟動指令碼。切換至其他 IP 位址，然後重新建立或升級至 1.10.3 以上版本。
    作業系統、升級、更新 1.10.0-1.10.2

    使用 COS 映像檔時，DataDisk 無法正確掛接至管理員叢集主節點，且管理員叢集升級或管理員主節點修復後，使用 COS 映像檔的管理員叢集狀態會遺失。(使用 COS 映像檔的管理員叢集為預先發布版功能)


    解決方法：

    將 osImageType 設為 ubuntu_containerd，重新建立管理員叢集

    使用 osImageType 設為 cos 建立管理員叢集後，請擷取管理員叢集 SSH 金鑰，並透過 SSH 連結至管理員主要節點。df -h 個結果包含 /dev/sdb1 98G 209M 93G 1% /opt/data。lsblk 結果包含 -sdb1 8:17 0 100G 0 part /opt/data
    作業系統 1.10

    在 Google Distributed Cloud 1.10.0 版中，Ubuntu 上的名稱解析預設會路由至本機 systemd-resolved 監聽 127.0.0.53。這是因為在 1.10.0 版使用的 Ubuntu 20.04 映像檔中，/etc/resolv.conf 會符號連結至 /run/systemd/resolve/stub-resolv.conf，而後者會指向 127.0.0.53 本機主機 DNS 存根。

    因此，本機主機 DNS 名稱解析作業會拒絕檢查上游 DNS 伺服器 (在 /run/systemd/resolve/resolv.conf 中指定) 的名稱，除非名稱指定為搜尋網域。.local

    這會導致對 .local 名稱的任何查詢失敗。舉例來說，在節點啟動期間，kubelet無法從具有 .local 後置字串的私人登錄檔提取映像檔。在管理員工作站上，指定帶有 .local 後置字元的 vCenter 位址將無法運作。


    解決方法：

    如要在管理員叢集設定檔和使用者叢集設定檔中指定 searchDomainsForDNS 欄位，納入網域，即可避免叢集節點發生這個問題。

    目前 gkectl update 尚不支援更新 searchDomainsForDNS 欄位。

    因此，如果您在建立叢集前未設定這個欄位，就必須透過 SSH 連線至節點，並將 /etc/resolv.conf 的符號連結從 /run/systemd/resolve/stub-resolv.conf (包含 127.0.0.53 本機 Stub) 變更為 /run/systemd/resolve/resolv.conf (指向實際的上游 DNS)，藉此略過本機 systemd-resolved Stub：

    sudo ln -sf /run/systemd/resolve/resolv.conf /etc/resolv.conf

    至於管理員工作站，gkeadm 不支援指定搜尋網域，因此必須透過這個手動步驟解決問題。

    這項解決方案不會在 VM 重新建立後繼續運作。重新建立 VM 時，您必須重新套用這項解決方法。
    安裝、作業系統 1.10

    Google Distributed Cloud 會為 Docker 橋接器 IP 位址指定專用子網路 (使用 --bip=169.254.123.1/24)，因此不會保留預設的 172.17.0.1/16 子網路。不過，在 1.10.0 版中，Ubuntu OS 映像檔存在錯誤，導致系統忽略自訂 Docker 設定。

    因此，Docker 會選擇預設的 172.17.0.1/16 做為橋接器 IP 位址子網路。如果該 IP 位址範圍內已有工作負載在執行，可能會導致 IP 位址衝突。


    解決方法：

    如要解決這個問題，請重新命名 dockerd 的下列 systemd 設定檔，然後重新啟動服務：

    sudo mv /etc/systemd/system/docker.service.d/50-cloudimg-settings.cfg \
    /etc/systemd/system/docker.service.d/50-cloudimg-settings.conf

sudo systemctl daemon-reload

sudo systemctl restart docker

    確認 Docker 選擇的橋接 IP 位址是否正確：

    ip a | grep docker0

    重新建立 VM 後，這項解決方案就會失效。每當重新建立 VM 時，您都必須重新套用這項解決方法。
    升級、更新 1.11

    在 Google Distributed Cloud 1.11.0 版中，與記錄和監控相關的自訂資源定義有所變更：

    • stackdriver 自訂資源的群組名稱已從「addons.sigs.k8s.io」變更為「addons.gke.io」；
    • monitoring 和 metricsserver 自訂資源的群組名稱已從「addons.k8s.io」變更為「addons.gke.io」；
    • 系統會開始根據上述資源的結構定義驗證規格。具體來說，stackdriver 自訂資源中的 resourceAttrOverride 和 storageSizeOverride 規格，必須在 CPU、記憶體和儲存空間大小要求與限制的值中具有字串型別。

    群組名稱變更是為了配合 Kubernetes 1.22 中的 CustomResourceDefinition 更新。

    如果您沒有其他適用或編輯受影響自訂資源的邏輯，則無須採取任何行動。Google Distributed Cloud 升級程序會負責遷移受影響的資源，並在群組名稱變更後保留現有規格。

    不過，如果您執行任何套用或編輯受影響資源的邏輯，則需要特別留意。首先，您需要在資訊清單檔案中，使用新的群組名稱參照這些權限。例如：

    apiVersion: addons.gke.io/v1alpha1  ## instead of `addons.sigs.k8s.io/v1alpha1`
kind: Stackdriver

    其次，請確認 resourceAttrOverride 和 storageSizeOverride 規格值為字串類型。例如：

    spec:
  resourceAttrOverride:
    stackdriver-log-forwarder/stackdriver-log-forwarder
      limits:
        cpu: 1000m # or "1"
        # cpu: 1 # integer value like this would not work
        memory: 3000Mi

    否則，套用和編輯作業不會生效，且可能導致記錄和監控元件出現非預期的狀態。可能的症狀包括：

    • onprem-user-cluster-controller中的對帳錯誤記錄，例如：
      potential reconciliation error: Apply bundle components failed, requeue after 10s, error: failed to apply addon components: failed to apply bundle objects from stackdriver-operator-addon 1.11.2-gke.53 to cluster my-cluster: failed to create typed live object: .spec.resourceAttrOverride.stackdriver-log-forwarder/stackdriver-log-forwarder.limits.cpu: expected string, got &value.valueUnstructured{Value:1}
    • kubectl edit stackdriver stackdriver 失敗，例如：
      Error from server (NotFound): stackdrivers.addons.gke.io "stackdriver" not found

    如果遇到上述錯誤，表示升級前已存在 stackdriver CR 規格中不支援的類型。如要解決這個問題，您可以手動編輯舊群組名稱 kubectl edit stackdrivers.addons.sigs.k8s.io stackdriver 下的 stackdriver CR，並執行下列操作：

    1. 將資源要求和限制變更為字串類型；
    2. 移除所有 addons.gke.io/migrated-and-deprecated: true 註解 (如有)。
    接著繼續或重新啟動升級程序。

    作業系統 1.7 以上版本

    如果 ESXi 伺服器發生故障，且已為該伺服器啟用 vCenter HA 功能，故障 ESXi 伺服器中的所有 VM 都會觸發 vMotion 機制，並移至其他正常的 ESXi 伺服器。遷移後的 COS VM 會失去 IP。

    解決方法：

    重新啟動 VM
    網路 1.14.7 之前的版本、1.15.0 至 1.15.3、1.16.0

    Seesaw 每 20 秒傳送的週期性 GARP (無償 ARP) 不會在 ARP 標頭中設定目標 IP。部分網路可能不接受這類封包 (例如 Cisco ACI)。這可能會導致服務在腦裂 (因 VRRP 封包捨棄而發生) 復原後，停機時間延長。

    解決方法：

    在任一 Seesaw VM 上執行 sudo seesaw -c failover，觸發 Seeaw 容錯移轉。這樣應該就能恢復流量。
    作業系統 1.16、1.28.0-1.28.200

    工作站節點的「staticPodPath」設定有誤

    解決方法：

    手動建立「/etc/kubernetes/manifests」資料夾

    後續步驟

    如需其他協助，請與 Cloud Customer Care 團隊聯絡。

    如要進一步瞭解支援資源，包括下列項目，請參閱「取得支援」：