Utilità di diagnostica di GKE Identity Service

L'utilità di diagnostica del servizio di identità GKE ti aiuta a risolvere i problemi di autenticazione basata su FQDN. Se riscontri difficoltà di autenticazione a 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 individuali con 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 attivarlo:

1. Apri la risorsa personalizzata ClientConfig per la modifica:

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

   Il file manifest dovrebbe essere simile al seguente:

   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. L'ora di scadenza determina quando la funzionalità dell'utilità di diagnostica si disattiva automaticamente. Poiché l'utilità di diagnostica è disponibile per chiunque abbia accesso al cluster, l'impostazione dell'ora di scadenza in modo appropriato contribuisce a garantire che l'utilità non rimanga attiva più del necessario. Quando imposti l'ora di scadenza, ti consigliamo di impostarla a 12 ore nel futuro, anche se qualsiasi ora futura è valida.

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 diagnostiche corrispondenti che puoi utilizzare per risolvere i problemi con un provider specifico.

1. Apri la pagina di diagnostica in un browser andando al seguente URL:

   APISERVER-URL/diagnose
   

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

   Se riscontri un errore di tipo vietato, come il seguente:

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

   Aggiungi il valore del numero di porta :11001 a APISERVER_URL. Ad esempio: https://apiserver.example.com:11001/diagnose.

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

2. Seleziona il fornitore di cui vuoi risolvere i problemi.

3. Accedi come di consueto.

   Al termine della procedura di accesso, l'utilità mostra una pagina con informazioni diagnostiche che possono aiutarti a risolvere i problemi.

Utilizzare la pagina 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 riuscita o meno.

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

• Token ID: contiene informazioni sul token ID recuperato da GKE Identity Service utilizzando il provider specificato. Il token ID è un oggetto JSON che contiene 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 è andata a buon fine e continui a riscontrare problemi, la causa potrebbe essere la mancanza di controlli dell'accesso basato sui ruoli (RBAC). Per ulteriori informazioni sulla risoluzione dei problemi, consulta RBAC per gruppi che non funzionano per i provider OIDC per ulteriori informazioni sulla risoluzione dei problemi.

Risolvere i problemi relativi all'autenticazione non riuscita

Se il contenuto della sezione Stato indica che l'autenticazione non è riuscita, inizia cercando incongruenze tra le sezioni Identity Provider e Token ID.

Ecco alcuni requisiti di autenticazione da controllare:

• 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 Identity Provider deve essere una chiave nella sezione ID Token. Ad esempio, se il campo UserClaim è impostato su email, deve essere presente un campo denominato email in ID Token.

• 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 provider che supporta i gruppi), deve essere presente un campo denominato groupsList nel token ID.

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

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 GKE Identity Service per singoli cluster, consulta le istruzioni per configurare singoli cluster.

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

Utilizzare i log per risolvere ulteriormente i problemi

I log del pod del servizio di identità GKE contengono informazioni di debug aggiuntive. Per utilizzare i log del pod GKE Identity Service:

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

2. Controlla il log del container del servizio di identità GKE.