使用 Connect Gateway
本頁說明如何使用 Connect Gateway 連線至已註冊的叢集。閱讀本頁面之前，請先熟悉總覽中的概念。本指南假設專案管理員已設定閘道，並授予您必要角色和權限。
事前準備
確認您已安裝下列指令列工具：
- 最新版 Google Cloud CLI，用於與 Google Cloud互動的指令列工具。
kubectl
如果您使用 Cloud Shell 做為與 Google Cloud互動的 Shell 環境，系統會為您安裝這些工具。
確認您已初始化 gcloud CLI，以便搭配專案使用。
登入 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 指令為串流指令，因此有額外需求：
attachcpexecport-forward
請注意下列要求：
如要使用
attach、cp和exec指令，叢集必須為 1.30 以上版本；如要使用port-forward指令，叢集必須為 1.31 以上版本。kubectl用戶端必須為 1.31 以上版本。如要查看用戶端版本，請查看
kubectl version指令的輸出內容。如要安裝新版kubectl，請參閱「安裝工具」。
擁有 roles/gkehub.gatewayAdmin IAM 角色和 cluster-admin ClusterRole 的使用者和服務帳戶，具備執行 attach、cp、exec 和 port-forward 指令的必要權限。如果使用者和服務帳戶已獲派自訂 IAM 角色或自訂 RBAC 角色，您可能需要授予額外權限。詳情請參閱以下各節。
視需要授予其他權限
如要透過 Connect 閘道執行 attach、cp、exec 和 port-forward 指令，必須具備 gkehub.gateway.stream IAM 權限。這項權限包含在 roles/gkehub.gatewayAdmin 中。
如果使用者不是專案擁有者，或使用者/服務帳戶未獲授專案的 roles/gkehub.gatewayAdmin，您必須授予他們 roles/gkehub.gatewayAdmin，或建立包含其他必要角色和 gkehub.gateway.stream 權限的自訂角色。如要瞭解如何建立自訂角色，請參閱 IAM 說明文件中的「建立及管理自訂角色」。
視需要建立及套用其他 RBAC 政策
具備 cluster-admin ClusterRole 的使用者和服務帳戶，擁有執行 attach、cp、exec 和 port-forward 指令的必要權限。
如要執行指令，至少需要下列規則：
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: User
name: EMAIL # Specify the user that should have stream access
namespace: NAMESPACE # Specify the namespace
疑難排解
如果無法透過閘道連線至叢集，您或管理員可以檢查下列常見問題。
- 伺服器沒有資源類型：如果
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.gatewayAdminroles/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：Gateway 的 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 分鐘後發生這項錯誤，這是基於安全考量而設下的限制，屬於預期情況。必須重新建立連線。
後續步驟
- 如需如何將 Connect 閘道納入 DevOps 自動化程序中的範例，請參閱「與 Cloud Build 整合」教學課程。