Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

使用 Connect 网关

本页面介绍如何使用 Connect 网关连接到已注册的集群。在阅读本页面之前，请确保您熟悉我们的概览中的概念。本指南假设您的项目管理员已经设置网关，并为您提供必要的角色和权限。

准备工作

确保您已安装以下命令行工具：
- 最新版本的 Google Cloud CLI，它是用于与 Google Cloud交互的命令行工具。
- kubectl
如果您使用 Cloud Shell 作为与 Google Cloud交互的 Shell 环境，则系统会为您安装这些工具。
确保您已初始化用于您项目的 gcloud CLI。

所需的角色

如需获得使用连接网关连接到集群并运行命令所需的权限，请让您的管理员为您授予集群项目的以下 IAM 角色：

获取集群的 kubeconfig 文件： Connect Gateway Reader (roles/gkehub.gatewayReader)
运行 kubectl CLI 命令： Connect Gateway Admin (roles/gkehub.gatewayAdmin)

Connect Gateway Admin (roles/gkehub.gatewayAdmin) 角色是唯一包含 gkehub.gateway.stream 权限的预定义角色，而 gkehub.gateway.stream 权限是运行 kubectl CLI 命令（如 attach、exec、port-forward 和 cp）所必需的。

您也可以使用自定义角色或其他预定义角色来获取这些权限。

登录到您的 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 命令属于流式传输命令，并有额外的要求：

attach
cp
exec
port-forward

如需运行这些命令，您必须满足以下要求：

对于 attach、cp 和 exec 命令，集群必须为 1.30 版或更高版本；对于 port-forward 命令，集群必须为 1.31 版或更高版本。
kubectl 客户端必须为 1.31 版或更高版本。如需检查客户端版本，请查看 kubectl version 命令的输出。如需安装较新版本的 kubectl，请参阅安装工具。
用户和服务账号必须通过 IAM 或 RBAC 获得以下对 Kubernetes API 的额外访问权限：
- IAM：授予包含 gkehub.gateway.stream 权限的角色。roles/gkehub.gatewayAdmin 预定义角色包含此权限。您还可以将此权限分配给自定义角色。
- RBAC：授予包含对 pods/exec、pods/portforward 和 pods/attach API 子资源的 get 访问权限的角色或 ClusterRole，如以下 Role 和 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 Agent 连接中断或未正确安装（仅限 Google Cloud 外部的集群）时，您可能会看到此错误。如需解决此问题，您需要验证集群上是否存在 gke-connect 命名空间。如果集群中存在 gke-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 身份认证服务日志，了解如何检查与身份信息相关的日志。
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 分钟后遇到此错误，则这是出于安全原因而设置的预期限制。需要重新建立连接。

`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 集成教程。