Esta página foi traduzida pela API Cloud Translation.

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

O utilitário de diagnóstico do GKE Identity Service ajuda a resolver problemas de autenticação baseada em FQDN. Se você estiver com 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 só está disponível em clusters individuais que executam o GKE Enterprise 1.32 ou mais recente e só é compatível com o OIDC.

Ativar o utilitário de diagnóstico

O utilitário de diagnóstico fica desativado por padrão e precisa ser ativado antes de você usá-lo para resolver problemas. Para ativar, siga estas instruções:

Abra o recurso personalizado ClientConfig para edição:

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

O manifesto será semelhante a 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

Conforme mostrado no exemplo a seguir, 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 de 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 de maneira adequada 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 como 12 horas no futuro, embora qualquer horário no futuro seja válido.

Salve as mudanças e saia do editor de texto para aplicar o manifesto ao cluster.

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.

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.

Se você encontrar um erro proibido, como este:
```
forbidden: user \"system:anonymous\" cannot get path \"/diagnose\"
```
Anexe o valor do número da porta de :11001 ao APISERVER_URL. Por exemplo, https://apiserver.example.com:11001/diagnose.

A página de diagnóstico mostra uma lista de provedores OIDC configurados para seu cluster.
Selecione o provedor que você quer resolver.
Faça login como de costume.

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

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

A página de diagnóstico oferece 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 GKE Identity Service usando o provedor especificado. 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 autenticação

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

Resolver problemas de falha na 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:

Se o campo UserClaim em Provedor de identidade estiver vazio, a seção Token de ID precisará conter um campo chamado sub. A ausência de um campo sub indica 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, precisará haver um campo chamado email no token de ID.
O valor do campo GroupsClaim em Provedor de identidade precisa ser uma chave em Token de ID. Por exemplo, se o campo GroupsClaim estiver definido como groupsList (para um provedor que oferece suporte a grupos), deverá haver um campo chamado groupsList no token de ID.
O valor do campo Client ID em 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 seguintes guias para mais detalhes sobre como configurar corretamente seus clusters com o GKE Identity Service:

Se você configurou o GKE Identity Service para clusters individuais, consulte as instruções para configurar clusters individuais.
Se você configurar o GKE Identity Service no nível da frota, consulte as instruções para configurar uma frota de clusters.

Usar registros para resolver mais problemas

Os registros do pod do GKE Identity Service contêm mais informações de depuração. Para usar os registros do pod do GKE Identity Service:

Utilitário de diagnóstico do serviço de identidade do GKE Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.