使用 Connect 网关
本页面介绍如何使用 Connect 网关连接到已注册的集群。在阅读本指南之前，您应该先熟悉我们的概览中的概念。本指南假设您的项目管理员已经设置网关，并为您提供必要的角色和权限。
准备工作
确保您已安装以下命令行工具：
- 最新版本的 Google Cloud CLI，用于与 Google Cloud 交互的命令行工具。
kubectl
如果您使用 Cloud Shell 作为与 Google Cloud 交互的 Shell 环境，则系统会为您安装这些工具。
确保您已初始化用于您项目的 gcloud CLI。
登录您的 Google Cloud 账号
您可以使用自己的 Google Cloud 账号或 Google Cloud 服务账号，通过网关 API 与连接的集群进行交互。
按照向 Google Cloud CLI 工具授权中的说明登录您的用户账号。Connect 网关支持服务账号模拟，因此即使您登录的是自己的用户账号，您仍然可以使用服务账号与集群进行交互，如下面几部分中所示。
选择已注册的集群
如果您不知道要访问的集群的名称，可以运行以下命令来查看当前所有舰队的已注册集群：
gcloud container fleet memberships list
该命令会列出舰队的所有集群，包括其成员资格名称和外部 ID。设备组中的每个集群都有一个唯一的成员资格名称。对于 GKE 集群，成员资格名称通常与您在创建集群时提供的名称匹配，除非注册时集群名称在其项目中不是唯一的。
获取集群的网关 kubeconfig
使用以下命令获取与指定的集群进行交互所需的 kubeconfig：
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME
将 MEMBERSHIP_NAME 替换为您的集群的舰队成员资格名称。
此命令会返回一个特殊的特定于 Connect 网关的 kubeconfig，允许您通过 Connect 网关连接到集群。
如果您想使用服务账号，而不是您自己的 Google Cloud 账号，请使用 gcloud config 将 auth/impersonate_service_account 设置为服务账号的电子邮件地址。
如需使用服务账号提取用于与 Connect 网关交互的集群凭据，请运行以下命令：请注意以下事项：
- Google Distributed Cloud on Bare Metal（纯软件）集群和 Google Distributed Cloud on VMware（纯软件）集群：成员资格名称与集群名称相同。
GKE on AWS：使用
gcloud container aws clusters get-credentials。GKE on Azure：使用
gcloud container azure clusters get-credentials。
如果您想使用服务账号，而不是您自己的 Google Cloud 账号，请使用 gcloud config 将 auth/impersonate_service_account 设置为服务账号的电子邮件地址。您可以在管理对服务账号的访问权限中详细了解如何让用户模拟服务账号。
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
限制
使用 gcloud container fleet memberships get-credentials 命令的网关不支持以下 kubectl 命令：
attachcpexecport-forward
预览对命令的支持
Beta 版命令 gcloud beta container fleet memberships get-credentials 支持 attach、cp 和 exec 命令（但不支持 port-forward）。此命令可让您使用 Connect 网关的预览功能。
请注意以下要求：
预览版不支持 GKE on Google Cloud。
集群必须为 1.30 或更高版本。
kubectl客户端必须为 1.29 版或更高版本。如果您使用的是版本 1.29，则必须设置以下环境变量：export KUBECTL_REMOTE_COMMAND_WEBSOCKETS=truekubectl版本 1.30 及更高版本不需要环境变量。如需检查客户端版本，请查看
kubectl version命令的输出。如需安装较新版本的kubectl，请参阅安装工具。
具有 roles/gkehub.gatewayAdmin IAM 角色和 cluster-admin ClusterRole 的用户和服务账号具有运行 attach、cp 和 exec 命令所需的权限。如果用户和服务账号已获授自定义 IAM 角色或自定义 RBAC 角色，您可能需要授予额外的权限。如需了解详情，请参阅以下部分：
如有需要，授予额外权限
如需通过 Connect 网关运行 attach、cp 和 exec 命令，您需要拥有 gkehub.gateway.stream IAM 权限。此权限包含在 roles/gkehub.gatewayAdmin 中。
对于不是项目所有者的用户，或者对于尚未在项目中获得 roles/gkehub.gatewayAdmin 的用户或服务账号，您必须向其授予 roles/gkehub.gatewayAdmin，或者创建包含其他所需角色和 gkehub.gateway.stream 权限的自定义角色。如需了解如何创建自定义角色，请参阅 IAM 文档中的创建和管理自定义角色。
创建和应用其他 RBAC 政策（如有需要）
具有 cluster-admin ClusterRole 的用户和服务账号拥有运行 attach、cp 和 exec 命令所需的权限。
至少需要满足以下规则才能运行命令：
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: stream-role
namespace: NAMESPACE # Specify the namespace
rules:
- apiGroups: ["*"]
resources: ["pods/exec", "pods/attach"]
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 exec/cp/attach 问题排查
运行命令时返回的错误通常不够明确，无法用于调试问题。在这种情况下，请使用更高的详细日志记录级别重新运行命令，例如：kubectl exec -v 5 ...。
未使用 Connect 网关 Beta 版跟踪
如果您收到 400 Bad Request 错误，请使用 gcloud CLI Beta 版跟踪重新生成 Connect 网关 kubeconfig 文件，看看是否能修正该错误：
gcloud beta container fleet memberships get-credentials my-membership`
如果您仍然收到 400 Bad Request 错误，请按照下一部分中的步骤操作。
未设置 kubectl 环境标志
如果您使用的 kubectl 客户端版本为 1.29，则需要启用环境变量 KUBECTL_REMOTE_COMMAND_WEBSOCKETS。如果未启用此功能，您会收到 400 Bad Request 错误。如需查看环境变量是否已启用，请运行以下命令：
echo $KUBECTL_REMOTE_COMMAND_WEBSOCKETS`
如果未设置该变量，请通过设置以下环境变量来启用该变量：
export KUBECTL_REMOTE_COMMAND_WEBSOCKETS=true
kubectl 版本 1.30 及更高版本不需要此标志，因为它默认处于启用状态。
低于 1.29 的 kubectl 版本不支持此功能。
缺少 IAM 权限
如果您收到 error: error reading from error stream... 消息，则表示您尚未获得运行该命令所需的 IAM 权限。此功能要求用户具有 gkehub.gateway.stream IAM 权限，该权限默认包含在 roles/gkehub.gatewayAdmin 角色中。如需查看相关说明，请参阅 IAM 权限部分。
错误消息 generic::failed_precondition：集群中遇到错误
如果您收到 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...。
缺少必要的 RBAC 权限
如果 Connect Agent 日志中的错误消息包含 403 Forbidden，则表示您缺少 RBAC 权限。您在集群中具有一组 RBAC 权限，可用于运行这些 kubectl 命令。如需设置所需的 RBAC 权限，请参阅 RBAC 政策部分。
错误消息 generic::resource_exhausted：网关的 active_streams 配额用尽
每个舰队宿主项目最多只能有 10 个活跃流。这在 connectgateway.googleapis.com/active_streams 配额下定义。如需了解如何管理配额，请参阅查看和管理配额。
错误消息 generic::failed_precondition：连接代理失败/终止
如果您在运行该命令时立即遇到此错误，则表示集群与 Google 之间的连接存在问题。如需了解详情，请参阅常规问题排查指南。
如果在会话处于活跃状态大约 5 到 10 分钟后遇到此错误，则这是该功能的预期限制。需要重新建立连接。
问题排查
如果您在通过网关连接到集群时遇到问题，您或您的管理员可以查看以下常见问题。
- 服务器没有资源类型：当命令
kubectl get ns失败时，您可能会看到此错误消息。导致此错误的原因有多种。以详细模式运行kubectl命令以查看更多详细信息，例如kubectl get ns -v 10。 - 找不到集群的有效连接（项目：12345，成员资格：my-cluster）：当 Connect Agent 连接中断或未正确安装时，您可能会看到此错误（仅限 Google Cloud 外部的集群）。如需解决此问题，您需要验证集群上是否存在
gke-connect命名空间。如果集群中存在gke-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 Agent 就能运行，因此系统在成员注册期间不会默认安装 Connect Agent。较旧版本的 Google Cloud CLI（399.0.0 及更低版本）假定集群上存在 Connect Agent。在使用较新版本的 Google Cloud CLI 注册的集群上，尝试将网关与这些旧版本搭配使用可能会失败。要解决此问题，请将 Google Cloud CLI 客户端升级到较新的版本，或使用
--install-connect-agent标志重新运行成员注册命令。
后续步骤
- 如需了解如何将 Connect 网关用作 DevOps 自动化的一部分的示例，请参阅与 Cloud Build 集成教程。