Utilità di diagnostica di GKE Identity Service

L'utilità di diagnostica di GKE Identity Service ti aiuta a risolvere i problemi di autenticazione basata su FQDN. Se hai difficoltà ad autenticarti in un cluster utilizzando un provider OIDC specifico, puoi attivare lo strumento e utilizzarlo per identificare rapidamente i problemi di configurazione simulando i flussi di accesso con il tuo provider OIDC.

L'utilità di diagnostica è disponibile solo su cluster singoli che eseguono GKE Enterprise 1.32 o versioni successive e supporta solo OIDC.

Attivare l'utilità di diagnostica

L'utilità di diagnostica è disattivata per impostazione predefinita e deve essere attivata prima di poterla utilizzare per la risoluzione dei problemi. Per attivarla, segui queste istruzioni:

1. Apri la risorsa personalizzata ClientConfig per la modifica:

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

   Il file manifest dovrebbe avere il seguente aspetto:

   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. Come mostrato nell'esempio seguente, aggiungi una sezione identityServiceOptions al manifest ClientConfig per specificare la configurazione dell'utilità di diagnostica:

   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
   

   Sostituisci TIMESTAMP con una scadenza nel formato RFC 3339. Ad esempio, 2025-05-01T17:05:00Z. La data e l'ora di scadenza determinano quando la funzionalità dell'utilità di diagnostica viene disattivata automaticamente. Poiché l'utilità di diagnostica è disponibile per chiunque abbia accesso al cluster, l'impostazione della data e dell'ora di scadenza in modo appropriato contribuisce a garantire che l'utilità non rimanga attiva più a lungo del necessario. Quando imposti la data e l'ora di scadenza, ti consigliamo di impostarla su 12 ore nel futuro, anche se è valida qualsiasi data e ora futura.

3. Salva le modifiche ed esci dall'editor di testo per applicare il manifest al cluster.

Utilizzare l'utilità di diagnostica per simulare un accesso

Una volta attivata l'utilità di diagnostica, puoi simulare un evento di accesso e ottenere le informazioni di diagnostica corrispondenti che puoi utilizzare per risolvere i problemi relativi a un provider specifico.

1. Apri la pagina di diagnostica in un browser visitando il seguente URL:

   APISERVER-URL/diagnose
   

   Sostituisci APISERVER_URL con il nome di dominio completo (FQDN) del tuo cluster. Ad esempio, https://apiserver.example.com.

   La pagina di diagnostica mostra un elenco di provider OIDC configurati per il tuo cluster.

2. Seleziona il fornitore per il quale vuoi risolvere i problemi.

3. Accedi normalmente.

   Al termine della procedura di accesso, l'utilità mostra una pagina con informazioni di diagnostica che possono aiutarti a risolvere il problema.

Utilizzare la pagina di diagnostica per risolvere i problemi di accesso

La pagina di diagnostica fornisce un riepilogo dell'autenticazione, suddiviso in tre sezioni:

• Stato: contiene Success o Failed, a seconda che l'autenticazione sia andata a buon fine o meno.

• Provider di identità: contiene dettagli, ad esempio Name, Client ID e UserClaim, relativi al provider utilizzato per accedere.

• Token ID: contiene informazioni sul token ID recuperato da GKE Identity Service utilizzando il provider specificato. Il token di identità è un oggetto JSON contenente un insieme di coppie chiave-valore. Le chiavi potrebbero includere iss, aud, sub e email.

Risolvere i problemi relativi all'autenticazione riuscita

Se i contenuti della sezione Stato indicano che l'autenticazione è riuscita e continui a riscontrare problemi, la causa potrebbe essere la mancanza di controlli di accesso basati sui ruoli (RBAC). Per ulteriori informazioni sulla risoluzione dei problemi, consulta I gruppi RBAC non funzionano per i fornitori OIDC.

Risolvere i problemi di autenticazione

Se i contenuti della sezione Stato indicano che l'autenticazione non è andata a buon fine, inizia cercando incoerenze tra le sezioni Identity Provider e Token ID.

Ecco alcuni requisiti di autenticazione che dovresti verificare:

• Se il campo UserClaim in Identity Provider è vuoto, la sezione ID Token deve contenere un campo denominato sub. Un campo sub mancante indica che si è verificato un problema con il token ID.

• Il valore del campo UserClaim in Provider di identità deve essere una chiave nella sezione Token ID. Ad esempio, se il campo UserClaim è impostato su email, in Token ID deve essere presente un campo denominato email.

• Il valore del campo GroupsClaim in Identity Provider deve essere una chiave in ID Token. Ad esempio, se il campo GroupsClaim è impostato su groupsList (per un fornitore che supporta i gruppi), deve essere presente un campo denominato groupsList in Token ID.

• Il valore del campo Client ID in Identity Provider deve essere contenuto nel valore del campo aud nella sezione Token ID.

Se una delle condizioni precedenti non è soddisfatta, consulta una delle seguenti guide per ulteriori dettagli su come configurare correttamente i cluster con GKE Identity Service:

• Se configuri il servizio GKE Identity per singoli cluster, consulta le istruzioni per configurare i singoli cluster.

• Se configuri GKE Identity Service a livello di parco risorse, consulta le istruzioni per configurare un parco risorse di cluster.

Utilizzare i log per ulteriori operazioni di risoluzione dei problemi

I log del pod GKE Identity Service contengono ulteriori informazioni di debug. Per utilizzare i log del pod GKE Identity Service:

1. Attiva il log di debug di GKE Identity Service.

2. Controlla il log del contenitore di GKE Identity Service.