Utilidad de diagnóstico de GKE Identity Service

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

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

Habilitar la utilidad de diagnóstico

La utilidad de diagnóstico está inhabilitada de forma predeterminada y debe habilitarse para poder usarla en la solución de problemas. Para habilitarlo, sigue estas instrucciones:

  1. Abre el recurso personalizado ClientConfig para editarlo:

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

    El archivo de manifiesto debería ser 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

  2. Como se muestra en el siguiente ejemplo, añade 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

    Sustituye 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 utilidad de diagnóstico. Como la utilidad de diagnóstico está disponible para cualquier persona con acceso al clúster, definir la hora de vencimiento de forma adecuada ayuda a garantizar que la utilidad no permanezca habilitada más tiempo del necesario. Cuando definas la hora de vencimiento, te recomendamos que sea 12 horas después de la hora actual, aunque puedes elegir cualquier hora futura.

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

Usar la utilidad de diagnóstico para simular un inicio de sesión

Una vez que se haya habilitado la utilidad de diagnóstico, podrá simular un evento de inicio de sesión y obtener la información de diagnóstico correspondiente, que podrá usar para solucionar problemas con un proveedor específico.

  1. Abre la página de diagnóstico en un navegador. Para ello, ve a la siguiente URL:

    APISERVER-URL/diagnose

    Sustituye APISERVER_URL por el nombre de dominio completo (FQDN) de tu clúster. Por ejemplo, https://apiserver.example.com.

    Si aparece un error de acceso prohibido, como el siguiente:

    forbidden: user \"system:anonymous\" cannot get path \"/diagnose\"

    Añade el valor del número de puerto de :11001 a APISERVER_URL. Por ejemplo, https://apiserver.example.com:11001/diagnose.

    En la página de diagnóstico se muestra una lista de proveedores de OIDC configurados para tu clúster.

  2. Selecciona el proveedor con el que quieres solucionar el problema.

  3. Inicia sesión como siempre.

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

Usar la página de diagnóstico para solucionar problemas de inicio de sesión

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

  • Status: contiene Success o Failed, según si la autenticación se ha realizado correctamente o no.

  • Proveedor de identidades: contiene detalles, como Name, Client ID y UserClaim, sobre el proveedor que se usó para iniciar sesión.

  • Token de ID: contiene información sobre el token de ID obtenido por el servicio de identidad de GKE mediante el proveedor indicado. 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.

Solucionar problemas de autenticación

Si el contenido de la sección Estado indica que la autenticación se ha realizado correctamente y sigues teniendo problemas, puede que se deba a que faltan controles de acceso basados en roles (RBAC). Para obtener más información sobre cómo solucionar problemas, consulta Los RBACs de grupos no funcionan con proveedores de OIDC.

Solucionar problemas de autenticación

Si el contenido de la sección Estado indica que la autenticación ha fallado, empieza por buscar incoherencias entre las secciones Proveedor de identidad y Token de ID.

Estos son algunos de los requisitos de autenticación que debes comprobar:

  • Si el campo UserClaim de Proveedor de identidades está vacío, la sección ID Token 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 de Proveedor de identidades debe ser una clave de la sección Token de ID. Por ejemplo, si el campo UserClaim tiene el valor email, debe haber un campo llamado email en Token de ID.

  • El valor del campo GroupsClaim de Proveedor de identidades debe ser una clave de Token de ID. Por ejemplo, si el campo GroupsClaim se define como groupsList (para un proveedor que admite grupos), debe haber un campo llamado groupsList en Token de ID.

  • El valor del campo Client ID de Proveedor de identidad debe estar incluido en el valor del campo aud de la sección Token de ID.

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

Usar registros para solucionar problemas

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

  1. Habilita el registro de depuración de Identity Service de GKE.

  2. Consulta el registro del contenedor de GKE Identity Service.