使用 Connect 网关

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

准备工作

  • 确保您已安装以下命令行工具:

    • 最新版本的 Cloud SDK,其中包含用于与 Google Cloud 交互的命令行工具 gcloud
    • kubectl

    如果您使用 Cloud Shell 作为与 Google Cloud 交互的 Shell 环境,则系统会为您安装这些工具。

  • 确保您已初始化 用于您的项目的 gcloud 命令行工具。

登录您的 Google Cloud 帐号

您可以使用自己的 Google Cloud 帐号或 Google Cloud 服务帐号,通过网关 API 与连接的集群进行交互。

按照授权 Cloud SDK 工具中的说明登录您的用户帐号。Connect 网关支持服务帐号模拟,因此即使您登录的是自己的用户帐号,您仍然可以使用服务帐号与集群进行交互,如下面几部分中所示。

选择已注册的集群

如果您不知道要访问的集群的名称,可以运行以下命令来查看当前 Environ 的所有已注册的集群:

gcloud container hub memberships list

该命令会列出 Environ 的所有集群,包括其成员资格名称和外部 ID。Environ 中的每个集群都有一个唯一的成员资格名称。对于 GKE 集群,成员资格名称通常与您在创建集群时提供的名称匹配,除非注册时集群名称在其项目中不是唯一的。

获取集群的网关 kubeconfig

使用以下命令获取与指定的集群交互所需的 kubeconfig,并将 MEMBERSHIP_NAME 替换为您的集群的 Environ 成员资格名称。此命令会返回一个特殊的特定于 Connect 网关的 kubeconfig,允许您通过网关连接到集群。

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

如果您想使用服务帐号,而不是您自己的 Google Cloud 帐号,请使用 gcloud configauth/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 beta container hub memberships get-credentials MEMBERSHIP_NAME

针对集群运行命令

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

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

网关支持以下 kubectl 命令:

  • exec
  • proxy

问题排查

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

  • 服务器没有资源类型“命名空间”:当 kubectl get ns 之类的简单命令失败时,您可能会看到此错误消息。导致此错误的原因有多种。以详细模式运行 kubectl 命令以查看更多详细信息,例如 kubectl get ns -v 10
  • 在此服务器上找不到请求的网址:如果 kubeconfig 包含不正确的服务器地址,您可能会看到此错误。请确保您使用的 Cloud SDK 版本为最新版本,然后重试以生成网关 kubeconfig。不要手动修改 kubeconfig 文件,因为这会导致意外错误。
  • 用户身份权限不足,无法使用网关 API:您需要具备 role/gkehub.gatewayAdmin 角色才能使用 API。如需了解详情,请参阅网关设置指南中的授予 IAM 权限
  • Connect 代理无权发送用户的请求:Connect 代理需要能够代表您转发请求,该设置通过针对集群的模拟政策指定。如需查看将用户添加到 gateway-impersonate 角色的示例,请参阅网关设置指南中的配置 RBAC 政策
  • 用户身份没有足够的 RBAC 权限,无法执行相应操作:您必须对集群拥有适当的权限才能运行所选的操作。如需查看将用户添加到适当的 ClusterRole 的示例,请参阅网关设置指南中的配置 RBAC 政策
  • Connect 代理运行状况不佳:请参阅“Connect 问题排查”页面,确保您的集群已连接。

后续步骤

  • 如需了解如何将 Connect 网关用作 DevOps 自动化的一部分的示例,请参阅与 Cloud Build 集成教程。