排解叢集連線問題

本頁面說明如何排解將叢集註冊至車隊，或使用 Google Cloud 以外的方式連線至叢集時，可能會遇到的常見錯誤。這些方式包括使用 Google Cloud 控制台、Google Cloud CLI 或kubectl透過 Connect 閘道。

地端叢集和其他公有雲上的叢集會依賴 Connect 代理程式，在叢集和 Google Cloud 專案之間建立及維護連線，並處理 Kubernetes 要求。如果看到「無法連線至代理程式」或「無法連線至叢集的控制平面」等錯誤，可能表示 Connect 代理程式有問題。

收集 Connect Agent 記錄

註冊外部叢集時，系統會使用 Connect 代理程式處理叢集與機群主專案之間的通訊。 Google CloudConnect Agent 是 gke-connect-agent 部署作業，通常安裝在叢集裡的 gke-connect 命名空間中。收集此 Connect Agent 的記錄有助於排解註冊和連線問題。

如要擷取代理程式的記錄，可以執行下列指令 (視需要調整行數)：

kubectl logs -n gke-connect -l app=gke-connect-agent --tail=-1

取得專案叢集中所有執行 Connect 代理程式的相關資訊：

kubectl describe deployment --all-namespaces -l app=gke-connect-agent

連線成功的項目應如下列範例所示：

2019/02/16 17:28:43.312056 dialer.go:244: dialer: dial: connected to gkeconnect.googleapis.com:443
2019/02/16 17:28:43.312279 tunnel.go:234: serve: opening egress stream...
2019/02/16 17:28:43.312439 tunnel.go:248: serve: registering endpoint="442223602236", shard="88d2bca5-f40a-11e8-983e-42010a8000b2" {"Params":{"GkeConnect":{"endpoint_class":1,"metadata":{"Metadata":{"Default":{"manifest_version":"234227867"}}}}}} ...
2019/02/16 17:28:43.312656 tunnel.go:259: serve: serving requests...

收集 GKE Identity Service 記錄檔

如果使用「連結」閘道時發生 Google 群組或第三方支援問題，檢查 GKE Identity Service 記錄或許有幫助。這種產生記錄的方法僅適用於 VMware 或裸機上的 Google Distributed Cloud 部署作業中的叢集。

  1. 如要提高 GKE Identity Service 記錄的詳細程度，請使用下列指令編輯 clientconfig 自訂資源：

    kubectl edit deployment -n anthos-identity-service

    ，並在 containers 欄位下方新增 vmodule 標記，如下所示：

    spec:
  containers:
  ...
  - command:
    - --vmodule=cloud/identity/hybrid/charon/*=9

  2. 使用下列指令刪除 GKE Identity Service Pod，藉此重新啟動該 Pod：

    kubectl delete pods -l k8s-app=ais -n anthos-identity-service

    幾秒後，充電盒應該會再次顯示。

  3. Pod 重新啟動後，請執行原本傳回非預期回應的指令，在 GKE Identity Service Pod 記錄中填入更多詳細資料。

  4. 使用下列指令，將這些記錄的輸出內容儲存至檔案：

    kubectl logs -l k8s-app=ais -n anthos-identity-service --tail=-1 > gke_id_service_logs.txt

如果 GKE Identity Service Pod 記錄檔中缺少預期群組，請確認叢集設定是否正確。如果還有其他 GKE Identity Service 相關問題，請參閱「排解使用者存取權問題」或「排解艦隊層級設定問題」。

tls: oversized record 個錯誤

問題

您可能發生了如下所示的錯誤：

... dialer: dial: connection to gkeconnect.googleapis.com:443 failed after
388.080605ms: serve: egress call failed: rpc error: code = Unauthenticated
desc = transport: oauth2: cannot fetch token: Post
https://oauth2.googleapis.com/token: proxyconnect tcp: tls: oversized record
received with length 20527
可能原因

這可能表示 Connect 代理程式嘗試透過 HTTPS 連線至只限 HTTP 的 Proxy。Connect Agent 只支援使用 CONNECT 的 HTTP Proxy。

解決方法

您需按照下列方式重新設定 Proxy 環境變數：

http_proxy=http://[PROXY_URL]:[PROXY_PORT]
https_proxy=http://[PROXY_URL]:[PROXY_PORT]

oauth2: cannot fetch token 個錯誤

問題

您可能發生了如下所示的錯誤：

...  dialer: dial: connection to gkeconnect.googleapis.com:443 failed
after 388.080605ms: serve: egress call failed: rpc error: code =
Unauthenticated desc = transport: oauth2: cannot fetch token: Post
https://oauth2.googleapis.com/token: read tcp 192.168.1.40:5570->1.1.1.1:80
read: connection reset by peer
可能原因

這可能表示上游 HTTP Proxy 重設連線，很可能是因為您的 HTTP Proxy 禁用這個網址。上述範例中的 1.1.1.1:80 就是 HTTP Proxy 位址。

解決方法

檢查您的 HTTP Proxy 許可清單是否包含下列網址/網域：

gkeconnect.googleapis.com
oauth2.googleapis.com/token
www.googleapis.com/oauth2/v1/certs

Connect Agent Pod 發生當機和重新啟動錯誤

問題

您可能會在叢集的 Google Cloud 控制台 中，遇到間歇性的「Unreachable Agent」錯誤，且/或發現 Pod 已重新啟動多次：

$ kubectl get pods -n gke-connect
NAME                                                READY   STATUS    RESTARTS   AGE
gke-connect-agent-20230706-03-00-6b8f75dd58-dzwmt   1/1     Running   5          99m

如要排解這類行為，請說明 Pod，查看其最後狀態是否因記憶體不足錯誤 (OOMKilled) 而終止：

  kubectl describe pods/gke-connect-agent-20230706-03-00-6b8f75dd58-dzwmt -n gke-connect
        <some details skipped..>
        Last State:     Terminated
        Reason:       OOMKilled
可能原因
根據預設，Connect 代理程式 Pod 的 RAM 上限為 256MiB。如果叢集安裝了大量工作負載，部分要求和回應可能無法如預期處理。
解決方法

更新 Connect Agent 部署作業，並授予更高的記憶體限制，例如：

containers:
  name: gke-connect-agent-20230706-03-00
  resources:
    limits:
      memory: 512Mi

PermissionDenied 個錯誤

問題

您可能發生了如下所示的錯誤：

tunnel.go:250: serve: recv error: rpc error: code = PermissionDenied
desc = The caller does not have permission
dialer.go:210: dialer: dial: connection to gkeconnect.googleapis.com:443
failed after 335.153278ms: serve: receive request failed: rpc error:
code = PermissionDenied desc = The caller does not have permission
dialer.go:150: dialer: connection done: serve: receive request failed:
rpc error: code = PermissionDenied desc = The caller does not have permission
dialer.go:228: dialer: backoff: 1m14.1376766s
可能原因

這可能表示您尚未將必要的身分與存取權管理 (IAM) 角色與您為了授權讓 Connect 代理程式連上 Google 而建立的Google Cloud 服務帳戶繫結起來。服務帳戶必須使用 gkehub.connect 身分與存取權管理角色。 Google Cloud

如果您刪除並重新建立同名的服務帳戶，也可能發生這種情況。 Google Cloud在這種情況下，您也需要刪除並重新建立 IAM 角色繫結。詳情請參閱「刪除和重新建立服務帳戶」一文。

解決方法

將 gkehub.connect 角色與您的服務帳戶繫結起來 (請注意，gkehub.admin 角色不具備連線所需的適當權限，不適合服務帳戶使用)。

舉例來說，如果專案名稱是 my-project，服務帳戶名稱是 Google Cloudgkeconnect@my-project.iam.gserviceaccount.com，您可執行以下指令，將角色與服務帳戶繫結起來：

gcloud projects add-iam-policy-binding my-project --member \
serviceAccount:gkeconnect@my-project.iam.gserviceaccount.com \
--role "roles/gkehub.connect"

您可以檢查下列指令的輸出內容，查看並確認服務帳戶權限已套用至 Google Cloud 服務帳戶，您應該會看到 role: roles/gkehub.connect 繫結至相關聯的 Google Cloud 服務帳戶。

gcloud projects get-iam-policy my-project

繫結身分與存取權管理角色和 Google Cloud 服務帳戶時發生錯誤

問題

您可能發生了如下所示的錯誤：

ERROR: (gcloud.projects.add-iam-policy-binding) PERMISSION_DENIED:
Service Management API has not been used in project [PROJECT_ID] before or it
is disabled. Enable it by visiting
https://console.developers.google.com/apis/api/servicemanagement.googleapis.com/overview?project=[PROJECT_ID]
then retry. If you enabled this API recently, wait a few minutes for the
action to propagate to our systems and retry.
可能原因

您可能不具有執行 gcloud projects add-iam-policy-binding 指令的身分與存取權管理權限。

解決方法

您需要具備 resourcemanager.projects.setIamPolicy 權限。如果您具有 Project IAM Admin、Owner 或 Editor 角色，應該可以執行此指令。若內部安全政策禁止您執行這個指令，請洽管理員。

系統時鐘偏差導致錯誤

問題

您可能發生了如下所示的錯誤：

acceptCall: failed to parse token in req [rpc_id=1]: Token used before issued [rpc_id=1]
可能原因

記錄訊息通常表示叢集上的時鐘偏差。 叢集核發的權杖時間戳記不同步，因此遭到拒絕。

解決方法

如要確認時鐘是否未正確同步，請在叢集上執行 date 指令，並與標準時間比較。通常只要幾秒鐘的時差就會造成這個問題。如要解決這個問題，請重新同步叢集的時鐘。

在 Google Cloud 控制台中看不見工作負載

問題

在 Connect Agent 記錄中，您可能會留意到以下錯誤：

"https://10.0.10.6:443/api/v1/nodes" YYYY-MM-DDTHH mm:ss.sssZ http.go:86: GET
"https://10.0.10.6:443/api/v1/pods" YYYY-MM-DDTHH mm:ss.sssZ http.go:139:
Response status: "403 Forbidden" YYYY-MM-DDTHH mm:ss.sssZ http.go:139:
Response status: "403 Forbidden"`
可能原因

這些記錄表明 Google Cloud 嘗試使用您在註冊時提供的認證存取叢集。403 錯誤表明這些憑證不具備存取該叢集所需的權限。

解決方法

確認憑證和所繫結的帳戶，確認帳戶具有必需的叢集權限。

Context deadline exceeded

問題

您可能發生了如下所示的錯誤：

2019/03/06 21:08:43.306625 dialer.go:235: dialer: dial: connecting to gkeconnect.googleapis.com:443...
2019/03/06 21:09:13.306893 dialer.go:240: dialer: dial: unable to connect to gkeconnect.googleapis.com:443: context deadline exceeded
2019/03/06 21:09:13.306943 dialer.go:183: dialer: connection done: context deadline exceeded
可能原因

這項錯誤表示發生低階 TCP 網路問題，Connect Agent 無法與 gkeconnect.googleapis.com 通訊。

解決方法

確認這個叢集中的 Pod 工作負載可以解析 gkeconnect.googleapis.com，並透過 443 連接埠建立連出連線。

服務專員連線斷斷續續

問題

在 Connect Agent 記錄中，您可能會留意到以下錯誤：

2020/10/06 18:02:34.409749 dialer.go:277: dialer: dial: connection to gkeconnect.googleapis.com:443 failed after 8m0.790286282s: serve: receive request failed: rpc error: code = Unavailable desc = transport is closing
2020/10/06 18:02:34.416618 dialer.go:207: dialer: connection done: serve: receive request failed: rpc error: code = Unavailable desc = transport is closing
2020/10/06 18:02:34.416722 dialer.go:295: dialer: backoff: 978.11948ms
2020/10/06 18:02:34.410097 tunnel.go:651: sendResponse: EOF [rpc_id=52]
2020/10/06 18:02:34.420077 tunnel.go:651: sendResponse: EOF [rpc_id=52]
2020/10/06 18:02:34.420204 tunnel.go:670: sendHalfClose: EOF [rpc_id=52]
2020/10/06 18:02:34.401412 tunnel.go:670: sendHalfClose: EOF [rpc_id=53]
可能原因

如果 Connect 代理程式沒有足夠的資源，與 Connect 的連線就會關閉，例如在較小的 AWS EC2 執行個體 (如 t3.medium) 上。

解決方法

如果您使用 AWS 和 T3 執行個體類型，請啟用T3 無上限，或執行個體類型為節點集區提供更多資源。

機群無法存取專案

問題

在某些 Fleet 作業 (通常是叢集註冊) 期間，您可能會看到類似下列的錯誤：

ERROR: (gcloud.container.hub.memberships.register) failed to initialize Feature
"authorizer", the fleet service account (service-PROJECT_NUMBER@gcp-sa-gkehub.iam.gserviceaccount.com) may not have access to your project
可能原因

您可能會不小心解除 Fleet 的預設服務帳戶 gcp-sa-gkehub 與專案之間的繫結。Fleet 服務代理程式是 IAM 角色，可授予服務帳戶管理叢集資源的權限。如果從服務帳戶移除這個角色繫結，預設服務帳戶就會解除與專案之間的繫結，導致您無法註冊叢集及執行其他叢集作業。

您可以使用 gcloud CLI 或 Google Cloud 控制台，檢查服務帳戶是否已從專案中移除。如果該指令或資訊主頁在您所有的服務帳戶中未顯示 gcp-sa-gkehub，表示服務帳戶已解除繫結。

gcloud

執行下列指令：

gcloud projects get-iam-policy PROJECT_NAME

其中 PROJECT_NAME 是您要註冊叢集的專案名稱。

控制台

前往 Google Cloud 控制台的「IAM & admin」(IAM 與管理) 頁面。

解決方法

如果您移除了 Fleet 服務代理程式角色繫結，請執行下列指令來還原角色繫結：

PROJECT_NUMBER=$(gcloud projects describe PROJECT_NAME --format "value(projectNumber)")
gcloud projects add-iam-policy-binding PROJECT_NAME \
  --member "serviceAccount:service-${PROJECT_NUMBER}@gcp-sa-gkehub.iam.gserviceaccount.com" \
  --role roles/gkehub.serviceAgent

確認系統已授予角色繫結：

gcloud projects get-iam-policy PROJECT_NAME

若您看到服務帳戶名稱及 gkehub.serviceAgent 角色，表示系統已授予角色繫結。例如：

- members:
  - serviceAccount:service-1234567890@gcp-sa-gkehub.iam.gserviceaccount.com
  role: roles/gkehub.serviceAgent

從與 Fleet 不同的專案註冊 GKE 叢集時發生錯誤

問題

從與機群專案不同的專案註冊 GKE 叢集時，您可能會在 gcloud CLI 中看到類似下列的錯誤：

...
message: 'DeployPatch failed'>
detail: 'DeployPatch failed'
...

您可以在記錄中套用下列篩選器進行驗證： 

resource.type="gke_cluster"
resource.labels.cluster_name="my-cluster"
protoPayload.methodName="google.container.v1beta1.ClusterManager.UpdateCluster"
protoPayload.status.code="13"
protoPayload.status.message="Internal error."
severity=ERROR

可能原因

Fleet 預設服務帳戶在 GKE 叢集專案中沒有必要權限。

解決方法

在註冊叢集前，請先授予機群預設服務帳戶必要權限。

在憑證輪替期間註冊/取消註冊 GKE 叢集，或更新已註冊 GKE 叢集的機群成員資格詳細資料時發生錯誤

問題

輪替叢集憑證(https://cloud.google.com/kubernetes-engine/docs/how-to/credential-rotation)時，如果註冊/取消註冊 GKE 叢集，或更新已註冊 GKE 叢集的成員資格，可能會發生錯誤。

ERROR: (gcloud.container.hub.memberships.unregister) "code": 13,
"message": "an internal error has occurred"
可能原因

叢集憑證處於中間狀態，機群服務無法存取。

解決方法

完成輪替，再註冊/取消註冊叢集，或更新已註冊 GKE 叢集的成員資格。

停用 Fleet API 時發生錯誤

問題

嘗試停用 Fleet API (gkehub.googleapis.com) 時，可能會遇到類似下列的錯誤：

Not ready to deactivate the service on this project; ensure there are no more resources managed by this service.
可能原因

這項專案中仍有叢集註冊至 Google Cloud (成員資格)，或啟用了機群層級功能。必須先取消註冊或停用所有會員或功能，才能停用 API。

  • 如要查看目前已註冊的叢集，請按照「查看機群成員」一文中的操作說明執行

  • 如要查看專案的所有有效機群層級功能，請按照下列步驟操作：

gcloud 和 cURL

$ curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://gkehub.googleapis.com/v1alpha/projects/PROJECT_NAME/locations/global/features

其中 PROJECT_NAME 是您要停用 Fleet API 的專案名稱。

控制台

如果專案已啟用 GKE Enterprise，請前往 Google Cloud 主控台的「功能管理工具」頁面。如果功能顯示為「已啟用」，表示該功能已在車隊層級啟用。

解決方法

請先取消註冊仍向專案機群註冊的叢集。如要停用部分功能，必須先取消註冊所有叢集。

完成後，請停用所有機群層級的功能。目前只能透過 Fleet REST API 執行這項操作。

  1. 停用您為專案啟用的車隊層級功能

    $ gcloud alpha container hub FEATURE_COMMAND disable

  2. 停用預設啟用的功能授權方和計量。

    $ curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -X "DELETE" \
    https://gkehub.googleapis.com/v1alpha/projects/PROJECT_NAME/locations/global/features/FEATURE

    其中 FEATURE 是要停用的功能名稱 (例如 authorizer 或 metering)。

註冊叢集時缺少叢集權限

症狀：

嘗試使用使用者帳戶或 Google Cloud 服務帳戶註冊叢集時，可能會收到類似下列內容的錯誤訊息：

ERROR: (gcloud.container.hub.memberships.register) ResponseError: code=403, message=Required "container.clusters.get" permission(s) for "projects/my-project/zones/zone-a/clusters/my-cluster"
可能原因：

嘗試註冊叢集的帳戶在叢集中沒有必要的cluster-admin角色式存取控管 (RBAC) 角色。

修正結果：

註冊叢集前，請將 cluster-admin RBAC 角色指派給帳戶。

註冊叢集時發生 Failed to check if the user is a cluster-admin: Unable to connect to the server 錯誤

症狀：

嘗試註冊叢集時，可能會收到類似下列內容的錯誤：

ERROR: (gcloud.container.hub.memberships.register) Failed to check if the user is a cluster-admin: Unable to connect to the server: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)

或

ERROR: (gcloud.container.hub.memberships.register) Failed to check if the user is a cluster-admin: Unable to connect to the server: dial tcp MASTER_ENDPOINT_IP:443: i/o timeout
可能原因：

執行註冊 gcloud 指令的機器無法連線至叢集的外部端點。如果您有停用外部存取權/IP 的私人叢集，但您機器的外部 IP 位址不在允許清單中，通常會發生這種情況。請注意，在 gcloud 407.0.0 之後，註冊 GKE 叢集時就不需要這個要求。

修正結果：

請確認要執行 gcloud 註冊指令的電腦可以存取叢集的 API 伺服器。如果叢集未啟用外部存取權，請向支援團隊回報問題 Google Cloud 。

錯誤：無法刪除 Google 管理的會員方案

將叢集註冊至機群後，叢集就會成為機群成員，並獲得專屬的機群成員名稱。如果您嘗試執行 gcloud container hub memberships delete MEMBERSHIP_NAME 刪除這項成員資格，可能會看到下列錯誤：

ERROR: (gcloud.container.hub.memberships.delete) FAILED_PRECONDITION: membership "projects/PROJECT_ID/locations/us-centrall/memberships/MEMBERSHIP_NAME" is a managed resource of your cluster. Deleting a google-managed membership directly is not allowed. Please offboard your fleet membership via cluster API: failed precondition

如要正確刪除機群成員資格，請按照「取消註冊叢集」一文中的說明操作。

取得其他協助

如要向 GKE Enterprise 支援團隊提出支援單，請按照下列步驟操作： Google Cloud

  1. 向 Google Cloud 支援團隊提交客服案件。
  2. 按照「收集 Connect Agent 記錄」一文中的操作說明，儲存 Connect 記錄。
  3. 如果使用 Google 群組或第三方支援服務排解內部部署叢集的問題，請按照「收集 GKE Identity Service 記錄」一文中的操作說明，儲存 GKE Identity Service 記錄。如有需要，請務必清除儲存檔案中的 Pod 記錄。
  4. 將相關記錄附加至案件。