注册集群的前提条件

本页面介绍了向 Google Cloud 注册 Kubernetes 集群的前提条件和要求,包括网络、Google Cloud 和 Kubernetes 集群配置,以及 Connect 代理的资源要求

所有注册

以下前提条件是手动注册任何类型的集群的前提条件。

安装命令行工具

确保您已安装以下命令行工具。如果您使用 Cloud Shell 作为与 Google Cloud 交互的 Shell 环境,则系统会为您安装这些工具。

安装 gcloud 命令行工具

gcloud 命令行工具是 Google Cloud 的命令行界面 (CLI),包含在 Cloud SDK 中。您可以使用 gcloud 命令行工具注册集群,也可以使用其他工具(如 Terraform 或 Cloud Console)注册集群,具体取决于您的集群类型。不过,即使您不将其用于集群注册,在此页面的许多其他设置步骤中,gcloud 也是必需项或有用项。

  1. 如果您尚未安装 Cloud SDK,请按照安装说明安装 Cloud SDK。您需要 281.0.0 或更高版本的 Cloud SDK。

  2. 运行以下命令以登录 Google Cloud:

gcloud auth login
  1. (可选)如果您打算试用 Alpha 版或测试版 Connect 功能,请安装 gcloud beta 组件:
 gcloud components install beta 

安装 kubectl

虽然 kubectl 不需要注册集群,但您可能需要它向注册集群的用户(如果他们不是集群所有者)以及其他平台特定的设置授予必要的基于角色的访问控制 (RBAC) 权限。您需要一个不低于 Google Kubernetes Engine (GKE) 支持的最低 Kubernetes 版本kubectl 版本。

我们建议使用 Cloud SDK 安装 kubectl

如需查看 kubectl 的版本,请运行以下命令:

kubectl version

客户端版本由输出的 gitVersion 指示。

要安装 kubectl,请运行以下命令:

gcloud components install kubectl

启用 API

您需要在 Google Cloud 项目中启用以下 API:

  • container.googleapis.com
  • gkeconnect.googleapis.com
  • gkehub.googleapis.com
  • cloudresourcemanager.googleapis.com

集群中的 Pod 必须能够直接或通过使用配置的代理服务器访问 googleapis.comgkeconnect.googleapis.com 地址。

如果要为注册启用 Workload Identity,则还必须启用以下各项:

  • iam.googleapis.com

非项目所有者必须获得 serviceusage.services.enable 权限,然后才能启用 API。

gcloud

要启用这些 API,请运行以下命令:

gcloud services enable \
 --project=[FLEET_HOST_PROJECT_ID] \
 container.googleapis.com \
 gkeconnect.googleapis.com \
 gkehub.googleapis.com \
 cloudresourcemanager.googleapis.com \
 iam.googleapis.com

其中:

如果您不想启用 Workload Identity,则可以省略 iam.googleapis.com

如需列出已在项目中启用的 API,请按照 Service Usage 文档中列出服务中的说明操作。

将所需的 IAM 角色授予注册集群的用户

在项目中拥有 roles/owner 角色后,您就拥有了完全的控制权,并且能够完成所有注册任务。

如果您在项目中没有 roles/owner 角色,则需要先获得特定的 IAM 角色,然后才能将集群连接到 Google。请参阅 Connect IAM 角色

以下 IAM 角色可确保您可以使用服务帐号注册和连接集群:

  • roles/gkehub.admin
  • roles/iam.serviceAccountAdmin
  • roles/iam.serviceAccountKeyAdmin
  • roles/resourcemanager.projectIamAdmin

仅对于 GKE 集群,您还可以添加以下角色,以获取集群的管理员权限(如果您尚未具有该角色),如果您创建了集群,您的用户帐号可能具有此角色:

  • roles/container.admin

对于 GKE 集群,此 IAM 角色包含 Kubernetes 基于角色的访问权限控制 (RBAC) cluster-admin 角色。对于其他集群环境,您需要使用 kubectl 授予此 RBAC 角色,如下一部分中所述。如需详细了解 GKE 中 IAM 与 RBAC 角色之间的关系,请参阅 GKE 文档

如果要使用 Workload Identity 注册集群,您只需要以下 IAM 角色:

  • roles/gkehub.admin

gcloud

要授予这些角色,请运行以下命令:

gcloud projects add-iam-policy-binding [FLEET_HOST_PROJECT_ID] \
 --member user:[GCP_EMAIL_ADDRESS] \
 --role=roles/gkehub.admin \
 --role=roles/iam.serviceAccountAdmin \
 --role=roles/iam.serviceAccountKeyAdmin \
 --role=roles/resourcemanager.projectIamAdmin

其中:

  • [FLEET_HOST_PROJECT_ID] 是您要在其中注册集群的 Google Cloud 项目 ID。了解如何查找此值
  • [GCP_EMAIL_ADDRESS] 是注册用户用于登录 Google Cloud 的帐号。

如需详细了解如何授予 IAM 角色,请参阅 IAM 文档中的授予、更改和撤消对资源的访问权限

为其他用户授予只读角色

具有以下角色的经过身份验证的用户可以在 Cloud Console 中查看已注册的用户集群。这些角色提供只读访问权限:

  • roles/gkehub.viewer
  • roles/container.viewer

gcloud

要向用户授予所需的角色,请运行以下命令:

gcloud projects add-iam-policy-binding [FLEET_HOST_PROJECT_ID] \
 --member user:[USER_EMAIL_ADDRESS] \
 --role roles/gkehub.viewer \
 --role=roles/container.viewer

其中:

  • [FLEET_HOST_PROJECT_ID] 是您要在其中注册集群的 Google Cloud 项目 ID。了解如何查找此值
  • [USER_EMAIL_ADDRESS] 是已通过身份验证的用户的电子邮件地址。

向注册集群的用户授予 cluster-admin RBAC 角色

cluster-admin 基于角色的访问权限控制 (RBAC) ClusterRole 可授予注册集群所需的权限。如果要注册的集群在 Google Cloud 中,您可以使用 IAM roles/container.admin 角色获得相同的权限,如 Google Cloud 设置和配置中所述。

kubectl

如果集群是由您创建的,则您可能会被授予此角色。您可以通过运行以下命令来验证这一点:

kubectl auth can-i '*' '*' --all-namespaces

如果您或其他用户需要该角色,请在集群中创建 ClusterRoleBinding 资源:

kubectl create clusterrolebinding [BINDING_NAME] --clusterrole cluster-admin --user [USER] 

其中:

  • [BINDING_NAME] 是您为 ClusterRoleBinding 资源选择的名称。
  • [USER] 是用于针对集群进行身份验证的身份。

如需详细了解 cluster-admin 角色,请参阅 Kubernetes 文档

Google Cloud 上的 GKE 集群

如果要在 Google Cloud 上注册 GKE 集群,则可能需要在注册集群之前执行以下一项或多项操作,具体取决于您选择的注册选项。

启用 GKE Workload Identity

如果要注册启用了集群 Workload Identity 的 GKE 集群,则必须在注册之前确保已在集群上启用了 GKE Workload Identity。如果向某个 GKE 集群注册机群 Workload Identity,但没有在集群上启用 GKE Workload Identity,则可能会导致该集群中的工作负载声明身份的方式不一致,并且配置不受支持。您可以在注册集群中详细了解使用 Workload Identity 注册集群的优势。

gcloud

如需检查您的 GKE 集群是否已启用 Workload Identity,请运行以下命令以列出集群的 Workload Identity 池

gcloud container clusters describe CLUSTER_NAME --format="value(workloadIdentityConfig.workloadPool)"

替换以下内容:

  • CLUSTER_NAME:GKE 集群的 name

如果您看到类似如下所示的结果,则表示您的 GKE 集群已启用 Workload Identity:

GKE_PROJECT_ID.svc.id.goog

如果没有结果,则表示未启用 Workload Identity。如需启用 Workload Identity,请按照启用 Workload Identity 中的说明操作。

授予将集群注册到其他项目的权限

将 GKE 集群注册到其自己项目中的机群时,除所有注册中所述的设置外,无需任何特殊权限设置。如果要将 GKE 集群从其自己的项目 (GKE_PROJECT) 注册到其他项目 (FLEET_HOST_PROJECT) 中的一组,但 FLEET_HOST_PROJECT 服务代理帐号 gcp-sa-gkehub 必须具有 GKE_PROJECT 项目的 gkehub.serviceAgent 角色。此角色可授予服务帐号管理该项目中的集群资源的权限。

您可以使用 gcloud 工具或 Cloud Console 检查队列宿主项目 gcp-sa-gkehub 服务帐号在集群的项目中是否具有所需角色,如下所示。

gcloud

运行以下命令:

gcloud projects get-iam-policy [GKE_PROJECT_ID]

控制台

  1. 选择集群的项目后,转到 Cloud Console 中的 IAM 和管理页面。

转到“IAM 和管理”页面 1. 选中包括 Google 提供的角色授权复选框以查看完整政策,包括服务代理。

如果看到 gcp-sa-gkehub,它的格式应为 service-[FLEET_HOST-PROJECT-NUMBER]@gcp-sa-gkehub.iam.gserviceaccount.com。例如:

  - members:
    - serviceAccount:service-1234567890@gcp-sa-gkehub.iam.gserviceaccount.com
    role: roles/gkehub.serviceAgent

如果项目的 IAM 政策中未列出服务代理,请执行以下操作以更新必要的权限:

gcloud

  1. 要向 gcp-sa-gkehub 授予 gkehub.serviceAgent 角色,请先确保此服务帐号存在。如果您之前在此项目中注册了集群,则此服务帐号应该已存在。您可以通过查看机群宿主项目的 IAM 政策进行检查:

    gcloud projects get-iam-policy [FLEET_HOST_PROJECT_ID]
    
  2. 如果您需要创建 gcp-sa-gkehub 服务帐号,请运行以下命令:

    gcloud beta services identity create --service=gkehub.googleapis.com --project=[FLEET_HOST_PROJECT_ID]

    此命令应输出以下内容:

    Service identity created: service-[FLEET_HOST_PROJECT_NUMBER]@gcp-sa-gkehub.iam.gserviceaccount.com
    
  3. 运行以下命令以向服务帐号授予这两个项目中的 roles/gkehub.serviceAgent 角色:

    GKE_PROJECT_ID=[GKE_PROJECT_ID]
    FLEET_HOST_PROJECT_ID=[FLEET_HOST_PROJECT_ID]
    FLEET_HOST_PROJECT_NUMBER=$(gcloud projects describe "${FLEET_HOST_PROJECT_ID}" --format "value(projectNumber)")
    gcloud projects add-iam-policy-binding "${FLEET_HOST_PROJECT_ID}" \
    --member "serviceAccount:service-${FLEET_HOST_PROJECT_NUMBER}@gcp-sa-gkehub.iam.gserviceaccount.com" \
    --role roles/gkehub.serviceAgent
    gcloud projects add-iam-policy-binding "${GKE_PROJECT_ID}" \
    --member "serviceAccount:service-${FLEET_HOST_PROJECT_NUMBER}@gcp-sa-gkehub.iam.gserviceaccount.com" \
    --role roles/gkehub.serviceAgent

    其中:

    • [GKE_PROJECT_ID] 是 GKE 集群的 Google Cloud 项目 ID。
    • [FLEET_HOST_PROJECT_ID] 是您要在其中注册集群的 Google Cloud 项目 ID。了解如何查找此值
  4. 如需确认已授予角色绑定,请再次运行以下命令:

    gcloud projects get-iam-policy [GKE_PROJECT_ID]
    

    如果您看到服务帐号名称和 gkehub.serviceAgent 角色,则已授予角色绑定。例如:

    - members:
      - serviceAccount:service-[FLEET_HOST_PROJECT_NUMBER]@gcp-sa-gkehub.iam.gserviceaccount.com
      role: roles/gkehub.serviceAgent
    

设置供 Connect Agent 使用的身份

虽然 Google Cloud 上 GKE 集群的大多数注册选项不会在集群上安装 Connect Agent,但目前您需要安装代理才能使用 Connect Gateway。您可以选择使用 gcloud 命令行工具进行注册。Connect Agent 需要身份才能向 Google Cloud 进行身份验证。

  • 队列工作负载身份(推荐):确保集群在您注册集群之前启用了 GKE Workload Identity,如上所述。
  • 服务帐号:如果您选择使用 Google Cloud 服务帐号而不是 Workload Identity,请按照以下说明创建服务帐号并下载其 JSON 密钥

为 Terraform 配置服务帐号

如果您想使用 Terraform 来注册 Google Kubernetes Engine 集群,则需要创建一个服务帐号,供 Terraform 用于访问 Fleet API 以创建成员资格。

gcloud

  1. 按如下方式创建服务帐号:

    gcloud iam service-accounts create [SERVICE_ACCOUNT_NAME] --project=[FLEET_HOST_PROJECT_ID]
  2. gkehub.admin IAM 角色绑定到服务帐号,以便 Terraform 可以将它与 Fleet API 一起使用:

    FLEET_HOST_PROJECT_ID=[FLEET_HOST_PROJECT_ID]
    gcloud projects add-iam-policy-binding ${FLEET_HOST_PROJECT_ID} \
     --member="serviceAccount:[SERVICE_ACCOUNT_NAME]@${FLEET_HOST_PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/gkehub.admin"
    

    如果要使用 Terraform 创建新集群,然后注册该集群,则还需要将 roles/container.admin 角色绑定到该服务帐号,以便 Terraform 可以使用该服务帐号访问 GKE API,从而创建集群。

    FLEET_HOST_PROJECT_ID=[FLEET_HOST_PROJECT_ID]
    gcloud projects add-iam-policy-binding ${FLEET_HOST_PROJECT_ID} \
     --member="serviceAccount:[SERVICE_ACCOUNT_NAME]@${FLEET_HOST_PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/container.admin"
    

    替换以下内容:

  3. 下载服务帐号的私钥 JSON 文件,如使用 gcloud 创建 Google Cloud 服务帐号中所述。您需要借助此文件来使用 Terraform 创建和注册集群

为 Config Connector 配置服务帐号

如果要使用 Config Connector 注册 GKE 集群,请执行以下操作:

gcloud

  1. 确保已安装 Config Connector 插件。您应该具有高于 1.47.0 的 Config Connector 版本。

  2. 按照 Config Connector 说明创建服务帐号。

  3. gkehub.admin IAM 角色绑定到此服务帐号,以便 Config Connector 可以使用此服务帐号访问 Fleet API:

    FLEET_HOST_PROJECT_ID=[FLEET_HOST_PROJECT_ID]
    gcloud projects add-iam-policy-binding ${FLEET_HOST_PROJECT_ID} \
     --member="serviceAccount:[SERVICE_ACCOUNT_NAME]@${FLEET_HOST_PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/gkehub.admin"
    

    如果您要使用 Config Connector 创建新集群,然后注册该集群,则还需要将 roles/container.admin 角色绑定到服务帐号,以便 Config Connector 控制器可以使用此服务帐号访问 GKE API 以创建集群。

    FLEET_HOST_PROJECT_ID=[FLEET_HOST_PROJECT_ID]
    gcloud projects add-iam-policy-binding ${FLEET_HOST_PROJECT_ID} \
     --member="serviceAccount:[SERVICE_ACCOUNT_NAME]@${FLEET_HOST_PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/container.admin"
    

    替换以下内容:

  4. 按照 Config Connector 说明使用此服务帐号配置 Config Connector。

Google Cloud 外部的集群

除了所有注册的前提条件之外,Google Cloud 以外的所有手动注册(例如注册关联的集群)都需要满足以下要求。

确保网络连接

如需成功注册集群,您需要确保可从 Kubernetes 集群访问以下网域:

  • cloudresourcemanager.googleapis.com 会解析与集群所连接的 Google Cloud 项目有关的元数据。
  • oauth2.googleapis.com 会获取针对 gkeconnect.googleapis.com 的代理 (Agent) 操作的短期 OAuth 令牌。
  • gkeconnect.googleapis.com 会建立用于接收 Google Cloud 请求的渠道并发出响应。
  • gkehub.googleapis.com 会创建与要连接到 Google Cloud 的集群对应的 Google Cloud 端 Fleet 成员资源。
  • www.googleapis.com 会对来自传入的 Google Cloud 服务请求的服务令牌进行身份验证。
  • gcr.io 会拉取 GKE Connect Agent 映像。

如果要使用 Workload Identity 注册集群,则还必须可以访问以下网域:

  • securetoken.googleapis.com
  • iamcredentials.googleapis.com
  • sts.googleapis.com

如果要对 Connect 使用代理,则还必须使用这些相关网域更新代理的许可名单。

如果您使用 gcloud 注册 Kubernetes 集群,则还需要在运行 gcloud 命令的环境中可以访问这些网域。

使用 VPC Service Controls

如果您希望在应用中使用 VPC Service Controls 来提升数据安全性,则需要确保以下服务在服务边界内:

  • Resource Manager API (cloudresourcemanager.googleapis.com)
  • GKE Connect API (gkeconnect.googleapis.com)
  • Fleet API (gkehub.googleapis.com)

如果要注册启用了队列 Workload Identity 的集群,您还需要以下服务:

  • IAM Service Account Credentials API (iamcredentials.googleapis.com)
  • Security Token Service API (sts.googleapis.com)

您还需要设置专用连接,以便访问相关 API。如需了解如何执行此操作,请参阅设置专用连接

设置身份

除 Google Cloud 外的所有手动集群注册选项都要求您向 Google 配置身份验证。您可以选择使用 Workload Identity 集群注册,或使用 Google Cloud 服务帐号注册。

创建集群时,系统会自动向您的项目队列注册 Anthos clusters on VMwareAnthos clusters on Bare MetalAnthos clusters on AWS,并从 1.8 版开始启用队列 Workload Identity。请注意,对于这些集群类型,您仍然需要设置服务帐号进行注册。初次注册后,Connect Agent 会使用队列 Workload Identity 向 Google 进行身份验证。

如果集群满足我们的挂接集群前提条件(如下所述),则可以在启用集群 Workload Identity 的情况下注册关联的集群。否则,请使用 Google Cloud 服务帐号注册关联的集群以进行身份验证。

使用 gcloud 创建 Google Cloud 服务帐号。

如需使用 Google Cloud 服务帐号手动注册集群,您需要一个包含服务帐号凭据的 JSON 文件。为遵循最小权限原则,我们建议您为注册的每个 Kubernetes 集群创建一个不同的服务帐号,并且只将 IAM 角色绑定到相应集群的服务帐号。

如需创建此文件,请执行以下步骤:

gcloud

通过运行以下命令创建服务帐号:

gcloud iam service-accounts create [SERVICE_ACCOUNT_NAME] --project=[FLEET_HOST_PROJECT_ID]

通过运行以下命令来列出项目的所有服务帐号:

gcloud iam service-accounts list --project=[FLEET_HOST_PROJECT_ID]

如果要为您注册的每个 Kubernetes 集群创建一个不同的服务帐号,请使用 IAM Condition,将 gkehub.connect IAM 角色绑定到其对应的集群的服务帐号:

MEMBERSHIP_NAME=[MEMBERSHIP_NAME]
FLEET_HOST_PROJECT_ID=[FLEET_HOST_PROJECT_ID]
SERVICE_ACCOUNT_NAME=[SERVICE_ACCOUNT_NAME]
gcloud projects add-iam-policy-binding ${FLEET_HOST_PROJECT_ID} \
 --member="serviceAccount:${SERVICE_ACCOUNT_NAME}@${FLEET_HOST_PROJECT_ID}.iam.gserviceaccount.com" \
 --role="roles/gkehub.connect" \
 --condition "expression=resource.name == \
'projects/${FLEET_HOST_PROJECT_ID}/locations/global/memberships/${MEMBERSHIP_NAME}',\
title=bind-${SERVICE_ACCOUNT_NAME}-to-${MEMBERSHIP_NAME}"

否则,请将角色绑定到项目中所有无该条件的集群的服务帐号。

FLEET_HOST_PROJECT_ID=[FLEET_HOST_PROJECT_ID]
gcloud projects add-iam-policy-binding ${FLEET_HOST_PROJECT_ID} \
 --member="serviceAccount:[SERVICE_ACCOUNT_NAME]@${FLEET_HOST_PROJECT_ID}.iam.gserviceaccount.com" \
 --role="roles/gkehub.connect"

下载服务帐号的私钥 JSON 文件。您在注册集群时会用到此文件:

FLEET_HOST_PROJECT_ID=[FLEET_HOST_PROJECT_ID]
gcloud iam service-accounts keys create [LOCAL_KEY_PATH] \
  --iam-account=[SERVICE_ACCOUNT_NAME]@${FLEET_HOST_PROJECT_ID}.iam.gserviceaccount.com \
  --project=${FLEET_HOST_PROJECT_ID}

其中:

  • [FLEET_HOST_PROJECT_ID] 是您要在其中注册集群的 Google Cloud 项目 ID。了解如何查找此值
  • [SERVICE_ACCOUNT_NAME] 是您为服务帐号选择的显示名。
  • [MEMBERSHIP_NAME] 是您选择要在注册时唯一表示集群的成员资格名称。
  • [LOCAL_KEY_PATH] 是您要将服务帐号私钥(一个 JSON 文件)保存到的本地文件路径。我们建议您使用服务帐号名称和项目 ID 命名文件,如 /tmp/creds/[SERVICE_ACCOUNT_NAME]-[FLEET_HOST_PROJECT_ID].json

关联集群的前提条件

根据要注册为关联集群的外部集群的类型,您可能需要满足一些额外的要求才能安装 Connect Agent 和/或使用集群 Workload Identity。

配置安全上下文限制 (SCC)(OpenShift 集群)

OpenShift OKEOKD 集群上,管理员可以使用 SCC 控制 pod 的权限。如需允许在集群中安装 Connect Agent,您需要创建自定义 SCC。

以下示例 SCC 定义指定了 Connect Agent 必须满足哪些条件才能加入集群:

# Connect Agent SCC
apiVersion: v1
kind: SecurityContextConstraints
metadata:
  name: gke-connect-scc
allowPrivilegeEscalation: false
# This is redundant with non-root + disallow privilege escalation,
# but we provide it for defense in depth.
requiredDropCapabilities:
- ALL
runAsUser:
  type: MustRunAsNonRoot
seLinuxContext:
  type: RunAsAny
supplementalGroups:
  type: MustRunAs
  ranges:
  - min: 1
    max: 65535
fsGroup:
  type: MustRunAs
  ranges:
  - min: 1
    max: 65535
volumes:
- secret
- projected
readOnlyRootFilesystem: true
seccompProfiles:
- docker/default
users:
groups:
  # Grants all service accounts in the gke-connect namespace access to this SCC
  - system:serviceaccounts:gke-connect

假设您已将 SCC 定义另存为 gke-connect-scc.yaml,请使用 OpenShift oc 命令行工具为您的集群创建 gke-connect-scc SCC,如下所示:

$ oc create -f gke-connect-scc.yaml

要验证是否已创建了自定义 SCC,请运行以下 oc 命令:

$ oc get scc | grep gke-connect-scc

队列 Workload Identity 要求

如果您的平台为您的集群创建了一个公共 OIDC 端点(或允许您创建一个),或者您为集群启用了 Kubernetes 服务帐号颁发者发现,您可以注册启用了队列 Workload Identity 的关联集群。如果您无法满足这些要求,则必须使用 Google Cloud 服务帐号注册关联的集群以进行身份验证。

如需了解特定的集群类型,请参阅以下内容:

  • OpenShift 集群:如上所述,在配置自定义 SCC 后,可以通过启用 Workload Identity 来注册。
  • 种类集群:要求启用服务帐号颁发者发现才能使用队列 Workload Identity。Kubernetes 1.20 版中默认启用此选项。如果您需要启用此功能,请按照服务帐号令牌量投影中的说明操作。启用服务帐号令牌量项目后,系统会自动启用服务帐号颁发者发现功能。
  • EKS 集群:要求集群具有公共 IAM OIDC 身份提供商。按照为您的集群创建 IAM OIDC 提供商中的说明检查提供商是否存在,并在必要时创建提供商。

资源用量和要求

通常,注册时安装的 Connect 代理会使用 500m 的 CPU 和 200Mi 的内存。但是,此使用情况可能因每秒向代理发出的请求数以及这些请求的大小而异。这些可能受到许多因素的影响,包括集群的大小、通过 Cloud Console 访问集群的用户数(用户数和/或工作负载越多,请求次数越多)以及集群上启用队列的功能数量。

后续步骤