Puedes usar una utilidad de diagnóstico para solucionar problemas de autenticación basados en FQDN en clústeres miembros de la flota. 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. Este documento solo se aplica a los tipos de clústeres compatibles.
La utilidad de diagnóstico solo está disponible en clústeres individuales que ejecutan la versión 1.32 o posterior 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 que puedas usarla para solucionar problemas. Para habilitarla, sigue estas instrucciones:
Abre el recurso personalizado ClientConfig para editarlo:
kubectl edit clientconfig default \ --kubeconfig CLUSTER_KUBECONFIG -n kube-publicEl 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: emailComo se muestra en el siguiente ejemplo, agrega una sección
identityServiceOptionsal manifiesto de 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: emailReemplaza
TIMESTAMPpor 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. Debido a que la utilidad de diagnóstico está disponible para cualquier persona con acceso al clúster, configurar la hora de vencimiento de forma adecuada ayuda a garantizar que la utilidad no permanezca habilitada más tiempo del necesario. Cuando configures la hora de vencimiento, se recomienda establecerla en 12 horas en el futuro, aunque cualquier hora en el futuro es válida.Guarda los cambios y cierra el editor de texto para aplicar el manifiesto al clúster.
Usa la utilidad de diagnóstico para simular un acceso
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.
Para abrir la página de diagnóstico en un navegador, navega a la siguiente URL:
APISERVER-URL/diagnoseReemplaza
APISERVER_URLpor el nombre de dominio completamente calificado (FQDN) de tu clúster. Por ejemplo,https://apiserver.example.com.Si encuentras un error prohibido, como el siguiente:
forbidden: user \"system:anonymous\" cannot get path \"/diagnose\"Agrega el valor del número de puerto
:11001aAPISERVER_URL. Por ejemplo,https://apiserver.example.com:11001/diagnose.En la página de diagnóstico, se muestra una lista de los proveedores de OIDC configurados para tu clúster.
Selecciona el proveedor en 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
SuccessoFailed, según si la autenticación se realizó correctamente o no.Proveedor de identidad: Contiene detalles, como
Name,Client IDyUserClaim, sobre el proveedor que se usó para acceder.Token de ID: Contiene información sobre el token de ID que recuperó el clúster 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,subyemail.
Soluciona problemas de autenticación exitosa
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 información adicional sobre la solución de problemas, consulta RBAC para grupos que no funcionan para proveedores de OIDC.
Soluciona problemas de falla de autenticación
Si el contenido de la sección Estado indica que falló la autenticación, comienza por buscar incoherencias entre las secciones Proveedor de identidad y Token de ID.
Estos son algunos requisitos de autenticación que debes verificar:
Si el campo
UserClaimen Proveedor de identidad está vacío, la sección Token de ID debe contener un campo llamadosub. Un camposubfaltante es una indicación de que hay un problema con el token de ID.El valor del campo
UserClaimen Proveedor de identidad debe ser una clave en la sección Token de ID. Por ejemplo, si el campoUserClaimestá configurado comoemail, debe haber un campo llamadoemailen Token de ID.El valor del campo
GroupsClaimen Proveedor de identidad debe ser una clave en Token de ID. Por ejemplo, si el campoGroupsClaimestá configurado comogroupsList(para un proveedor que admite grupos), debe haber un campo llamadogroupsListen Token de ID.El valor del campo
Client IDen Proveedor de identidad debe estar dentro del valor del campoauden 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 detalles sobre cómo configurar correctamente tus clústeres para la autenticación:
Si configuraste la autenticación para clústeres individuales, consulta las instrucciones para configurar clústeres individuales.
Si configuraste la autenticación a nivel de la flota, consulta las instrucciones para configurar una flota de clústeres.
Usa registros para solucionar problemas adicionales
Los registros de Pod del servicio de identidad contienen información de depuración adicional. Para usar estos registros, haz lo siguiente: