本页面介绍如何使用 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。
您可以在管理对服务账号的访问权限中详细了解如何让用户模拟服务账号。
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 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标志重新运行成员注册命令。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：集群中遇到错误
如果您收到 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：连接代理失败/终止
如果您在运行该命令时立即遇到此错误，则表示集群与 Google 之间的连接存在问题。如需了解详情，请参阅常规问题排查指南。
如果在会话处于活跃状态大约 20 到 30 分钟后遇到此错误，则这是出于安全原因而设置的预期限制。需要重新建立连接。
后续步骤
- 如需了解如何将 Connect 网关用作 DevOps 自动化的一部分的示例，请参阅与 Cloud Build 集成教程。