在舰队级层配置 GKE Identity Service

本文档适用于在集群上设置 GKE Identity Service 的集群管理员或应用运维人员。本文档介绍如何使用您偏好的 OpenID Connect (OIDC) 身份提供方在集群上的舰队级层设置 GKE Identity Service。本文档中的说明假定 GKE Identity Service 已作为客户端应用向您的身份提供商注册。

如需详细了解 GKE Identity Service 和其他设置选项，请参阅概览。如需了解如何以开发者或其他集群用户身份使用此服务访问集群，请参阅使用 GKE Identity Service 访问集群。

准备工作

  • 在开始设置之前，请确保您的平台管理员已为您提供为 GKE Identity Service 配置 OIDC 提供商中的所有必要信息，包括 GKE Identity Service 的客户端 ID 和 Secret。
  • 确保要配置的集群符合舰队级级设置的前提条件。如需了解其他集群类型和环境，请参阅 GKE Identity Service 概览。

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

    • 最新版本的 Google Cloud CLI，其中包含用于与 Google Cloud 交互的命令行工具 gcloud。如果您需要安装 Google Cloud CLI，请参阅安装指南。
    • kubectl，用于对 Kubernetes 集群运行命令。如果您需要安装 kubectl，请参阅安装指南。

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

  • 确保您已初始化要用于在其中注册集群的项目的 gcloud CLI。

  • 如果您不是项目所有者，则您需要具有在其中注册集群的项目的 GKE Hub Admin 角色才能完成配置步骤。

启用 API

控制台

确保已选择集群所注册的项目。

  • Enable the GKE Hub and Kubernetes Engine APIs.

    Enable the APIs

gcloud

运行以下命令启用设置所需的 API： 

gcloud services enable 

gkehub.googleapis.com 

container.googleapis.com

配置集群

如需将集群配置为使用您选择的提供方，GKE Identity Service 需要您指定有关身份提供方的详细信息、为用户识别提供的 JWT 令牌的信息，以及作为客户端应用注册 GKE Identity Service 时提供的其他信息。

例如，如果您的提供方使用以下字段（以及其他字段）创建身份令牌，其中 iss 是身份提供方 URI，sub 用于标识用户，groupList 用于列出用户所属的安全群组：

{
  'iss': 'https://server.example.com'
  'sub': 'u98523-4509823'
  'groupList': ['developers@example.corp', 'us-east1-cluster-admins@example.corp']
  ...
}

...则您的配置将具有以下相应的字段：

issueruri: 'https://server.example.com'
username: 'sub'
group: 'groupList'
...

您的平台管理员或组织中管理身份的人员应为您提供创建配置所需的大部分信息。 如需查看一些常用身份提供方的配置示例，请参阅提供方专用配置。

借助 GKE Identity Service，您可以通过 Google Cloud 控制台或使用 Google Cloud CLI 创建或更新和应用此配置。

控制台

启用 GKE Identity Service

  1. 在 Google Cloud 控制台中，转到 GKE Enterprise 的功能页面。

    转到 GKE Enterprise 功能

  2. 在功能表中，点击 Identity Service 行中的启用，然后在显示的窗格中再次点击启用。这将创建一个新的 GKE Identity Service 控制器实例，以管理舰队集群中 GKE Identity Service 的生命周期。

选择集群

  1. 返回功能表，点击 Identity Service 行中的详细信息，打开服务的详细信息窗格。此时会显示项目的集群及其舰队级 GKE Identity Service 状态。
  2. 点击更新 Identity Service以打开设置窗格。
  3. 选择要配置的集群。只能选择受支持的集群类型。您可以选择单个集群，也可以指定所有集群都使用相同的身份配置。
  4. 在身份提供方下拉列表中，选择您要如何配置集群。如果集群已有 GKE Identity Service 配置，则可以选择对其进行更新。如果现有的已注册集群具有您要使用的 GKE Identity Service 配置，则可以选择将该配置复制到所选的集群。如需创建全新的配置，请按照所选提供方的相关说明进行操作（请参见下一部分）。

设置提供方详细信息

您需要添加的提供方详细信息取决于您要在配置中使用的身份提供方类型。

OIDC

  1. 选择新建 Open ID Connect，以创建新的 OIDC 配置。
  2. 在提供商名称字段中指定要用于识别此配置的名称，通常是身份提供商名称。此名称必须以字母开头，后面最多可跟 39 个小写字母、数字或连字符，但不能以连字符结尾。创建配置后，您将无法修改此名称。
  3. 在客户端 ID 字段中指定向您的提供商注册 GKE Identity Service 时返回的客户端 ID。
  4. 在客户端密钥字段中指定客户端应用和身份提供商之间必须共享的客户端密钥。
  5. 在颁发者网址字段中，指定用于向您的身份提供商发出授权请求的 URI。
  6. 点击下一步以设置 OIDC 特性。

Azure AD

  1. 选择新建 Azure Active Directory，以创建新的 Azure AD 配置。
  2. 在提供商名称字段中指定要用于识别此配置的名称，通常是身份提供商名称。此名称必须以字母开头，后面最多可跟 39 个小写字母、数字或连字符，但不能以连字符结尾。创建配置后，您将无法修改此名称。
  3. 在客户端 ID 字段中指定向您的提供商注册 GKE Identity Service 时返回的客户端 ID。
  4. 在客户端密钥字段中指定客户端应用和身份提供商之间必须共享的客户端密钥。
  5. 在租户中指定租户，即要进行身份验证的 Azure AD 账号。
  6. 点击下一步以设置 Azure AD 特性。

设置特性

您需要添加的特性取决于您的身份提供方，以及您的平台管理员在为 GKE Identity Service 配置提供方时选择的设置选项。

OIDC

  • 填写配置特性：

    • kubectl 重定向 URI：gcloud CLI 使用的重定向网址和端口，由平台管理员在注册时指定，通常采用 http://localhost:PORT/callback 形式。
    • 证书授权机构（可选）：如果平台管理员提供，则该参数为身份提供商的 PEM 编码证书字符串。
    • 群组声明（可选）：提供商用于返回账号的安全群组的 JWT 声明（字段名称）。
    • 群组前缀（可选）：如果您有多个身份提供商的配置（通常是提供商名称），则该参数为您要附加到安全群组名称的前缀，以避免与访问权限控制规则中的现有名称冲突。
    • 代理（可选）：用于连接到身份提供商的代理服务器地址（如适用）。例如，如果您的集群位于专用网络中并且需要连接到公共身份提供商，则可能需要设置此参数。例如：http://user:password@10.10.10.10:8888。
    • 范围（可选）：身份提供商所需的任何其他范围。Microsoft Azure 和 Okta 需要 offline_access 范围。 如有必要，请点击添加范围以添加更多范围。
    • 用户声明（可选）：您的提供商用于标识账号的 JWT 声明（字段名称）。如果您未在此处指定值，GKE Identity Service 会使用“sub”，这是许多提供商使用的用户 ID 声明。您可以选择其他声明，例如“电子邮件”或“名称”，具体取决于 OpenID 提供方。“电子邮件”以外的声明会以颁发者网址作为前缀，以防止命名冲突。
    • 用户前缀（可选）：如果您不想使用默认前缀，则该参数为您要附加到用户声明的前缀，以防止与现有名称冲突。
    • 额外参数（可选）：配置所需的任何额外参数，指定为参数 Key 和 Value。如果需要，请点击添加参数添加更多参数。
    • 启用访问令牌（可选）：如果启用，则允许为 OIDC 提供方（例如 Okta）提供群组支持。
    • 部署 Google Cloud 控制台代理（可选）：如果启用了此代理，则进行部署，以允许 Google Cloud 控制台连接到无法通过互联网公开访问的本地身份提供商。

Azure AD

填写配置特性：

  • kubectl 重定向 URI：gcloud CLI 使用的重定向网址和端口，由平台管理员在注册时指定，通常采用 http://localhost:PORT/callback 形式。
  • 用户声明（可选）：您的提供商用于标识账号的 JWT 声明（字段名称）。如果您未在此处指定值，则 GKE Identity Service 会依次使用“email”“preferred_username”或“sub”的值，以获取用户详细信息。
  • 代理（可选）：用于连接到身份提供商的代理服务器地址（如适用）。例如，如果您的集群位于专用网络中并且需要连接到公共身份提供商，则可能需要设置此参数。例如：http://user:password@10.10.10.10:8888。

添加身份提供商

如果您想要为队列配置其他身份提供方，则可以选择在此处添加提供方。按照相关步骤指定其他身份提供方。

更新配置

点击更新配置。这会在必要时安装 GKE Identity Service（仅限 EKS 集群，GKE 集群默认已安装 GKE Identity Service），并在所选集群上应用客户端配置。

gcloud

创建配置文件

GKE Identity Service 使用名为 ClientConfig 的 Kubernetes 自定义资源 (CRD) 进行集群配置，其中包含 GKE Identity Service 与身份提供方交互所需的全部信息对应的字段。使用您的配置创建名为 auth-config.yaml 的文件，如下所示。

下面的文件对 oidc 配置和 azuread 配置都进行了展示。如需详细了解何时使用 oidc 或 azuread，请参阅提供方专用配置。

  apiVersion: authentication.gke.io/v2alpha1
  kind: ClientConfig
  metadata:
    name: default
    namespace: kube-public
  spec:
    authentication:
    - name: NAME
      proxy: PROXY_URL
      oidc:
        certificateAuthorityData: CERTIFICATE_STRING
        clientID: CLIENT_ID
        clientSecret: CLIENT_SECRET
        deployCloudConsoleProxy: PROXY_BOOLEAN
        extraParams: EXTRA_PARAMS
        groupsClaim: GROUPS_CLAIM
        groupPrefix: GROUP_PREFIX
        issuerURI: ISSUER_URI
        kubectlRedirectURI: http://localhost:PORT/callback
        scopes: SCOPES
        userClaim: USER_CLAIM
        userPrefix: USER_PREFIX

    - name: NAME
      proxy: PROXY_URL
      azureAD:
        clientID: CLIENT_ID
        clientSecret: CLIENT_SECRET
        tenant: TENANT_UUID
        kubectlRedirectURI: http://localhost:PORT/callback
        userClaim: USER_CLAIM

如果您配置了多个身份提供商，则可以使用与上述格式相同的格式，在 authentication 锚标记下的 auth-config.yaml 文件中列出多个身份验证配置。

下表介绍了 ClientConfig 中的 oidc 和 azuread 对象的各个字段。大部分字段是可选的。您需要添加的字段取决于您的身份提供方，以及您的平台管理员在为 GKE Identity Service 配置提供方时选择的设置选项。

字段 必填 说明 格式
name 是 您要用于标识此配置的名称，通常是身份提供方名称。配置名称必须以字母开头，后面最多可跟 39 个小写字母、数字或连字符，但不能以连字符结尾。 字符串
certificateAuthorityData 否 如果平台管理员提供，则该字段为身份提供方的 PEM 编码证书字符串。将生成的字符串作为单独的一行添加到 certificateAuthorityData 中。 字符串
clientID 是 向您的提供方注册 GKE Identity Service 时返回的客户端标识符。 字符串
clientSecret 是 向您的提供商注册 GKE Identity Service 时返回的客户端密钥。 字符串
deployCloudConsoleProxy 否 指定是否部署一个代理，该代理允许 Google Cloud 控制台连接到无法通过互联网公开访问的本地身份提供方。默认情况下，该值设置为 false。 布尔值
extraParams 否 要发送到身份提供方的其他键值对参数，以逗号分隔列表的形式指定，例如“prompt=consent,access_type=offline”。 英文逗号分隔列表
enableAccessToken 否 启用后，当用户从命令行登录时，GKE Identity Service 可以使用身份提供方的 userinfo 端点获取群组信息。如果您的提供方（例如 Okta）提供来自此端点的群组声明，您便可以使用安全群组进行授权。如果未设置，则视为 false。 布尔值
groupsClaim 否 您的提供方用于返回账号的安全群组的 JWT 声明（字段名称）。 字符串
groupPrefix 否 如果您有多个身份提供方的配置（通常是提供方名称），则该字段为您要附加到安全群组名称的前缀，以避免与访问权限控制规则中的现有名称冲突。 字符串
issuerURI 有 用于向您的身份提供方发出授权请求的 URI。URI 必须使用 HTTPS。 网址字符串
kubectlRedirectURI 有 gcloud CLI 使用的重定向网址和端口，由平台管理员在注册时指定，通常采用 `http://localhost:PORT/callback` 形式。 网址字符串
scopes 是 要发送到 OpenID 提供方的其他范围。例如，Microsoft Azure 和 Okta 需要 offline_access 范围。 英文逗号分隔列表
userClaim 否

OIDC：您的提供方用于识别用户账号的 JWT 声明（字段名称）。如果您未在此处指定值，GKE Identity Service 会使用“sub”，这是许多提供方使用的用户 ID 声明。您可以选择其他声明，例如“电子邮件”或“名称”，具体取决于 OpenID 提供方。“电子邮件”以外的声明会以颁发者网址作为前缀，以防止命名冲突。

AzureAD：您的提供方用于识别账号的 JWT 声明（字段名称）。如果您未在此处指定值，则 GKE Identity Service 会依次使用“email”“preferred_username”或“sub”的值，以获取用户详细信息。

 字符串
userPrefix 否 如果您不想使用默认前缀，则该字段为您要附加到用户声明的前缀，以防止与现有名称冲突。 字符串
租户 是 要进行身份验证的 Azure AD 账号的种类。支持的值为租户 ID，或属于特定租户的账号的租户名称。租户名称也称为主域名。如需详细了解如何查找这些值，请参阅查找 Microsoft Azure AD 租户 ID 和主域名。 字符串
proxy 否 用于连接到身份提供方的代理服务器地址（如适用）。例如，如果您的集群位于专用网络中并且需要连接到公共身份提供方，则可能需要设置此字段。例如：http://user:password@10.10.10.10:8888。 字符串

启用 GKE Identity Service

您还可以使用舰队级默认配置启用 GKE Identity Service。使用此设置时，您指定的配置会自动应用于注册到舰队的每个新集群。如需详细了解舰队级默认配置，请参阅配置舰队级默认设置。

如需为您的项目启用 GKE Identity Service，请运行以下命令： 

gcloud container fleet identity-service enable

这将创建一个新的 GKE Identity Service 控制器实例，以管理舰队集群中 GKE Identity Service 的生命周期。 您只需为每个项目运行一次此命令，即可使用 GKE Identity Service 并将所有受支持的集群注册到您的项目舰队。

将配置应用于集群

如需在必要时安装 GKE Identity Service（仅限 EKS 集群，GKE 集群默认已安装 GKE Identity Service），并将配置应用于集群，请运行以下命令：

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

其中 CLUSTER_NAME 是集群在舰队内的唯一名称。

应用集群配置后，此配置由 GKE Identity Service 控制器管理，并被视为“可靠来源”。对 GKE Identity Service 客户端配置所做的任何本地更改都会由控制器协调回此设置中指定的配置。

请注意，如果您的集群已有针对任何身份验证选项的配置（例如 LDAP 配置），则以下情况适用：

  • 如果您已有 OIDC 提供商的现有集群级层配置，则对集群应用舰队级 GKE Identity Service 控制措施将覆盖所有现有身份验证规范。
  • 如果舰队级配置（例如 LDAP）不支持提供商的现有集群级配置，则此设置将失败。您必须移除现有的提供商配置才能应用舰队级配置。

如果您不再希望 Anthos Identity Service 控制器管理您的配置（例如，如果您想要使用其他身份验证选项），则可以按照停用 GKE Identity Service 管理中的说明停用此功能。

特定于提供方的配置

本部分为 OIDC 提供方（例如 Azure AD 和 Okta）提供配置指南，包括示例配置，您可以复制该示例配置并使用自己的详细信息进行修改。

Azure AD

这是使用 Azure AD 设置 GKE Identity Service 的默认配置。通过使用此配置，GKE Identity Service 可以从 Azure AD 获取用户和群组信息，此外，您可以根据群组设置 Kubernetes 基于角色的访问权限控制 (RBAC)。不过，如果使用此配置，对于每位用户，您最多只能检索大约 200 个群组。

如果对于每位用户，您需要检索 200 个以上的群组，请参阅 Azure AD（高级）部分的说明。

...
spec:
  authentication:
  - name: oidc-azuread
    oidc:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      extraParams: prompt=consent, access_type=offline
      issuerURI: https://login.microsoftonline.com/TENANT_ID/v2.0
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: openid,email,offline_access
      userClaim: email

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

Azure AD（高级）

通过 Azure AD 的此可选配置，GKE Identity Service 可以使用 Microsoft Graph API 检索用户和群组信息，并且对于可针对每位用户检索的群组数量，没有任何限制。如需了解支持此配置的平台，请参阅 Azure AD 的高级设置。

如果需要针对每位用户检索的群组数量少于 200 个，则建议您使用默认配置，即在您的 ClientConfig 中使用一个 oidc 锚标记。如需了解详情，请参阅 Azure AD 的相关说明。

示例配置中的所有字段都是必填字段。

...
spec:
  authentication:
  - name: azure
    azureAD:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      tenant: TENANT_UUID
      kubectlRedirectURI: http://localhost:PORT/callback
      groupFormat: GROUP_FORMAT
      userClaim: USER_CLAIM

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

将 GROUP_FORMAT 替换为您要用于检索群组信息的格式。此字段可以接受与用户群组的 ID 或 NAME 相对应的值。此设置目前适用于 GKE on VMware 集群和 Google Distributed Cloud Virtual for Bare Metal 集群。

Okta

下面向您展示了如何使用用户和群组设置身份验证，并将 Okta 作为您的身份提供方。此配置允许 Anthos Identity Service 使用访问令牌和 Okta 的 userinfo 端点检索用户和群组声明。

...
spec:
  authentication:
  - name: okta
    oidc:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      enableAccessToken: true
      extraParams: prompt=consent
      groupsClaim: groups
      issuerURI: https://OKTA_ISSUER_URI/
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: offline_access,email,profile,groups
      userClaim: email

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

配置舰队级默认设置

您可以使用舰队级默认配置来启用 GKE Identity Service。使用此设置时，在创建集群期间注册的每个新的 GKE on Google Cloud 集群或 Anthos 集群都会在具有您指定的配置的集群上启用 GKE Identity Service。如需详细了解如何管理舰队级配置，请参阅管理舰队级功能。

如需使用舰队级默认配置来配置 GKE Identity Service，请执行以下操作：

  1. 创建一个名为 fleet-default.yaml 的文件，然后按照创建配置文件进行填充

  2. 使用舰队级默认配置启用 GKE Identity Service：

    gcloud container fleet identity-service enable --fleet-default-member-config=fleet-default.yaml

  3. 如需修改现有舰队级默认配置，或者已在不使用舰队级默认配置的情况下在舰队中启用了 GKE Identity Service 时添加一个舰队级默认配置，请运行以下命令：

    gcloud container fleet identity-service apply --fleet-default-member-config=default-config.yaml

  4. 在配置舰队级默认配置之前注册的集群不会自动继承默认配置。如果您希望将默认配置应用于属于此类集群的集群，请运行以下命令：

    gcloud container fleet identity-service apply --origin=fleet --membership=CLUSTER_NAME

  5. 如需移除舰队级默认配置，请运行以下命令：

    gcloud container fleet identity-service delete --fleet-default-member-config

验证身份服务配置

完成舰队级设置后，您可以验证舰队中的集群是否已成功配置了您指定的身份服务配置。

控制台

  1. 在 Google Cloud 控制台中，打开 GKE Enterprise 功能页面。

    转到 GKE Enterprise 功能管理

    所有已启用的功能在功能列表中显示为已启用。

  2. 在 Identity Service 功能中点击详细信息。详细信息面板会显示已注册集群的状态。

gcloud

运行以下命令：

gcloud container fleet identity-service describe

设置用户访问权限

配置集群后，请继续设置用户访问权限。

停用舰队级 GKE Identity Service 管理

如果您不希望 Google Cloud 继续管理您的 GKE Identity Service 配置和生命周期，则可以停用此功能。停用舰队级管理不会从集群中移除 GKE Identity Service 或您的身份验证配置，因此用户仍然可以使用配置的第三方身份提供商向集群进行身份验证。但是，如果您在集群上对 GKE Identity Service 配置或资源进行本地手动修改，则这些更改不再会协调为“单一可靠来源”所需状态。

为集群停用舰队级管理

如需为集群停用舰队级管理，请运行以下命令：

gcloud container fleet identity-service delete --membership=CLUSTER_NAME

其中 CLUSTER_NAME 是集群在舰队内的唯一名称。

为舰队停用舰队级管理

执行以下操作可为舰队停用舰队级 GKE Identity Service 管理。

控制台

  1. 在 Google Cloud 控制台中，打开 GKE Enterprise 功能页面。

    打开 GKE Enterprise 功能

  2. 在功能表中，点击 Identity Service 行中的详细信息，然后在显示的窗格中再次点击停用 GKE Identity Service。

gcloud

运行以下命令：

gcloud container fleet identity-service disable

为您的舰队停用此功能后，您将无法再在 Google Cloud 控制台中或通过使用 gcloud 查看或更新任何集群的 GKE Identity Service 状态。

问题排查

如果您在此设置过程中遇到问题，请参阅我们的问题排查指南。