Utilitário de diagnóstico do serviço de identidade do GKE

O utilitário de diagnóstico do serviço de identidade do GKE ajuda a resolver problemas de autenticação baseada em FQDN. Se você tiver dificuldades para autenticar em um cluster usando um provedor OIDC específico, ative a ferramenta e use-a para identificar rapidamente problemas de configuração simulando fluxos de login com seu provedor OIDC.

O utilitário de diagnóstico está disponível apenas em clusters que executam o GKE Enterprise 1.32 ou mais recente e só oferece suporte ao OIDC.

Ativar o utilitário de diagnóstico

O utilitário de diagnóstico é desativado por padrão e precisa ser ativado antes de ser usado para solucionar problemas. A maneira de ativar o utilitário depende de como você configurou o cluster com o serviço de identidade do GKE.

Configuração da frota (console)

Se você usou o consoleGoogle Cloud para configurar clusters com o GKE Identity Service no nível da frota, siga estas instruções.

  1. Crie um arquivo de manifesto ClientConfig YAML conforme descrito em Criar um arquivo de configuração.

    O manifesto vai ser parecido com este:

    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

  2. Como mostrado no exemplo abaixo, adicione uma seção identityServiceOptions ao manifesto ClientConfig para especificar a configuração do utilitário de diagnóstico:

    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

    Substitua TIMESTAMP por um horário de expiração no formato RFC 3339. Por exemplo, 2025-05-01T17:05:00Z. O tempo de expiração determina quando o recurso do utilitário de diagnóstico é desativado automaticamente. Como o utilitário de diagnóstico está disponível para qualquer pessoa com acesso ao cluster, definir o tempo de expiração adequadamente ajuda a garantir que o utilitário não permaneça ativado por mais tempo do que o necessário. Ao definir o prazo de validade, é recomendável definir 12 horas no futuro, embora qualquer horário no futuro seja válido.

  3. Em seguida, aplique o arquivo ao cluster executando:

    gcloud container fleet identity-service apply \
    --membership=CLUSTER_NAME \
    --config=MANIFEST_FILE_PATH

    Substitua:

    • CLUSTER_NAME: o nome exclusivo do cluster na frota.

    • MANIFEST_FILE_PATH: caminho do arquivo de manifesto ClientConfig YAML.

Configuração da frota (gcloud)

Se você usou a CLI do Google Cloud para configurar clusters com o GKE Identity Service no nível da frota, siga estas instruções:

  1. Abra o arquivo de manifesto ClientConfig que foi criado quando você configurou o cluster com o GKE Identity Service.

    O manifesto vai ser parecido com este:

    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

  2. Como mostrado no exemplo abaixo, adicione uma seção identityServiceOptions ao manifesto ClientConfig para especificar a configuração do utilitário de diagnóstico:

    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

    Substitua TIMESTAMP por um horário de expiração no formato RFC 3339. Por exemplo, 2025-05-01T17:05:00Z. O tempo de expiração determina quando o recurso do utilitário de diagnóstico é desativado automaticamente. Como o utilitário de diagnóstico está disponível para qualquer pessoa com acesso ao cluster, definir o tempo de expiração adequadamente ajuda a garantir que o utilitário não permaneça ativado por mais tempo do que o necessário. Ao definir o prazo de validade, é recomendável definir 12 horas no futuro, embora qualquer horário no futuro seja válido.

  3. Em seguida, aplique o arquivo ao cluster executando:

    gcloud container fleet identity-service apply \
    --membership=CLUSTER_NAME \
    --config=MANIFEST_FILE_PATH

    Substitua:

    • CLUSTER_NAME: o nome exclusivo do cluster na frota.

    • MANIFEST_FILE_PATH: caminho do arquivo de manifesto ClientConfig YAML.

Configuração de clusters individuais

Se você configurar o serviço de identidade do GKE para clusters individuais, siga estas instruções:

  1. Abra o recurso personalizado ClientConfig para edição:

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

    O manifesto vai ser parecido com este:

    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

  2. Como mostrado no exemplo abaixo, adicione uma seção identityServiceOptions ao manifesto ClientConfig para especificar a configuração do utilitário de diagnóstico:

    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

    Substitua TIMESTAMP por um horário de expiração no formato RFC 3339. Por exemplo, 2025-05-01T17:05:00Z. O tempo de expiração determina quando o recurso do utilitário de diagnóstico é desativado automaticamente. Como o utilitário de diagnóstico está disponível para qualquer pessoa com acesso ao cluster, definir o tempo de expiração adequadamente ajuda a garantir que o utilitário não permaneça ativado por mais tempo do que o necessário. Ao definir o prazo de validade, é recomendável definir 12 horas no futuro, embora qualquer horário no futuro seja válido.

  3. Salve as alterações e saia do editor de texto para aplicar o manifesto ao cluster.

Usar o utilitário de diagnóstico para simular um login

Depois que o utilitário de diagnóstico for ativado, você poderá simular um evento de login e receber as informações de diagnóstico correspondentes que podem ser usadas para resolver problemas com um provedor específico.

  1. Abra a página de diagnóstico em um navegador acessando o seguinte URL:

    APISERVER-URL/diagnose

    Substitua APISERVER_URL pelo nome de domínio totalmente qualificado (FQDN) do cluster. Por exemplo, https://apiserver.example.com.

    A página de diagnóstico mostra uma lista de provedores OIDC configurados para seu cluster.

  2. Selecione o provedor que você quer resolver.

  3. Faça login normalmente.

    Ao final do processo de login, o utilitário mostra uma página com informações de diagnóstico que podem ajudar a resolver problemas.

Usar a página de diagnóstico para resolver problemas de login

A página de diagnóstico fornece um resumo da autenticação, que é dividido em três seções:

  • Status: contém Success ou Failed, dependendo se a autenticação foi bem-sucedida ou não.

  • Provedor de identidade: contém detalhes, como Name, Client ID e UserClaim, sobre o provedor usado para fazer login.

  • Token de ID: contém informações sobre o token de ID buscado pelo serviço de identidade do GKE usando o provedor fornecido. O token de ID é um objeto JSON que contém um conjunto de pares de chave-valor. As chaves podem incluir iss, aud, sub e email.

Resolver problemas de sucesso da autenticação

Se o conteúdo da seção Status indicar que a autenticação foi concluída e você ainda estiver com problemas, a ausência de controles de acesso baseados em função (RBACs) pode ser a causa. Para mais informações sobre solução de problemas, consulte RBACs para grupos que não funcionam com provedores OIDC para mais soluções.

Resolver falhas de autenticação

Se o conteúdo da seção Status indicar que a autenticação falhou, comece procurando inconsistências entre as seções Provedor de identidade e Token de ID.

Confira alguns requisitos de autenticação que você precisa verificar:

  • Se o campo UserClaim em Provedor de identidade estiver vazio, a seção ID Token precisará conter um campo chamado sub. Um campo sub ausente é uma indicação de que há um problema com o token de ID.

  • O valor do campo UserClaim em Provedor de identidade precisa ser uma chave na seção Token de ID. Por exemplo, se o campo UserClaim estiver definido como email, será necessário ter um campo chamado email no token de ID.

  • O valor do campo GroupsClaim no provedor de identidade precisa ser uma chave no token de ID. Por exemplo, se o campo GroupsClaim estiver definido como groupsList (para um provedor compatível com grupos), será necessário ter um campo chamado groupsList em Token de ID.

  • O valor do campo Client ID no provedor de identidade precisa estar contido no valor do campo aud na seção token de ID.

Se alguma das condições anteriores não for atendida, consulte um dos guias a seguir para mais detalhes sobre como configurar corretamente seus clusters com o GKE Identity Service:

Usar registros para resolver outros problemas

Os registros do pod do Serviço de identidade do GKE contêm outras informações de depuração. Para usar os registros do pod do serviço de identidade do GKE:

  1. Ative o registro de depuração do serviço de identidade do GKE.

  2. Confira o registro de contêiner do GKE Identity Service.