Se usó la API de Cloud Translation para traducir esta página.

Utilidad de diagnóstico de GKE Identity Service

La utilidad de diagnóstico de GKE Identity Service te ayuda a solucionar problemas de autenticación basada en FQDN. Si tienes dificultades para autenticarte en un clúster con un proveedor de OIDC específico, puedes habilitar la herramienta y usarla para identificar rápidamente los problemas de configuración simulando flujos de acceso con tu proveedor de OIDC.

La utilidad de diagnóstico solo está disponible en clústeres individuales que ejecutan GKE Enterprise 1.32 o versiones posteriores, y solo admite OIDC.

Habilita la utilidad de diagnóstico

La utilidad de diagnóstico está inhabilitada de forma predeterminada y se debe habilitar antes de poder usarla para solucionar problemas. Para habilitarlo, sigue estas instrucciones:

Abre el recurso personalizado de ClientConfig para editarlo:

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

El manifiesto debería verse de manera similar al siguiente:

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

Como se muestra en el siguiente ejemplo, agrega una sección identityServiceOptions al manifiesto ClientConfig para especificar la configuración de la utilidad 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

Reemplaza TIMESTAMP por una hora de vencimiento en formato RFC 3339. Por ejemplo, 2025-05-01T17:05:00Z. La hora de vencimiento determina cuándo se desactiva automáticamente la función de la utilidad de diagnóstico. Dado que la utilidad de diagnóstico está disponible para cualquier persona que tenga acceso al clúster, configurar la hora de vencimiento de manera adecuada ayuda a garantizar que la utilidad no permanezca habilitada más tiempo del necesario. Cuando configures el tiempo de vencimiento, te recomendamos que lo establezcas en 12 horas en el futuro, aunque cualquier hora en el futuro es válida.

Guarda los cambios y sal del editor de texto para aplicar el manifiesto al clúster.

Una vez que se habilita la utilidad de diagnóstico, puedes simular un evento de acceso y obtener la información de diagnóstico correspondiente que puedes usar para solucionar problemas con un proveedor específico.

Navega a la siguiente URL para abrir la página de diagnóstico en un navegador:
```
APISERVER-URL/diagnose
```
Reemplaza APISERVER_URL por el nombre de dominio completamente calificado (FQDN) de tu clúster. Por ejemplo, https://apiserver.example.com

En la página de diagnóstico, se muestra una lista de los proveedores de OIDC configurados para tu clúster.
Selecciona el proveedor para el que deseas solucionar problemas.
Accede como de costumbre.

Al final del proceso de acceso, la utilidad muestra una página con información de diagnóstico que puede ayudarte a solucionar problemas.

Usa la página de diagnóstico para solucionar problemas de acceso

La página de diagnóstico proporciona un resumen de autenticación, que se divide en tres secciones:

Estado: Contiene Success o Failed, según si la autenticación se realizó correctamente o no.
Proveedor de identidad: Contiene detalles, como Name, Client ID y UserClaim, sobre el proveedor que se usó para acceder.
Token de ID: Contiene información sobre el token de ID que recupera el servicio de identidad de GKE con el proveedor determinado. El token de ID es un objeto JSON que contiene un conjunto de pares clave-valor. Las claves pueden incluir iss, aud, sub y email.

Soluciona problemas de autenticación correcta

Si el contenido de la sección Estado indica que la autenticación se realizó correctamente y sigues teniendo problemas, es posible que la causa sea la falta de controles de acceso basados en roles (RBAC). Para obtener más información sobre la solución de problemas, consulta RBAC para grupos que no funcionan para proveedores de OIDC.

Soluciona problemas de autenticación

Si el contenido de la sección Estado indica que la autenticación falló, primero busca inconsistencias entre las secciones Proveedor de identidad y Token de ID.

Estos son algunos requisitos de autenticación que debes verificar:

Si el campo UserClaim en Proveedor de identidad está vacío, la sección Token de ID debe contener un campo llamado sub. Si falta el campo sub, significa que hay un problema con el token de ID.
El valor del campo UserClaim en Identity Provider debe ser una clave en la sección ID Token. Por ejemplo, si el campo UserClaim está configurado como email, debe haber un campo llamado email en Token de ID.
El valor del campo GroupsClaim en Proveedor de identidad debe ser una clave en Token de ID. Por ejemplo, si el campo GroupsClaim está configurado como groupsList (para un proveedor que admite grupos), debe haber un campo llamado groupsList en el token de ID.
El valor del campo Client ID en Proveedor de identidad debe estar contenido en el valor del campo aud en la sección Token de ID.

Si no se cumple ninguna de las condiciones anteriores, consulta una de las siguientes guías para obtener más detalles sobre cómo configurar correctamente tus clústeres con GKE Identity Service:

Si configuras GKE Identity Service para clústeres individuales, consulta las instrucciones para configurar clústeres individuales.
Si configuras GKE Identity Service a nivel de la flota, consulta las instrucciones para configurar una flota de clústeres.

Usa registros para solucionar problemas

Los registros del pod de GKE Identity Service contienen información de depuración adicional. Para usar los registros del pod de GKE Identity Service, haz lo siguiente: