使用第三方身份设置 Connect 网关

本指南适用于需要在包含没有 Google 身份且不属于 Google Workspace 的用户的项目中设置 Connect 网关的平台管理员。在本指南中，这些身份称为“第三方身份”。在阅读本指南之前，您应该先熟悉 Connect 网关概览中的概念。如需向个别 Google 账号授权，请参阅设置 Connect 网关。如需获取 Google 群组支持，请参阅使用 Connect 群组设置 Connect 网关。

本指南中的设置允许用户使用 Google Cloud CLI、Connect 网关和 Google Cloud 控制台登录舰队集群。

支持的集群类型

您可以通过 Connect 网关为以下已注册的集群类型使用第三方身份设置访问权限控制：

GKE 集群
Anthos (GKE Enterprise) 1.13 及更高版本的 VMware 和裸金属上的 Google Distributed Cloud（纯软件）
Kubernetes 1.25 版及更高版本的 GKE on AWS 和 GKE on Azure
Anthos (GKE Enterprise) 1.16 版及更高版本的关联集群

如果您需要升级本地集群以使用此功能，请参阅升级 GKE Enterprise Clusters for VMWare 和升级 GKE Enterprise Clusters on Bare Metal。

如果您有上述环境以外的 GKE 集群环境，请联系 Cloud Customer Care 或 Connect 网关团队。

运作方式

如概览中所述，用户使用的身份提供方可能不是 Google Workspace 或 Cloud Identity。通过使用员工身份联合，用户可以使用第三方身份提供方（例如 Okta 或 Azure Active Directory），通过 Connect 网关访问其集群。与 Google 账号不同，第三方用户由具有以下格式的 Identity and Access Management (IAM) 主账号表示：

principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_VALUE

WORKFORCE_POOL_ID 是包含相关第三方身份提供方的员工池的名称。
SUBJECT_VALUE 是第三方身份与 Google 主体的映射。

对于第三方群组，IAM 主账号采用以下格式：

principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP_VALUE

下图显示了第三方用户向启用该服务的集群进行身份验证并对其运行命令的典型流程。为了成功执行此流程，需要为用户或群组在集群上应用基于角色的访问控制 (RBAC) 政策。

对于单个用户，集群上必须存在使用该用户的完整 IAM 主账号名称的 RBAC 政策。

如果使用群组功能，集群上必须存在使用群组的完整 IAM 主账号名称的 RBAC 政策，该群组必须：

包含用户 alice@example.com 作为成员。
包含在 Alice 的 Google Cloud 组织中的员工池中的身份提供方映射中。

显示网关第三方身份流程的示意图

用户 alice@example.com 使用第三方基于浏览器的登录功能以第三方身份登录 gcloud。为了从命令行使用集群，用户会获取集群的网关 kubeconfig，如使用 Connect 网关中所述。
用户运行 kubectl 命令或在 Google Cloud 控制台中打开 Google Kubernetes Engine 工作负载或对象浏览器页面来发送请求。
Connect 网关接收请求，并使用员工身份联合来处理第三方身份验证。
Connect 网关使用 IAM 执行授权检查。
Connect 服务会将请求转发到集群上运行的 Connect Agent。请求中随附了用户的凭据信息，可在集群上进行身份验证和授权。
Connect Agent 将请求转发到 Kubernetes API 服务器。
Kubernetes API 服务器将请求转发给 GKE Identity Service，后者验证请求。
GKE Identity Service 将第三方用户和群组信息返回到 Kubernetes API 服务器。然后，Kubernetes API 服务器可以根据集群中已配置的 RBAC 政策，使用这些信息对请求进行授权。

准备工作

确保您已安装以下命令行工具：
- 最新版本的 Google Cloud CLI，它是用于与 Google Cloud 交互的命令行工具。
- Kubernetes 命令行工具 kubectl，用于与集群进行交互。
如果您使用 Cloud Shell 作为与 Google Cloud 交互的 Shell 环境，则系统会为您安装这些工具。
确保您已初始化用于您项目的 gcloud CLI。
本指南假设您在项目中具有 roles/owner。如果您不是项目所有者，则可能还需要其他权限才能执行部分设置步骤。
对于 Google Cloud 之外的集群，GKE Identity Service 需要从您的集群中调用 Google API 才能完成身份验证。请检查您的网络政策是否要求出站流量通过代理。

使用 Workforce Identity 设置第三方身份属性映射

确保按照与您的身份提供方对应的说明，为您的 Google Cloud 组织设置员工池和身份提供方：

启用 API

如需将网关添加到您的项目中，请启用 Connect 网关 API 及其必需的依赖项 API。如果您的用户只想使用 Google Cloud 控制台对集群进行身份验证，则无需启用 connectgateway.googleapis.com，但需要启用其余的 API。

gcloud services enable --project=PROJECT_ID  \
connectgateway.googleapis.com \
anthos.googleapis.com \
gkeconnect.googleapis.com \
gkehub.googleapis.com \
cloudresourcemanager.googleapis.com

设置 GKE Identity Service

Connect 网关的第三方身份支持功能使用 GKE Identity Service 从 Google 获取群组成员资格信息。您可以在 GKE Identity Service 简介中详细了解 GKE Identity Service。

如果您将 GKE 集群与网关结合使用，则不需要设置 GKE Identity Service 即可使用第三方身份支持功能。请改为按照为 RBAC 配置 Google 群组中的说明操作，然后继续授予 IAM 角色，以授予通过网关访问集群的权限。

如果您将关联的 GKE 集群与网关结合使用，则无需使用 GKE Identity Service 即可获得第三方身份支持。按照您所选集群类型的说明设置第三方身份支持：

确保已安装 GKE Identity Service

从 1.7 版开始，GKE 集群默认安装 GKE Identity Service（但第三方身份支持需要 1.13 版或更高版本）。您可以通过运行以下命令来确认其是否已正确安装到您的集群上：

kubectl --kubeconfig CLUSTER_KUBECONFIG get all -n anthos-identity-service

将 CLUSTER_KUBECONFIG 替换为集群的 kubeconfig 的路径。

为群组配置第三方身份支持

如果您的集群或舰队已配置为支持 Google 群组，则无需执行其他步骤，并且您可以跳到向第三方用户和群组授予 IAM 角色。

如果您使用的是 Google Distributed Cloud on VMware 或 Google Distributed Cloud on Bare Metal，则您设置 GKE Identity Service 的方式决定了您需要如何配置第三方群组功能。

如果您是首次使用 GKE Identity Service，可以选择使用 Fleet API（推荐）或使用 kubectl 来配置第三方群组支持。

如果您不是 GKE Identity Service 的新用户，请注意以下事项：

如果您已经在舰队级层为其他身份提供方设置 GKE Identity Service，则第三方群组功能默认处于启用状态。如需了解详情以及您可能需要进行的任何其他设置，请参阅下面的舰队部分。
如果您已按集群为其他身份提供方设置 GKE Identity Service，请参阅下面的“Kubectl”部分，了解如何更新第三方群组功能的配置。Kubectl

舰队

您可以使用 Google Cloud 控制台或命令行通过 Fleet Feature API 配置对第三方群组的访问权限。

控制台

如果您之前没有为舰队设置 GKE Identity Service，请按照为 GKE Identity Service 配置集群中的说明操作。

选择集群并更新配置

在 Google Cloud 控制台中，前往 Feature Manager 页面。

前往 Feature Manager
点击 Identity Service 面板中的详细信息。此时将显示您项目的集群详细信息。
点击更新 Identity Service以打开设置窗格。
选择要配置的集群。您可以选择单个集群，也可以指定所有集群都使用相同的身份配置。
在配置身份提供方部分中，您可以选择保留、添加、更新或移除身份提供方。
点击继续以进行下一个配置步骤。如果您为此设置选择了至少一个符合条件的集群，则此时会显示 Google 身份验证部分。
选择启用，为所选集群启用 Google 身份验证。如果您需要通过代理访问 Google 身份提供方，请输入代理详细信息。
点击更新配置。这会将身份配置应用于所选集群。

gcloud

如果您之前没有为舰队设置 GKE Identity Service，请按照为 GKE Identity Service 配置集群中的说明操作。在您的 auth-config.yaml 文件中仅指定以下配置：

spec:
  authentication:
  - name: google-authentication-method
    google:
      disable: false

使用代理配置第三方群组访问权限

如果您需要通过代理访问身份提供方，请在 auth-config.yaml 文件中使用 proxy 字段。例如，如果您的集群位于专用网络中并且需要连接到公共身份提供方，则可能需要设置此字段。即使您已为其他提供方配置了 GKE Identity Service，也必须添加此配置。

如需配置 proxy，以下是更新现有配置文件 auth-config.yaml 的 authentication 部分的方法。

  spec:
    authentication:
    - name: authentication-method
      google:
        disable: false
      proxy: PROXY_URL

其中

disable（可选）表示选择启用或停用集群的第三方群组功能。默认情况下，此值设置为 false。false如果您想停用此功能，可以将其设置为 true。true
PROXY_URL（可选）是连接到 Google 身份的代理服务器地址。例如 http://user:password@10.10.10.10:8888

应用配置

如需将配置应用于集群，请运行以下命令：

gcloud container fleet identity-service apply \
--membership=CLUSTER_NAME \
--config=/path/to/auth-config.yaml

其中

CLUSTER_NAME 是集群在舰队内的唯一成员资格名称。

应用此配置后，其将由 GKE Identity Service 控制器管理。对 GKE Identity Service 客户端配置所做的任何本地更改都会由控制器协调回此设置中指定的配置。

Kubectl

如需将集群配置为使用 GKE Identity Service 和第三方群组功能，您需要更新集群的 GKE Identity Service ClientConfig。这是用于集群配置的 Kubernetes 自定义资源类型 (CRD)。每个 GKE Enterprise 集群在 kube-public 命名空间中都有一个名为 default 的 ClientConfig 资源，您可以使用配置详细信息更新该资源。

如需修改配置，请使用以下命令。

kubectl --kubeconfig CLUSTER_KUBECONFIG -n kube-public edit clientconfig default

如果 kubeconfig 中有多个上下文，则会使用当前上下文。运行该命令之前，您可能需要将当前上下文重置为正确的集群。

以下示例展示了如何使用配置类型为 google 的新身份验证方法更新 ClientConfig，以启用第三方群组功能。如果 internalServer 字段为空，请确保将其设置为 https://kubernetes.default.svc，如下所示。

spec:
  authentication:
  - google:
      audiences:
      - "CLUSTER_IDENTIFIER"
    name: google-authentication-method
    proxy: PROXY_URL
  internalServer: https://kubernetes.default.svc

其中

CLUSTER_IDENTIFIER（必需）表示集群的成员资格详细信息。您可以使用以下命令检索集群的成员资格详细信息：

kubectl --kubeconfig CLUSTER_KUBECONFIG get memberships membership -o yaml

其中

CLUSTER_KUBECONFIG 是集群的 kubeconfig 文件的路径。在响应中，请查看 spec.owner.id 字段以检索集群的成员资格详细信息。

以下示例响应显示了集群的成员资格详细信息：

id: //gkehub.googleapis.com/projects/123456789/locations/global/memberships/xy-ab12cd34ef

对应于以下格式：//gkehub.googleapis.com/projects/PROJECT_NUMBER/locations/global/memberships/MEMBERSHIP

向第三方用户和群组授予 IAM 角色

第三方身份需要以下额外的 Google Cloud 角色才能通过网关与连接的集群进行交互：

roles/gkehub.gatewayAdmin。此角色允许用户访问 Connect 网关 API。
- 如果用户只需要所连接集群的只读权限，则可以改用 roles/gkehub.gatewayReader。
- 如果用户需要所连接集群的读写权限，则可以改用 roles/gkehub.gatewayEditor。
roles/gkehub.viewer。此角色允许用户查看已注册的集群成员资格。

以下代码展示了如何向各个身份和映射群组添加必要的角色：

单个身份

如需向项目 PROJECT_ID 的单个身份授予必要的角色，请运行以下命令：

gcloud projects add-iam-policy-binding PROJECT_ID \
    --role=GATEWAY_ROLE \
    --member="principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_VALUE"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --role=roles/gkehub.viewer \
    --member="principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_VALUE"

其中

PROJECT_ID 是项目的 ID。
GATEWAY_ROLE 是 roles/gkehub.gatewayAdmin、roles/gkehub.gatewayReader 或 gkehub.gatewayEditor 中的一个。
WORKFORCE_POOL_ID 是员工身份池 ID。
SUBJECT_VALUE 是用户身份。

群组

如需向项目 PROJECT_ID 的特定群组中的所有身份授予必要的角色，请运行以下命令：

gcloud projects add-iam-policy-binding PROJECT_ID \
    --role=GATEWAY_ROLE \
    --member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP_ID"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --role=roles/gkehub.viewer \
    --member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP_ID"

其中

PROJECT_ID 是项目的 ID。
GATEWAY_ROLE 是 roles/gkehub.gatewayAdmin、roles/gkehub.gatewayReader 或 gkehub.gatewayEditor 中的一个。
WORKFORCE_POOL_ID 是员工池 ID。
GROUP_ID 是映射的 google.groups 声明中的群组。

在应用 RBAC 政策时，请参阅使用 Workforce Identity 设置第三方映射中针对您的身份提供方列出的设置，以了解更多自定义项（例如指定部门属性）。

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

配置基于角色的访问权限控制 (RBAC) 政策

最后，每个集群的 Kubernetes API 服务器必须能够对来自指定第三方用户和群组且通过网关的 kubectl 命令授权。对于每个集群，您需要添加 RBAC 权限政策，用于指定主体对集群拥有哪些权限。

RBAC 政策中的主体必须使用与 IAM 绑定相同的格式，第三方用户以 principal://iam.googleapis.com/ 开头，第三方群组以 principalSet://iam.googleapis.com/ 开头。如果没有为集群配置 GKE Identity Service，则除了第三方用户的角色/集群角色之外，您还需要模拟政策。在这种情况下，请按照这些 RBAC 设置步骤操作，添加以 principal://iam.googleapis.com/ 开头的第三方主账号作为用户。

以下示例展示了如何向第三方群组的成员授予配置了 GKE Identity Service 的集群的 cluster-admin 权限。然后，您可以将政策文件另存为 /tmp/admin-permission.yaml，并将其应用于与当前上下文关联的集群。

cat <<EOF > /tmp/admin-permission.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: gateway-cluster-admin-group
subjects:
- kind: Group
  name: "principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP"
roleRef:
  kind: ClusterRole
  name: cluster-admin
  apiGroup: rbac.authorization.k8s.io
EOF
# Apply permission policy to the cluster.
kubectl apply --kubeconfig=KUBECONFIG_PATH -f /tmp/admin-permission.yaml

如需详细了解如何指定 RBAC 权限，请参阅使用 RBAC 授权。

后续步骤

了解如何使用 Connect 网关通过命令行连接到集群。
如需了解如何将 Connect 网关用作 DevOps 自动化的一部分的示例，请参阅与 Cloud Build 集成教程。