Diagnosetool für GKE Identity Service

Mit dem Diagnosetool für GKE Identity Service können Sie Probleme bei der FQDN-basierten Authentifizierung beheben. Wenn Sie Probleme bei der Authentifizierung bei einem Cluster mit einem bestimmten OIDC-Anbieter haben, können Sie das Tool aktivieren und damit schnell Konfigurationsprobleme erkennen, indem Sie Anmeldevorgänge mit Ihrem OIDC-Anbieter simulieren.

Das Diagnosetool ist nur für einzelne Cluster mit GKE Enterprise 1.32 oder höher verfügbar und unterstützt nur OIDC.

Diagnosetool aktivieren

Das Diagnosetool ist standardmäßig deaktiviert und muss aktiviert werden, bevor Sie es zur Fehlerbehebung verwenden können. So aktivieren Sie die Funktion:

  1. Öffnen Sie die benutzerdefinierte ClientConfig-Ressource zum Bearbeiten:

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

    Das Manifest sollte in etwa so aussehen:

    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. Fügen Sie dem ClientConfig-Manifest einen identityServiceOptions-Abschnitt hinzu, um die Konfiguration des Diagnosedienstprogramms anzugeben, wie im folgenden Beispiel gezeigt:

    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
    

    Ersetzen Sie TIMESTAMP durch einen Ablaufzeitpunkt im RFC 3339-Format. Beispiel: 2025-05-01T17:05:00Z. Das Ablaufdatum bestimmt, wann die Funktion für das Diagnosetool automatisch deaktiviert wird. Da das Diagnosetool für alle mit Clusterzugriff verfügbar ist, trägt die entsprechende Festlegung des Ablaufdatums dazu bei, dass das Tool nicht länger als nötig aktiviert bleibt. Beim Festlegen der Ablaufzeit wird empfohlen, sie auf 12 Stunden in der Zukunft festzulegen. Jede Zeit in der Zukunft ist jedoch gültig.

  3. Speichern Sie die Änderungen und beenden Sie den Texteditor, um das Manifest auf den Cluster anzuwenden.

Diagnosetool zum Simulieren einer Anmeldung verwenden

Sobald das Diagnosetool aktiviert ist, können Sie ein Anmeldeereignis simulieren und die entsprechenden Diagnoseinformationen abrufen, mit denen Sie Probleme mit einem bestimmten Anbieter beheben können.

  1. Öffnen Sie die Diagnoseseite in einem Browser, indem Sie die folgende URL aufrufen:

    APISERVER-URL/diagnose
    

    Ersetzen Sie APISERVER_URL durch den vollständig qualifizierten Domainnamen (FQDN) für Ihren Cluster. Beispiel: https://apiserver.example.com.

    Wenn Sie einen Fehler wie den folgenden erhalten:

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

    Hängen Sie den Portnummernwert von :11001 an APISERVER_URL an. Beispiel: https://apiserver.example.com:11001/diagnose

    Auf der Diagnoseseite wird eine Liste der für Ihren Cluster konfigurierten OIDC-Anbieter angezeigt.

  2. Wählen Sie den Anbieter aus, für den Sie eine Fehlerbehebung ausführen möchten.

  3. Melden Sie sich wie gewohnt an.

    Am Ende des Anmeldevorgangs wird im Dienstprogramm eine Seite mit Diagnoseinformationen angezeigt, die Ihnen bei der Fehlerbehebung helfen können.

Anmeldeprobleme mithilfe der Diagnoseseite beheben

Die Diagnoseseite enthält eine Authentifizierungszusammenfassung, die in drei Abschnitte unterteilt ist:

  • Status: Enthält entweder Success oder Failed, je nachdem, ob die Authentifizierung erfolgreich war.

  • Identitätsanbieter: Enthält Details wie Name, Client ID und UserClaim zum Anbieter, der für die Anmeldung verwendet wurde.

  • ID-Token: Enthält Informationen zum ID-Token, das von GKE Identity Service mit dem angegebenen Anbieter abgerufen wurde. Das ID-Token ist ein JSON-Objekt, das eine Reihe von Schlüssel/Wert-Paaren enthält. Schlüssel können iss, aud, sub und email enthalten.

Probleme mit der Authentifizierung beheben

Wenn der Inhalt des Abschnitts Status darauf hinweist, dass die Authentifizierung erfolgreich war, und weiterhin Probleme auftreten, sind möglicherweise fehlende rollenbasierte Zugriffssteuerungen (Role-Based Access Controls, RBACs) die Ursache. Weitere Informationen zur Fehlerbehebung finden Sie unter RBACs for groups not working for OIDC providers.

Fehler bei der Authentifizierung beheben

Wenn der Inhalt des Bereichs Status darauf hinweist, dass die Authentifizierung fehlgeschlagen ist, suchen Sie zuerst nach Inkonsistenzen zwischen den Bereichen Identitätsanbieter und ID-Token.

Hier sind einige Authentifizierungsanforderungen, die Sie prüfen sollten:

  • Wenn das Feld UserClaim in Identity Provider leer ist, muss der Bereich ID-Token ein Feld mit dem Namen sub enthalten. Ein fehlendes sub-Feld deutet darauf hin, dass ein Problem mit dem ID-Token vorliegt.

  • Der Feldwert UserClaim in Identitätsanbieter muss ein Schlüssel im Abschnitt ID-Token sein. Wenn das Feld UserClaim beispielsweise auf email festgelegt ist, muss im ID-Token ein Feld mit dem Namen email vorhanden sein.

  • Der Feldwert GroupsClaim in Identity Provider (Identitätsanbieter) muss ein Schlüssel in ID Token (ID-Token) sein. Wenn das Feld GroupsClaim beispielsweise auf groupsList festgelegt ist (für einen Anbieter, der Gruppen unterstützt), muss im ID-Token ein Feld mit dem Namen groupsList vorhanden sein.

  • Der Feldwert Client ID unter Identitätsanbieter muss im Wert des Felds aud im Bereich ID-Token enthalten sein.

Wenn eine der oben genannten Bedingungen nicht erfüllt ist, finden Sie in einem der folgenden Leitfäden weitere Informationen zur richtigen Konfiguration Ihrer Cluster mit GKE Identity Service:

Protokolle für die weitere Fehlerbehebung verwenden

Die Pod-Logs von GKE Identity Service enthalten zusätzliche Informationen zur Fehlerbehebung. So verwenden Sie GKE Identity Service-Pod-Logs:

  1. Debug-Log für GKE Identity Service aktivieren

  2. Containerlog des GKE Identity Service prüfen.