使用 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，并将 MEMBERSHIP_NAME 替换为集群的舰队成员资格名称。此命令会返回一个特殊的特定于 Connect 网关的 kubeconfig，允许您通过网关连接到集群。

# Fetch cluster credential used to interact with Connect gateway
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

如果您想使用服务账号，而不是您自己的 Google Cloud 账号，请使用 gcloud config 将 auth/impersonate_service_account 设置为服务账号的电子邮件地址。您可以在管理对服务账号的访问权限中详细了解如何让用户模拟服务账号。

# Fetch cluster credential used to interact with Connect gateway, using a service account
gcloud config set auth/impersonate_service_account SA_EMAIL_ADDRESS
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

针对集群运行命令

获得必要的凭据后，您可以照常使用 kubectl 或 go-client 针对 Kubernetes 集群运行命令。输出内容应如下所示：

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

网关不支持以下 kubectl 命令：

attach
cp
exec
port-forward

问题排查

如果您在通过网关连接到集群时遇到问题，您或您的管理员可以查看以下常见问题。

服务器没有资源类型：当命令 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 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 集成教程。