使用 Connect Gateway

本頁說明如何使用 Connect Gateway 連線至已註冊的叢集。閱讀本頁面之前，請先熟悉總覽中的概念。本指南假設專案管理員已設定閘道，並授予您必要角色和權限。

事前準備

  • 確認您已安裝下列指令列工具：

    如果您使用 Cloud Shell 做為與 Google Cloud互動的 Shell 環境，系統會為您安裝這些工具。

  • 確認您已初始化 gcloud CLI，以便搭配專案使用。

必要的角色

如要取得使用連線閘道連線至叢集及執行指令所需的權限，請要求管理員在叢集專案中授予您下列 IAM 角色：

  • 取得叢集的 kubeconfig 檔案： Connect Gateway 讀取者 (roles/gkehub.gatewayReader)
  • 執行 kubectl CLI 指令： Connect Gateway 管理員 (roles/gkehub.gatewayAdmin)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

Connect Gateway 管理員 (roles/gkehub.gatewayAdmin) 角色是唯一包含 gkehub.gateway.stream 權限的預先定義角色，而執行 kubectl CLI 指令 (例如 attach、exec、port-forward 和 cp) 時，必須具備這項權限。

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

登入 Google Cloud 帳戶

您可以透過 Gateway API，使用自己的 Google Cloud 帳戶或 Google Cloud 服務帳戶與已連線的叢集互動。

按照「授權 Google Cloud CLI 工具」中的操作說明登入使用者帳戶。Connect 閘道支援服務帳戶模擬，因此即使您登入自己的使用者帳戶，也可以使用服務帳戶與叢集互動，如下節所示。

選取已註冊的叢集

如果您不知道要存取的叢集名稱，可以執行下列指令，查看目前機群中所有已註冊的叢集：

gcloud container fleet memberships list

這會列出機群中的所有叢集，包括成員名稱和外部 ID。機群中的每個叢集都有專屬的成員名稱。如果是 GKE 叢集，成員名稱通常會與您建立叢集時指定的名稱相符，除非叢集名稱在註冊時，於專案中並非專屬名稱。

取得叢集的閘道 kubeconfig

使用下列指令取得 kubeconfig，與指定叢集互動：

gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

將 MEMBERSHIP_NAME 替換為叢集的 Fleet 成員名稱。

這項指令會傳回專屬的 Connect 閘道 kubeconfig，讓您透過 Connect 閘道連線至叢集。

如要使用服務帳戶而非自己的 Google Cloud 帳戶，請使用 gcloud config 將 auth/impersonate_service_account 設為服務帳戶電子郵件地址。

如要擷取用於透過服務帳戶與 Connect 閘道互動的叢集憑證，請執行下列指令： 請注意下列事項：

  • 裸機和 VMware 上的 Google Distributed Cloud (僅限軟體) 叢集：成員名稱與叢集名稱相同。

  • GKE on AWS：使用 gcloud container aws clusters get-credentials。

  • GKE on Azure：使用 gcloud container azure clusters get-credentials。

如要進一步瞭解如何允許使用者模擬服務帳戶，請參閱「管理服務帳戶的存取權」。

gcloud config set auth/impersonate_service_account SA_EMAIL_ADDRESS
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

將 SA_EMAIL_ADDRESS 替換為服務帳戶的電子郵件地址。如要進一步瞭解如何允許使用者模擬服務帳戶，請參閱「管理服務帳戶的存取權」。

對叢集執行指令

取得必要憑證後，您就可以使用 kubectl 或 go-client 執行指令，就像對任何 Kubernetes 叢集執行指令一樣。輸出內容應如下所示：

# Get namespaces in the Cluster.
kubectl get namespaces
NAME              STATUS   AGE
default           Active   59d
gke-connect       Active   4d

kubectl exec/cp/attach/port-forward 指令

下列 kubectl 指令為串流指令，因此有額外需求：

  • attach
  • cp
  • exec
  • port-forward

如要執行這些指令，必須符合下列條件：

  • 叢集必須為 1.30 以上版本，才能使用 attach、cp 和 exec 指令；必須為 1.31 以上版本，才能使用 port-forward 指令。

  • kubectl 用戶端必須為 1.31 以上版本。如要查看用戶端版本，請查看 kubectl version 指令的輸出內容。如要安裝較新版本的 kubectl，請參閱「安裝工具」。

  • 使用者和服務帳戶必須透過 IAM 或 RBAC 取得下列 Kubernetes API 存取權：

    • IAM：授予包含 gkehub.gateway.stream 權限的角色。roles/gkehub.gatewayAdmin 預先定義的角色包含這項權限。您也可以將這項權限指派給自訂角色。

    • RBAC：授予包含 get 的角色或 ClusterRole，存取 pods/exec、pods/portforward 和 pods/attach API 子資源，例如下列範例中的角色和 RoleBinding：

      apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: stream-role
  namespace: NAMESPACE # Specify the namespace
rules:
- apiGroups: ["*"]
  resources: ["pods/exec", "pods/attach", "pods/portforward"]
  verbs: ["get"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: stream-rolebinding
  namespace: NAMESPACE # Specify the namespace
roleRef:
  apiGroup: "rbac.authorization.k8s.io"
  kind: Role
  name: stream-role
subjects:
- kind: Group
  name: EMAIL # Specify the group that should have stream access

      更改下列內容：

      • NAMESPACE：Role 和 RoleBinding 的命名空間。
      • EMAIL：應具備串流存取權的群組電子郵件地址 (如果叢集支援群組 RBAC)。

      cluster-admin 預設 ClusterRole 也包含這些權限。

疑難排解

如果無法透過閘道連線至叢集，您或管理員可以檢查下列常見問題。

  • 伺服器沒有資源類型：如果 kubectl get ns 指令失敗，您可能會看到這則錯誤訊息。造成這項錯誤的潛在原因有很多，以詳細輸出模式執行 kubectl 指令，即可查看更多詳細資料，例如 kubectl get ns -v 10。
  • 無法找到叢集的有效連線(專案：12345，成員資格：my-cluster)：如果 Connect 代理程式失去連線或未正確安裝 (僅限外部叢集)，可能會看到這個錯誤。 Google Cloud 如要解決這個問題，請確認叢集上是否有 gke-connect 名稱空間。如果叢集上存在 gke-connect 命名空間，請參閱「Connect 疑難排解」頁面，修正連線問題。
  • 在這個伺服器上找不到您要求的網址：如果 kubeconfig 含有不正確的伺服器位址，您可能會看到這則錯誤訊息。請確認您使用的是最新版 Google Cloud CLI，然後重試產生閘道 kubeconfig。請勿手動編輯 kubeconfig 檔案，否則會發生未預期的錯誤。
  • 使用者身分沒有足夠的權限來使用閘道 API：您需要 roles/gkehub.gatewayAdmin、roles/gkehub.gatewayReader 或 roles/gkehub.gatewayEditor 角色才能使用 API。詳情請參閱閘道設定指南中的「授予使用者 IAM 角色」。
  • Connect 代理程式未獲授權傳送使用者要求：Connect 代理程式必須獲准代表您轉送要求，這項設定是在叢集上使用模擬政策指定。如需將使用者新增至 gateway-impersonate 角色的範例，請參閱閘道設定指南中的「設定 RBAC 授權」。
  • 使用者身分沒有足夠的 RBAC 權限來執行作業：您必須在叢集上擁有適當的權限，才能執行所選作業。如需將使用者新增至適當 ClusterRole 的範例，請參閱閘道設定指南中的「設定 RBAC 授權」。
  • 使用 Google 群組或第三方支援時，使用者身分沒有足夠的權限執行作業：如需如何檢查與身分資訊相關記錄的說明，請參閱「收集 GKE Identity Service 記錄」。
  • Connect 代理程式狀況不佳：請參閱 Connect 疑難排解頁面，確認叢集已連線。
  • 找不到可執行的 gke-gcloud-auth-plugin 或找不到名稱為 gcp 的驗證供應商：kubectl 1.26 以上版本可能會顯示這項錯誤，這是因為從 GKE v1.26 開始，kubectl 驗證機制有所異動。安裝 gke-gcloud-auth-plugin，然後使用最新版 Google Cloud CLI 重新執行 gcloud container fleet memberships get-credentials MEMBERSHIP_NAME。
  • 使用舊版 Google Cloud CLI 時，與閘道的連線會失敗：對於 GKE 叢集，閘道不再需要 Connect 代理程式才能運作，因此在註冊成員時，系統不會預設安裝該代理程式。舊版 Google Cloud CLI (399.0.0 以下) 會假設叢集上存在 Connect 代理程式。如果叢集是使用較新版本的 Google Cloud CLI 註冊，嘗試搭配使用閘道與這些舊版可能會失敗。如要解決這個問題，請將 Google Cloud CLI 用戶端升級至較新版本，或使用 --install-connect-agent 旗標重新執行成員註冊指令。
  • gke-security-groups 群組下傳回的群組大小超過 8 KB 的 HTTP 標頭大小限制。重新整理群組階層並重試：雖然群組數量沒有硬性限制，但如果群組名稱過長，要求可能會超過 8 KB 的 HTTP 標頭大小限制，導致錯誤，您可能需要重整群組階層。

kubectl exec/cp/attach/port-forward 疑難排解

執行指令時傳回的錯誤通常是通用錯誤 400 Bad Request，不夠清楚，無法偵錯。如要傳回更詳細的錯誤訊息，請使用 kubectl 用戶端 1.32 以上版本，以詳細程度 4 以上執行指令，例如：kubectl exec -v 4 ...。

在傳回的記錄中，搜尋包含下列回應的記錄：

  • kubectl exec/cp/attach 指令：RemoteCommand fallback:
  • kubectl port-forward 指令：fallback to secondary dialer from primary dialer err:

如要排解 kubectl exec -v 4 ... 指令可能傳回的部分常見錯誤訊息，請參閱下一節。

缺少 IAM 權限

如果錯誤訊息包含 generic::permission_denied: Permission'gkehub.gateway.stream' denied on resource，這可能表示您未獲授權執行指令所需的 IAM 權限。使用者必須具備 gkehub.gateway.stream IAM 權限，才能使用這項功能。roles/gkehub.gatewayAdmin 角色預設包含這項權限。如需操作說明，請參閱「IAM 權限」一節。

缺少必要的 RBAC 權限

如果錯誤訊息包含 ...generic::failed_precondition: failed to connect to the cluster's API Server with response (status=403 Forbidden...，表示您缺少 RBAC 權限。您需要在叢集中擁有一組 RBAC 權限，才能執行這些 kubectl 指令。如要進一步瞭解如何設定必要的 RBAC 權限，請參閱「視需要建立及套用其他 RBAC 政策」。

錯誤訊息 generic::resource_exhausted：閘道的 active_streams 配額已用盡

每個機群主專案最多只能有 10 個有效串流。這項配額定義在 connectgateway.googleapis.com/active_streams 下方。如需管理配額的操作說明，請參閱「查看及管理配額」。

錯誤訊息 generic::failed_precondition: error encountered within the cluster

如果收到 generic::failed_precondition: error encountered within the cluster 錯誤訊息，請檢查叢集中的 Connect Agent 記錄，找出根本原因：

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

Connect Agent 中要尋找的記錄是 failed to create the websocket connection...。

錯誤訊息 generic::failed_precondition: connection to Agent failed/terminated

如果在執行指令時立即發生這項錯誤，表示叢集與 Google 的連線有問題。詳情請參閱一般疑難排解指南。

如果工作階段啟動約 20 到 30 分鐘後發生這個錯誤，這是基於安全考量而設下的限制，屬於正常現象。連線需要重新建立。

kubectl --raw 疑難排解

使用縮短的端點 (例如 kubectl get --raw /version) 可能會導致下列錯誤：Error from server (NotFound): the server could not find the requested resource。請務必提供完整伺服器地址。

從 kubeconfig 擷取端點：

# e.g. https://connectgateway.googleapis.com/v1/projects/1234567/locations/global/gkeMemberships/my-membership
FULL_GATEWAY_ENDPOINT=$(kubectl config view --minify -o jsonpath='{.clusters[*].cluster.server}')
echo $FULL_GATEWAY_ENDPOINT

然後使用指令的端點，例如使用 /version：

kubectl get --raw $FULL_GATEWAY_ENDPOINT/version

後續步驟

  • 如需如何將 Connect 閘道納入 DevOps 自動化程序，請參閱「與 Cloud Build 整合」教學課程。