GKE Identity Service 诊断实用程序

GKE Identity Service 诊断实用程序可帮助您排查基于 FQDN 的身份验证问题。如果您在使用特定 OIDC 提供方向集群进行身份验证时遇到困难，可以启用该工具，并通过它模拟使用 OIDC 提供方的登录流程，以便快速找出配置问题。

诊断实用程序仅在运行 GKE Enterprise 1.32 或更高版本的独立集群上可用，并且仅支持 OIDC。

启用诊断实用程序

诊断实用程序默认处于停用状态，您必须先启用它，然后才能使用它排查问题。如需启用它，请按照以下说明操作：

打开 ClientConfig 自定义资源进行修改：

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

清单应类似于以下内容：

apiVersion: authentication.gke.io/v2alpha1
kind: ClientConfig
metadata:
  name: default
  namespace: kube-public
spec:
  authentication:
  - name: oidc
    oidc:
      clientID: example-client-id
      clientSecret: example-client-secret
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      extraParams: prompt=consent, access_type=offline
      issuerURI: https://example.com
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: openid,email,offline_access
      userClaim: email

如以下示例所示，在 ClientConfig 清单中添加 identityServiceOptions 部分，以指定诊断实用程序配置：

apiVersion: authentication.gke.io/v2alpha1
  kind: ClientConfig
  metadata:
    name: default
    namespace: kube-public
  spec:
    identityServiceOptions:
      diagnosticInterface:
        enabled: true
        expirationTime: TIMESTAMP
    authentication:
    - name: oidc
      oidc:
        clientID: example-client-id
        clientSecret: example-client-secret
        cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
        extraParams: prompt=consent, access_type=offline
        issuerURI: https://example.com
        kubectlRedirectURI: http://localhost:PORT/callback
        scopes: openid,email,offline_access
        userClaim: email

将 TIMESTAMP 替换为采用 RFC 3339 格式的到期时间。例如 2025-05-01T17:05:00Z。到期时间决定了诊断实用程序功能何时自动关闭。由于任何具有集群访问权限的用户都可以使用诊断实用程序，因此适当设置到期时间有助于确保该实用程序保持启用状态的时间不会超出必要期限。设置到期时间时，建议将其设置为未来 12 小时，不过未来任何时间都是有效的。

保存更改并退出文本编辑器，以将清单应用于集群。

启用诊断实用程序后，您可以模拟登录事件并获取相应的诊断信息，以便用于排查特定提供方的问题。

在浏览器中前往以下网址以打开诊断页面：
```
APISERVER-URL/diagnose
```
将 APISERVER_URL 替换为集群的完全限定域名 (FQDN)。例如 https://apiserver.example.com。

诊断页面会显示为集群配置的 OIDC 提供方的列表。
选择要进行问题排查的提供方。
像往常一样登录。

在登录过程结束时，实用程序会显示一个页面，其中包含可帮助您进行问题排查的诊断信息。

使用诊断页面排查登录问题

诊断页面会提供身份验证摘要，该摘要分为三个部分：

状态：包含 Success 或 Failed，具体取决于身份验证是否成功。
身份提供方：包含有关用于登录的提供方的详细信息，例如 Name、Client ID 和 UserClaim。
ID 令牌：包含有关 GKE Identity Service 使用给定提供方提取的 ID 令牌的信息。ID 令牌是包含一组键值对的 JSON 对象。键可能包括 iss、aud、sub 和 email。

排查身份验证成功问题

如果状态部分的内容表明身份验证已成功，但您仍然遇到问题，则原因可能是缺少基于角色的访问控制 (RBAC)。如需了解其他问题排查信息，请参阅群组的 RBAC 无法用于 OIDC 提供方，以进行进一步的问题排查。

排查身份验证失败问题

如果状态部分的内容表明身份验证失败，请先查看身份提供方和 ID 令牌部分是否存在不一致的情况。

以下是一些您应检查的身份验证要求：

如果身份提供方中的 UserClaim 字段为空，则 ID 令牌部分必须包含一个名为 sub 的字段。缺少 sub 字段表示 ID 令牌存在问题。
身份提供方中的 UserClaim 字段值必须是 ID 令牌部分中的键。例如，如果 UserClaim 字段设置为 email，则 ID 令牌中必须有一个名为 email 的字段。
身份提供方中的 GroupsClaim 字段值必须是 ID 令牌中的键。例如，如果 GroupsClaim 字段设置为 groupsList（适用于支持群组的提供方），则 ID 令牌中必须有一个名为 groupsList 的字段。
身份提供方中的 Client ID 字段值必须包含在 ID 令牌部分中的 aud 字段值内。

如果不满足上述任何条件，请参阅以下指南之一，详细了解如何使用 GKE Identity Service 正确配置集群：

如果您为个别集群设置 GKE Identity Service，请参阅有关配置个别集群的说明。
如果您在舰队级设置 GKE Identity Service，请参阅有关配置集群舰队的说明。

使用日志进行进一步的问题排查

GKE Identity Service pod 日志包含其他调试信息。如需使用 GKE Identity Service pod 日志，请执行以下操作：