排查舰队级设置问题

本文档为 GKE Identity Service 的舰队级设置提供了问题排查说明。

解决舰队级设置问题

如需解决设置舰队时可能出现的问题,请按照以下说明操作:

1. 验证是否已启用 GKE Identity Service

如需验证是否已为您的项目启用 GKE Identity Service,请运行以下命令:

$ gcloud container fleet identity-service describe

如果您没有看到任何错误,则表示 GKE Identity Service 已启用,您可以继续按照下一条说明操作。

错误: Identity Service Feature for project <your-project-id> is not enabled

如果您看到此错误,则表示在设置该功能时,没有为舰队正确启用 GKE Identity Service。

解决方案:如需确保为您的项目启用了该功能,请参阅为 GKE Identity Service 配置集群中的说明。

2. 查看 GKE Identity Service 状态

如需查看 GKE Identity Service 的当前状态,请运行以下命令:

$ gcloud container fleet identity-service describe

此命令的输出包含以下两个部分:

  • membershipSpecs 包含您为注册到舰队的每个集群指定的身份提供方配置。使用这些配置在每个集群上配置 GKE Identity Service。

  • membershipStates 会显示每个集群中 GKE Identity Service 的当前状态,包括相关身份提供方配置以及设置过程中可能发生的任何错误。

如需排查集群中的问题,请在 membershipStates 下搜索集群并查找以下字段:

  • state 字段:membershipStates -> <cluster-identifier> -> identityservice -> state
  • failureReason 字段:membershipStates -> <cluster-identifier> -> identityservice -> failureReason

示例

如果您已将两个集群 helloworldfoobar 注册到舰队,则输出将具有以下结构:

Identity Service Feature:
  createTime: '222-11-10T23:05:6.146566392Z'
  membershipSpecs:
    projects/<your-project-number>/locations/<location>/memberships/helloworld:
      identityservice:
        authMethods:
        - name: oidc
          oidcConfig:
            clientId: id
            issuerUri: https://accounts.google.com
            ... other fields
    projects/<your-project-number>/locations/<location>/memberships/foobar:
      identityservice:
        authMethods:
        - name: oidc
          oidcConfig:
            clientId: id
            issuerUri: https://accounts.google.com
            ... other fields 
  membershipStates:
    projects/<your-project-number>/location/<location>/memberships/helloworld:
      identityservice:
        failureReason: AIS feature does not support this cluster type
        memberConfig:
          authMethods:
          - name: oidc
            oidcConfig:
              clientId: id
              issuerUri: https://accounts.google.com
              ... other fields
        state: ERROR
      state:
        code: OK
        updateTime: '2022-11-11T20:39:59.556176650Z'
    projects/<your-project-number>/location/<location>/memberships/foobar:
      identityservice:
        memberConfig:
          authMethods:
          - name: oidc
            oidcConfig:
              clientId: id
              issuerUri: https://accounts.google.com
              ... other fields
        state: OK
      state:
        code: OK
        updateTime: '2022-11-11T20:39:59.556176650Z'

  name: projects/<project-number>/locations/global/features/identityservice
  updateTime: '2022-11-11T20:40:31.859321901Z'

3. 验证集群状态

如需验证集群中 GKE Identity Service 的状态,请检查以下各项:

  • state 值为 OK:表示在使用 membershipSpecs 下指定的配置在集群上配置 GKE Identity Service 时,没有发生错误。

    如果您要排查问题的集群配置(例如 helloworld)在 membershipSpecsmembershipStates 中不同,则可能是因为您更新了集群的配置。等待几分钟,让 GKE Identity Service 将更改传播到集群,然后再次检查状态

    如果要排查问题的集群配置(例如 helloworld)在 membershipSpecsmembershipStates 中相同,则表示 GKE Identity Service 已正确配置。

  • state 字段为 ERROR:表示在使用 membershipSpecs 下指定的配置在集群上配置 GKE Identity Service 时出错。

    要解决此问题,请参阅排查常见问题。 完成必要的问题排查步骤后,请等待几分钟,然后再次检查状态

排查常见问题

GKE Identity Service API 未启用

如果未启用 GKE Identity Service API,则会出现此问题。

错误消息

anthosidentityservice.googleapis.com is not enabled

解决方案

如需启用 API,请运行以下命令:

$ gcloud services enable anthosidentityservice.googleapis.com

集群类型不受支持

当您使用不受支持的集群类型时,会发生此问题。

错误消息

GKE Identity Service feature does not support this cluster type

解决方案

如需了解受支持的集群类型,请参阅集群类型,或与 Google Cloud 支持团队联系以处理新的集群类型请求。

在配置中找到的协议不受支持

当您应用于集群的身份配置包含不受支持的协议时,就会出现此问题。

错误消息

unsupported protocol found in configuration, aborting reconciliation.

解决方案

GKE Identity Service 的舰队级设置支持:

更新集群上的配置,使其仅包含上述受支持的协议。如需修改配置,请运行以下命令:

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

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

集群没有身份配置

如果没有向集群应用任何配置,就会出现此问题。

错误消息

Authentication configuration is not present for this membership

解决方案

按照配置集群中的说明将身份配置应用于集群。

缺少 GKE Hub Admin IAM 权限

如果您在使用的项目上没有 gkehub.admin 角色,则会出现此问题。

错误消息

PERMISSION_DENIED: Permission 'gkehub.memberships.list' denied on '`projects//locations//memberships`'
PERMISSION_DENIED: Permission 'gkehub.features.get' denied on '`projects//locations/global/features/identityservice`'
PERMISSION_DENIED: Permission 'gkehub.features.delete' denied on '`projects//locations/global/features/identityservice`'
PERMISSION_DENIED: Permission 'gkehub.features.create' denied on '`projects//locations/global/features/identityservice`'

解决方案

ID 为 project_id 的项目的所有者必须运行以下命令:

gcloud projects add-iam-policy-binding project_id --member=user:USER_ID --role=roles/gkehub.admin

USER_ID 替换为您的 Google 账号。

身份配置中存在非唯一的身份提供方

如果集群的 GKE Identity Service 配置对多个身份提供方具有相同的 name 值,则会出现此问题。

错误消息

Configuration contains multiple identity providers with the same name

解决方案

重命名或移除配置中的重复条目。

身份配置中存在多个类型为 google 的提供方

如果 ClientConfig 配置了多个类型为 google 的配置,则会出现此问题。

错误消息

configuration contains multiple identity providers of type 'google'

解决方案

配置的 spec/authentication 部分最多可以包含一个类型为 google 的配置。

更新集群上的配置,使其不含多个类型为 google 的配置。如需修改配置,请运行以下命令:

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

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

提取 ClientConfig 的自定义资源定义时出错

如果从集群提取 ClientConfig 的自定义资源定义时出错,就会出现此问题。

错误消息

error fetching the ClientConfig's Custom Resource Definition: ERROR_REASON

解决方案

使用 ERROR_REASON 中显示的详细信息解决此问题。

更新 GKE Identity Service ClientConfig 时出错

如果更新集群中的 ClientConfig 时出错,则会出现此问题。

错误消息

Error updating AIS ClientConfig: ERROR_REASON

解决方案

使用 ERROR_REASON> 中显示的详细信息解决此问题。

客户端不存在 ClientConfig

当集群上不存在应在安装 GKE Identity Service 时创建的 ClientConfig 时,就会出现此问题。缺少 ClientConfig 表示 GKE Identity Service 未在集群上正确安装。

错误消息

ClientConfig CR not present, expected to be created when AIS was installed

解决方案

集群上的 GKE Identity Service 资源可能被意外删除。您可以尝试创建新集群。如果您在新集群中看到相同的错误,请与您的集群管理员或 Google Cloud 支持团队联系。

GKE Identity Service pod 未启动

当 GKE Identity Service pod 处于 pending 状态时,就会出现此问题。

错误消息

GKE Identity Service pod is not running (pending)

解决方案

此问题应该会在几分钟后自动解决,之后 GKE Identity Service pod 会切换到 running 状态。