Utilitaire de diagnostic de GKE Identity Service

L'utilitaire de diagnostic GKE Identity Service vous aide à résoudre les problèmes d'authentification basée sur le nom de domaine complet. Si vous rencontrez des difficultés pour vous authentifier sur un cluster à l'aide d'un fournisseur OIDC spécifique, vous pouvez activer l'outil et l'utiliser pour identifier rapidement les problèmes de configuration en simulant des flux de connexion avec votre fournisseur OIDC.

L'utilitaire de diagnostic n'est disponible que sur les clusters individuels exécutant GKE Enterprise 1.32 ou version ultérieure, et n'est compatible qu'avec OIDC.

Activer l'utilitaire de diagnostic

L'utilitaire de diagnostic est désactivé par défaut et doit être activé avant que vous puissiez l'utiliser pour résoudre les problèmes. Pour l'activer, procédez comme suit :

  1. Ouvrez la ressource personnalisée ClientConfig pour la modifier :

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

    Le fichier manifeste doit ressembler à ce qui suit :

    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. Comme indiqué dans l'exemple suivant, ajoutez une section identityServiceOptions au fichier manifeste ClientConfig pour spécifier la configuration de l'utilitaire de diagnostic :

    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
    

    Remplacez TIMESTAMP par une heure d'expiration au format RFC 3339. Exemple : 2025-05-01T17:05:00Z. Le délai d'expiration détermine le moment où la fonctionnalité d'utilitaire de diagnostic se désactive automatiquement. Étant donné que l'utilitaire de diagnostic est disponible pour toute personne ayant accès au cluster, définir un délai d'expiration approprié permet de s'assurer que l'utilitaire ne reste pas activé plus longtemps que nécessaire. Lorsque vous définissez le délai d'expiration, nous vous recommandons de le définir sur 12 heures dans le futur, bien que n'importe quelle heure dans le futur soit valide.

  3. Enregistrez vos modifications et quittez l'éditeur de texte pour appliquer le fichier manifeste au cluster.

Utiliser l'utilitaire de diagnostic pour simuler une connexion

Une fois l'utilitaire de diagnostic activé, vous pouvez simuler un événement de connexion et obtenir les informations de diagnostic correspondantes que vous pouvez utiliser pour résoudre les problèmes liés à un fournisseur spécifique.

  1. Ouvrez la page de diagnostic dans un navigateur en accédant à l'URL suivante :

    APISERVER-URL/diagnose
    

    Remplacez APISERVER_URL par le nom de domaine complet de votre cluster. Exemple :https://apiserver.example.com

    Si vous rencontrez une erreur "Interdit" semblable à celle-ci :

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

    Ajoutez la valeur du numéro de port :11001 à APISERVER_URL. Par exemple, https://apiserver.example.com:11001/diagnose.

    La page de diagnostic affiche la liste des fournisseurs OIDC configurés pour votre cluster.

  2. Sélectionnez le fournisseur pour lequel vous souhaitez résoudre des problèmes.

  3. Connectez-vous comme d'habitude.

    À la fin du processus de connexion, l'utilitaire affiche une page contenant des informations de diagnostic qui peuvent vous aider à résoudre les problèmes.

Utiliser la page "Diagnostic" pour résoudre les problèmes de connexion

La page "Diagnostic" fournit un récapitulatif de l'authentification, divisé en trois sections :

  • État : contient Success ou Failed, selon que l'authentification a réussi ou non.

  • Fournisseur d'identité : contient des informations sur le fournisseur utilisé pour se connecter, comme Name, Client ID et UserClaim.

  • Jeton d'identification : contient des informations sur le jeton d'identification récupéré par GKE Identity Service à l'aide du fournisseur indiqué. Le jeton d'identité est un objet JSON contenant un ensemble de paires clé/valeur. Les clés peuvent inclure iss, aud, sub et email.

Résoudre les problèmes d'authentification réussie

Si le contenu de la section État indique que l'authentification a réussi et que vous rencontrez toujours des problèmes, il est possible que des contrôles d'accès basés sur les rôles (RBAC) soient manquants. Pour obtenir des informations de dépannage supplémentaires, consultez Les autorisations RBAC pour les groupes ne fonctionnent pas pour les fournisseurs OIDC.

Résoudre les problèmes d'échec de l'authentification

Si le contenu de la section État indique que l'authentification a échoué, commencez par rechercher les incohérences entre les sections Fournisseur d'identité et Jeton d'identité.

Voici quelques exigences d'authentification à vérifier :

  • Si le champ UserClaim dans Fournisseur d'identité est vide, la section Jeton d'identité doit contenir un champ nommé sub. Un champ sub manquant indique qu'il y a un problème avec le jeton d'identité.

  • La valeur du champ UserClaim dans Fournisseur d'identité doit être une clé dans la section Jeton d'identité. Par exemple, si le champ UserClaim est défini sur email, un champ nommé email doit figurer dans le jeton d'identité.

  • La valeur du champ GroupsClaim dans Fournisseur d'identité doit être une clé dans Jeton d'identité. Par exemple, si le champ GroupsClaim est défini sur groupsList (pour un fournisseur compatible avec les groupes), un champ nommé groupsList doit figurer dans le jeton d'identité.

  • La valeur du champ Client ID dans Fournisseur d'identité doit être contenue dans la valeur du champ aud de la section Jeton d'identité.

Si l'une des conditions précédentes n'est pas remplie, consultez l'un des guides suivants pour savoir comment configurer correctement vos clusters avec GKE Identity Service :

Utiliser les journaux pour résoudre les problèmes

Les journaux des pods GKE Identity Service contiennent des informations de débogage supplémentaires. Pour utiliser les journaux des pods GKE Identity Service :

  1. Activez le journal de débogage de GKE Identity Service.

  2. Consultez le journal du conteneur GKE Identity Service.