Esta página foi traduzida pela API Cloud Translation.

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

A utilidade de diagnóstico do GKE Identity Service ajuda a resolver problemas de autenticação baseada em FQDN. Se tiver dificuldades em autenticar-se num cluster através de um fornecedor de OIDC específico, pode ativar a ferramenta e usá-la para identificar rapidamente problemas de configuração simulando fluxos de início de sessão com o seu fornecedor de OIDC.

A utilidade de diagnóstico só está disponível em clusters individuais com o GKE Enterprise 1.32 ou superior e só suporta o OIDC.

Ative a utilidade de diagnóstico

A utilidade de diagnóstico está desativada por predefinição e tem de ser ativada antes de a poder usar para resolver problemas. Para a 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 deve ser semelhante ao seguinte:

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 seguinte, adicione uma secçã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 uma hora de validade no formato RFC 3339. Por exemplo, 2025-05-01T17:05:00Z. A hora de expiração determina quando a funcionalidade de utilitário de diagnóstico é desativada automaticamente. Uma vez que o utilitário de diagnóstico está disponível para qualquer pessoa com acesso ao cluster, a definição da hora de expiração de forma adequada ajuda a garantir que o utilitário não permanece ativado durante mais tempo do que o necessário. Ao definir a hora de validade, é recomendável defini-la para 12 horas no futuro, embora qualquer hora no futuro seja válida.

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

Depois de ativar a utilidade de diagnóstico, pode simular um evento de início de sessão e obter as informações de diagnóstico correspondentes que pode usar para resolver problemas com um fornecedor específico.

Abra a página de diagnóstico num navegador navegando para o seguinte URL:
```
APISERVER-URL/diagnose
```
Substitua APISERVER_URL pelo nome do domínio totalmente qualificado (FQDN) do cluster. Por exemplo, https://apiserver.example.com.

Se encontrar um erro de acesso proibido, como o seguinte:
```
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 apresenta uma lista de fornecedores de OIDC configurados para o seu cluster.
Selecione o fornecedor cujos problemas quer resolver.
Inicie sessão como habitualmente.

No final do processo de início de sessão, o utilitário apresenta uma página com informações de diagnóstico que podem ajudar a resolver problemas.

Use a página Diagnósticos para resolver problemas de início de sessão

A página Diagnósticos apresenta um resumo da autenticação, que está dividido em três secções:

Status: contém Success ou Failed, consoante a autenticação tenha sido bem-sucedida ou não.
Fornecedor de identidade: contém detalhes, como Name, Client ID e UserClaim, sobre o fornecedor que foi usado para iniciar sessão.
Símbolo de ID: contém informações sobre o símbolo de ID obtido pelo GKE Identity Service através do fornecedor indicado. O token de ID é um objeto JSON que contém um conjunto de pares de chave-valor. As teclas podem incluir iss, aud, sub e email.

Resolva problemas de autenticação bem-sucedida

Se o conteúdo da secção Estado indicar que a autenticação foi bem-sucedida e continuar a ter problemas, a causa pode ser a falta de controlos de acesso baseados em funções (RBACs). Para ver informações adicionais de resolução de problemas, consulte o artigo Os RBACs para grupos não funcionam para fornecedores OIDC para mais informações sobre a resolução de problemas.

Resolva problemas de falha na autenticação

Se o conteúdo da secção Estado indicar que a autenticação falhou, comece por procurar inconsistências entre as secções Fornecedor de identidade e Token de ID.

Seguem-se alguns requisitos de autenticação que deve verificar:

Se o campo UserClaim em Fornecedor de identidade estiver vazio, a secção ID Token tem de conter um campo denominado sub. Um campo sub em falta é uma indicação de que existe um problema com o token de ID.
O valor do campo UserClaim em Fornecedor de identidade tem de ser uma chave na secção Token de ID. Por exemplo, se o campo UserClaim estiver definido como email, tem de existir um campo denominado email no token de ID.
O valor do campo GroupsClaim em Identity Provider tem de ser uma chave em ID Token. Por exemplo, se o campo GroupsClaim estiver definido como groupsList (para um fornecedor que suporta grupos), tem de existir um campo denominado groupsList no token de ID.
O valor do campo Client ID em Fornecedor de identidade tem de estar contido no valor do campo aud na secção Token de ID.

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

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

Use registos para uma resolução de problemas mais detalhada

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

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.