Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
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 individuais
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. Para ativar, siga estas instruções:
Abra o recurso personalizado ClientConfig para edição:
Como mostrado no exemplo abaixo, adicione uma seção identityServiceOptions
ao manifesto ClientConfig para especificar a configuração do utilitário de diagnóstico:
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.
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.
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.
Selecione o provedor que você quer resolver.
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 de 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 ID Token.
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:
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-09-01 UTC."],[],[],null,["# GKE Identity Service diagnostic utility\n=======================================\n\nThe GKE Identity Service diagnostic utility helps you to troubleshoot\n[FQDN-based authentication](/kubernetes-engine/enterprise/identity/setup/authenticate-fqdn-access)\nissues. If you're experiencing difficulties authenticating to a cluster using a\nspecific OIDC provider, you can enable the tool and use it to quickly identify\nconfiguration issues by simulating sign-in flows with\nyour OIDC provider.\n\nThe diagnostic utility is only available on [individual clusters](/kubernetes-engine/enterprise/identity/setup/per-cluster-overview)\nrunning GKE Enterprise 1.32 or higher and only supports OIDC.\n\nEnable the diagnostic utility\n-----------------------------\n\nThe diagnostic utility is disabled by default and must be enabled before you\ncan use it to troubleshoot. To enable it, use these instructions:\n\n1. Open the ClientConfig custom resource for editing:\n\n kubectl edit clientconfig default \\\n --kubeconfig \u003cvar translate=\"no\"\u003eCLUSTER_KUBECONFIG\u003c/var\u003e -n kube-public\n\n The manifest should look similar to the following: \n\n apiVersion: authentication.gke.io/v2alpha1\n kind: ClientConfig\n metadata:\n name: default\n namespace: kube-public\n spec:\n authentication:\n - name: oidc\n oidc:\n clientID: example-client-id\n clientSecret: example-client-secret\n cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc\n extraParams: prompt=consent, access_type=offline\n issuerURI: https://example.com\n kubectlRedirectURI: http://localhost:PORT/callback\n scopes: openid,email,offline_access\n userClaim: email\n\n2. As shown in the following example, add an `identityServiceOptions` section\n to the ClientConfig manifest to specify the diagnostic utility\n configuration:\n\n apiVersion: authentication.gke.io/v2alpha1\n kind: ClientConfig\n metadata:\n name: default\n namespace: kube-public\n spec:\n identityServiceOptions:\n diagnosticInterface:\n enabled: true\n expirationTime: \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eTIMESTAMP\u003c/span\u003e\u003c/var\u003e\n authentication:\n - name: oidc\n oidc:\n clientID: example-client-id\n clientSecret: example-client-secret\n cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc\n extraParams: prompt=consent, access_type=offline\n issuerURI: https://example.com\n kubectlRedirectURI: http://localhost:PORT/callback\n scopes: openid,email,offline_access\n userClaim: email\n\n Replace \u003cvar translate=\"no\"\u003eTIMESTAMP\u003c/var\u003e with an expiration time in\n [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format. For\n example, `2025-05-01T17:05:00Z`. The expiration time determines when the\n diagnostic utility feature automatically turns off. Since the diagnostic\n utility is available to anyone with cluster access, setting the expiration\n time appropriately helps ensure that the utility doesn't remain enabled\n longer than necessary. When setting the expiration time, it's recommended\n to set it to 12 hours in the future, although any time in the future is\n valid.\n3. Save your changes and exit the text editor to apply the manifest to the\n cluster.\n\nUse the diagnostic utility to simulate a sign-in\n------------------------------------------------\n\nOnce the diagnostic utility is enabled, you can simulate a sign-in event and get\nthe corresponding diagnostic information that you can use to troubleshoot issues\nwith a specific provider.\n\n1. Open the diagnostic page in a browser by navigating to the following URL:\n\n \u003cvar translate=\"no\"\u003eAPISERVER-URL\u003c/var\u003e/diagnose\n\n Replace \u003cvar translate=\"no\"\u003eAPISERVER_URL\u003c/var\u003e with the fully qualified domain\n name (FQDN) for your cluster. For example, `https://apiserver.example.com`.\n\n If you encounter a forbidden error, like the following: \n\n forbidden: user \\\"system:anonymous\\\" cannot get path \\\"/diagnose\\\"\n\n Append the port number value of **`:11001`** to the \u003cvar translate=\"no\"\u003eAPISERVER_URL\u003c/var\u003e. For example, `https://apiserver.example.com:11001/diagnose`.\n\n The diagnostic page displays a list of OIDC providers configured for your\n cluster.\n2. Select the provider that you want to troubleshoot.\n\n3. Sign in as usual.\n\n At the end of the sign in process, the utility displays a page with\n diagnostic information that can help you troubleshoot.\n\nUse the diagnostics page to troubleshoot sign-in problems\n---------------------------------------------------------\n\nThe diagnostics page provides an authentication summary, which is divided into\nthree sections:\n\n- **Status** : contains either `Success` or `Failed`, depending on whether the\n authentication has succeeded or not.\n\n- **Identity Provider** : contains details, such as `Name`, `Client ID`, and\n `UserClaim`, about the provider that was used to sign in.\n\n- **ID Token** : contains information about ID token fetched by\n GKE Identity Service using the given provider. The ID token is a JSON\n object containing a set of key-value pairs. Keys might include `iss`, `aud`,\n `sub`, and `email`.\n\n### Troubleshoot authentication success\n\nIf the content of the **Status** section indicates that the authentication has\nsucceeded and you're still experiencing issues, missing\nrole-based-access-controls (RBACs) might be the cause. For additional\ntroubleshooting information, see [RBACs for groups not working for OIDC\nproviders](/kubernetes-engine/enterprise/identity/setup/user-access-troubleshooting#rbacs_for_groups_not_working_for_oidc_providers)\nfor further troubleshooting.\n\n### Troubleshoot authentication failure\n\nIf the content of the **Status** section indicates that the authentication has\nfailed, start by looking for inconsistencies between the **Identity Provider**\nand **ID Token** sections.\n\nHere are a few authentication requirements that you should check:\n\n- If the `UserClaim` field in **Identity Provider** is empty, then the **ID\n Token** section must contain a field named `sub`. A missing `sub` field is\n an indication that there's a problem with the ID token.\n\n- The `UserClaim` field value in **Identity Provider** must be a key in the\n **ID Token** section. For example, if the `UserClaim` field is set to\n `email`, then there must be a field named `email` in **ID Token**.\n\n- The `GroupsClaim` field value in **Identity Provider** must be a key in **ID\n Token** . For example, if the `GroupsClaim` field is set to `groupsList` (for\n a provider that supports groups), then there must be a field named\n `groupsList` in **ID Token**.\n\n- The `Client ID` field value in **Identity Provider** must be contained\n within the value of the `aud` field in **ID Token** section.\n\nIf any of the preceding conditions aren't met, see one of the following guides\nfor more details on how to properly configure your clusters with\nGKE Identity Service:\n\n- If you set up GKE Identity Service for individual clusters, see the\n [instructions to configure individual\n clusters](/kubernetes-engine/enterprise/identity/setup/per-cluster#configure_clusters).\n\n- If you set up GKE Identity Service at a fleet level, see the\n [instructions to configure a fleet of\n clusters](/kubernetes-engine/enterprise/identity/setup/fleet-cluster#configure_clusters).\n\n### Use logs for further troubleshooting\n\nThe [GKE Identity Service pod\nlogs](/kubernetes-engine/enterprise/identity/setup/ais-pod-troubleshooting)\ncontain additional debugging information. To use GKE Identity Service pod\nlogs:\n\n1. [Enable the GKE Identity Service debug log](/kubernetes-engine/enterprise/identity/setup/user-access-troubleshooting#enable_the_debug_log).\n\n2. [Check the GKE Identity Service container log](/kubernetes-engine/enterprise/identity/setup/user-access-troubleshooting#check_the_container_log)."]]
