Autenticarsi alle API Google Cloud dai workload GKE

Questa pagina mostra come accedere in modo più sicuro alle API dai workload eseguiti nei cluster Google Kubernetes Engine (GKE) utilizzando Workload Identity Federation for GKE. Google Cloud

Questa pagina è rivolta agli amministratori di identità e account, agli operatori e agli sviluppatori che creano e gestiscono i criteri relativi alle autorizzazioni utente. Per scoprire di più sui ruoli comuni e sulle attività di esempio a cui facciamo riferimento nei contenuti di Google Cloud , consulta Ruoli utente e attività comuni di GKE.

Prima di leggere questa pagina, assicurati di conoscere i concetti di Workload Identity Federation for GKE.

Prima di iniziare

Prima di iniziare, assicurati di aver eseguito le seguenti operazioni:

  • Attiva l'API Google Kubernetes Engine.
  • Attiva l'API Kubernetes Engine
  • Se vuoi utilizzare Google Cloud CLI per questa attività, installala e poi inizializza gcloud CLI. Se hai già installato gcloud CLI, scarica l'ultima versione eseguendo il comando gcloud components update. Le versioni precedenti di gcloud CLI potrebbero non supportare l'esecuzione dei comandi in questo documento.

Abilita Workload Identity Federation for GKE su cluster e pool di nodi

In Autopilot, Workload Identity Federation for GKE è sempre abilitato. Vai alla sezione Configurare le applicazioni per utilizzare Workload Identity Federation for GKE.

In Standard, puoi abilitare Workload Identity Federation for GKE su cluster e pool di nodi utilizzando Google Cloud CLI o la console Google Cloud . Workload Identity Federation for GKE deve essere abilitato a livello di cluster prima di poter abilitare Workload Identity Federation for GKE sui pool di nodi.

Puoi abilitare Workload Identity Federation for GKE in un cluster Standard esistente utilizzando gcloud CLI o la console Google Cloud . I pool di nodi esistenti non sono interessati, mentre i nuovi pool di nodi nel cluster utilizzano Workload Identity Federation for GKE.

gcloud

  1. Nella console Google Cloud , attiva Cloud Shell.

    Attiva Cloud Shell

    Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.

  2. Per abilitare Workload Identity Federation per GKE in un cluster esistente, esegui il seguente comando:

    gcloud container clusters update CLUSTER_NAME \
        --location=LOCATION \
        --workload-pool=PROJECT_ID.svc.id.goog
    

    Sostituisci quanto segue:

    • CLUSTER_NAME: il nome del cluster esistente.
    • LOCATION: la regione o zona di Compute Engine del control plane del cluster, ad esempio us-central1 o us-central1-a.
    • PROJECT_ID: il tuo ID progetto Google Cloud .

Console

Per abilitare Workload Identity Federation per GKE in un cluster esistente, procedi nel seguente modo:

  1. Vai alla pagina Google Kubernetes Engine nella console Google Cloud .

    Vai a Google Kubernetes Engine

  2. Nell'elenco dei cluster, fai clic sul nome del cluster da modificare.

  3. Nella pagina dei dettagli del cluster, nella sezione Sicurezza, fai clic su Modifica Workload Identity.

  4. Nella finestra di dialogo Modifica Workload Identity, seleziona la casella di controllo Abilita Workload Identity.

  5. Fai clic su Salva modifiche.

Eseguire la migrazione dei carichi di lavoro esistenti a Workload Identity Federation for GKE

Dopo aver abilitato Workload Identity Federation for GKE su un cluster esistente, potresti voler eseguire la migrazione dei carichi di lavoro in esecuzione per utilizzare Workload Identity Federation for GKE. Seleziona la strategia di migrazione ideale per il tuo ambiente. Puoi creare nuovi pool di nodi con Workload Identity Federation for GKE abilitata oppure aggiornare i pool di nodi esistenti per abilitare Workload Identity Federation for GKE.

Puoi abilitare Workload Identity Federation for GKE su un pool di nodi solo se Workload Identity Federation for GKE è abilitato sul cluster.

Best practice:

Crea nuovi pool di nodi se devi anche modificare le tue applicazioni per renderle compatibili con Workload Identity Federation for GKE.

Per impostazione predefinita, tutti i nuovi node pool che crei utilizzano Workload Identity Federation for GKE se il cluster ha abilitato Workload Identity Federation for GKE. Per creare un nuovo pool di nodi con Workload Identity Federation for GKE abilitata, esegui questo comando:

gcloud container node-pools create NODEPOOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --workload-metadata=GKE_METADATA

Sostituisci quanto segue:

  • NODEPOOL_NAME: il nome del nuovo pool di nodi.
  • CLUSTER_NAME: il nome del cluster esistente con Workload Identity Federation for GKE abilitata.
  • CONTROL_PLANE_LOCATION: la regione o zona di Compute Engine del control plane del cluster, ad esempio us-central1 o us-central1-a.

Il flag --workload-metadata=GKE_METADATA configura il pool di nodi in modo che utilizzi il server metadati GKE.

Best practice:

Includi il flag in modo che la creazione pool di nodi non riesca se Workload Identity Federation for GKE non è abilitata sul cluster.

Aggiornare un pool di nodi esistente

Puoi abilitare manualmente Workload Identity Federation for GKE sui pool di nodi esistenti dopo aver abilitato Workload Identity Federation for GKE sul cluster.

gcloud

  1. Nella console Google Cloud , attiva Cloud Shell.

    Attiva Cloud Shell

    Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.

  2. Per modificare un pool di nodi esistente in modo che utilizzi Workload Identity Federation for GKE, esegui il seguente comando:

    gcloud container node-pools update NODEPOOL_NAME \
        --cluster=CLUSTER_NAME \
        --location=CONTROL_PLANE_LOCATION \
        --workload-metadata=GKE_METADATA
    

    Se un cluster ha abilitato Workload Identity Federation for GKE, puoi disabilitarla selettivamente su un pool di nodi specifico specificando esplicitamente --workload-metadata=GCE_METADATA.

Console

Per modificare un pool di nodi esistente in modo che utilizzi Workload Identity Federation for GKE, segui questi passaggi:

  1. Vai alla pagina Google Kubernetes Engine nella console Google Cloud .

    Vai a Google Kubernetes Engine

  2. Nell'elenco dei cluster, fai clic sul nome del cluster da modificare.

  3. Fai clic sulla scheda Nodi.

  4. Nella sezione Pool di nodi, fai clic sul nome del pool di nodi che vuoi modificare.

  5. Nella pagina Dettagli del pool di nodi, fai clic su Modifica.

  6. Nella pagina Modifica pool di nodi, nella sezione Sicurezza, seleziona la casella di controllo Abilita server metadati GKE.

  7. Fai clic su Salva.

Configura le applicazioni per utilizzare Workload Identity Federation for GKE

Per consentire alle tue applicazioni GKE di autenticarsi nelle API utilizzando Workload Identity Federation for GKE, crea criteri IAM per le API specifiche. Google CloudL'entità in queste policy è un identificatore dell'entità IAM che corrisponde ai carichi di lavoro, agli spazi dei nomi o ai service account Kubernetes. Questo processo restituisce un token di accesso federato che il tuo workload può utilizzare nelle chiamate API.

In alternativa, puoi configurare i service account Kubernetes per impersonare i service account IAM, il che configura GKE per scambiare il token di accesso federato con un token di accesso dall'API Service Account Credentials IAM. Per maggiori dettagli, consulta la sezione Alternativa: collega Service Account Kubernetes a IAM.

Configurare l'autorizzazione e i principal

  1. Recupera le credenziali per il tuo cluster:

    gcloud container clusters get-credentials CLUSTER_NAME \
        --location=CONTROL_PLANE_LOCATION
    

    Sostituisci quanto segue:

    • CLUSTER_NAME: il nome del cluster in cui è abilitata Workload Identity Federation per GKE.
    • CONTROL_PLANE_LOCATION: la regione o zona di Compute Engine del control plane del cluster, ad esempio us-central1 o us-central1-a.
  2. Crea uno spazio dei nomi da utilizzare per il account di servizio Kubernetes. Puoi anche utilizzare lo spazio dei nomi default o qualsiasi spazio dei nomi esistente.

    kubectl create namespace NAMESPACE
    
  3. Crea un service account Kubernetes da utilizzare per la tua applicazione. Puoi utilizzare anche qualsiasi ServiceAccount Kubernetes esistente in qualsiasi spazio dei nomi. Se non assegni un ServiceAccount al tuo carico di lavoro, Kubernetes assegna il ServiceAccount default nello spazio dei nomi.

    kubectl create serviceaccount KSA_NAME \
        --namespace NAMESPACE
    

    Sostituisci quanto segue:

    • KSA_NAME: il nome del nuovo ServiceAccount Kubernetes.
    • NAMESPACE: il nome dello spazio dei nomi Kubernetes per il service account.
  4. Crea un criterio di autorizzazione IAM che faccia riferimento a Kubernetes ServiceAccount. Come best practice, concedi le autorizzazioni a risorseGoogle Cloud specifiche a cui la tua applicazione deve accedere. Devi disporre delle autorizzazioni IAM pertinenti per creare policy di autorizzazione nel tuo progetto.

    Ad esempio, il seguente comando concede il ruolo Visualizzatore cluster Kubernetes Engine (roles/container.clusterViewer) al service account che hai creato:

    gcloud projects add-iam-policy-binding projects/PROJECT_ID \
        --role=roles/container.clusterViewer \
        --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME \
        --condition=None
    

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo ID progetto Google Cloud .
    • PROJECT_NUMBER: il numero di progetto Google Cloud numerico.

    Puoi concedere ruoli su qualsiasi risorsa Google Cloud che supporta le policy di autorizzazione IAM. La sintassi dell'identificatore dell'entità dipende dalla risorsa Kubernetes. Per un elenco degli identificatori supportati, consulta Identificatori delle entità per Workload Identity Federation for GKE.

(Facoltativo) Configura le opzioni mesh di servizi

Se utilizzi Istio o Cloud Service Mesh per gestire il tuo ambiente, aggiungi la seguente annotazione al campo metadata.annotations nella specifica del pod:

metadata:
  annotations:
    proxy.istio.io/config: '{ "holdApplicationUntilProxyStarts": true }'

Questa annotazione impedisce l'avvio dei container finché il proxy mesh di servizi non è pronto a reindirizzare il traffico dalle tue applicazioni.

Verifica la configurazione di Workload Identity Federation for GKE

In questa sezione, creerai un bucket Cloud Storage e concederai l'accesso in visualizzazione al bucket al ServiceAccount Kubernetes che hai creato nella sezione precedente. Poi esegui il deployment di un workload e verifica che il container possa elencare i cluster nel progetto.

  1. Crea un bucket Cloud Storage vuoto:

    gcloud storage buckets create gs://BUCKET
    

    Sostituisci BUCKET con un nome per il nuovo bucket.

  2. Concedi il ruolo Storage Object Viewer (roles/storage.objectViewer) al service account che hai creato:

    gcloud storage buckets add-iam-policy-binding gs://BUCKET \
        --role=roles/storage.objectViewer \
        --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME \
        --condition=None
    

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo ID progetto Google Cloud .
    • PROJECT_NUMBER: il numero di progetto Google Cloud numerico.
    • NAMESPACE: lo spazio dei nomi Kubernetes che contiene il service account.
    • KSA_NAME: il nome di ServiceAccount.
  3. Salva il seguente manifest come test-app.yaml:

    apiVersion: v1
    kind: Pod
    metadata:
      name: test-pod
      namespace: NAMESPACE
    spec:
      serviceAccountName: KSA_NAME
      containers:
      - name: test-pod
        image: google/cloud-sdk:slim
        command: ["sleep","infinity"]
        resources:
          requests:
            cpu: 500m
            memory: 512Mi
            ephemeral-storage: 10Mi
    
  4. Solo nei cluster Standard, aggiungi quanto segue al campo template.spec per posizionare i pod nei pool di nodi che utilizzano Workload Identity Federation for GKE.

    Salta questo passaggio nei cluster Autopilot, che rifiutano questo nodeSelector perché ogni nodo utilizza Workload Identity Federation for GKE.

    spec:
      nodeSelector:
        iam.gke.io/gke-metadata-server-enabled: "true"
    
  5. Applica la configurazione al cluster:

    kubectl apply -f test-app.yaml
    
  6. Attendi che il pod sia pronto. Per controllare lo stato del pod, esegui il comando seguente:

    kubectl get pods --namespace=NAMESPACE
    

    Quando il pod è pronto, l'output è simile al seguente:

    NAME       READY   STATUS    RESTARTS   AGE
    test-pod   1/1     Running   0          5m27s
    
  7. Apri una sessione shell nel pod:

    kubectl exec -it pods/test-pod --namespace=NAMESPACE -- /bin/bash
    
  8. Recupera un elenco di oggetti nel bucket:

    curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        "https://storage.googleapis.com/storage/v1/b/BUCKET/o"
    

    L'output è il seguente:

    {
      "kind": "storage#objects"
    }
    

    Questo output mostra che il pod può accedere agli oggetti nel bucket.

Alternativa: collega i service account Kubernetes a IAM

Best practice:

Utilizza gli identificatori delle entità IAM per configurare Workload Identity Federation for GKE. Tuttavia, questa identità federata presenta limitazioni specifiche per ogni API Google Cloud supportata. Se queste limitazioni ti riguardano, segui i passaggi seguenti per configurare l'accesso a queste API dai tuoi carichi di lavoro GKE.

  1. Crea uno spazio dei nomi Kubernetes:

    kubectl create namespace NAMESPACE
    
  2. Crea un ServiceAccount Kubernetes:

    kubectl create serviceaccount KSA_NAME \
        --namespace=NAMESPACE
    
  3. Crea un account di servizio IAM. Puoi anche utilizzare qualsiasi account di servizio IAM esistente in qualsiasi progetto della tua organizzazione.

    gcloud iam service-accounts create IAM_SA_NAME \
        --project=IAM_SA_PROJECT_ID
    

    Sostituisci quanto segue:

    • IAM_SA_NAME: un nome per il nuovo account di servizio IAM.
    • IAM_SA_PROJECT_ID: l'ID progetto per il tuo account di serviziot IAM.

    Per informazioni sull'autorizzazione dei service account IAM ad accedere alle API Google Cloud, consulta Informazioni sui service account.

  4. Concedi al tuo account di servizio IAM i ruoli necessari per API Google Cloud specifiche:

    gcloud projects add-iam-policy-binding IAM_SA_PROJECT_ID \
        --member "serviceAccount:IAM_SA_NAME@IAM_SA_PROJECT_ID.iam.gserviceaccount.com" \
        --role "ROLE_NAME"
    

    Sostituisci ROLE_NAME con il nome del ruolo, ad esempio roles/spanner.viewer.

  5. Crea un criterio di autorizzazione IAM che conceda al service account Kubernetes l'accesso per rappresentare il account di servizio IAM:

    gcloud iam service-accounts add-iam-policy-binding IAM_SA_NAME@IAM_SA_PROJECT_ID.iam.gserviceaccount.com \
        --role roles/iam.workloadIdentityUser \
        --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME]"
    

    Il nome del membro deve includere lo spazio dei nomi e il nome ServiceAccount di Kubernetes. Ad esempio, serviceAccount:example-project.svc.id.goog[example-namespace/example-serviceaccount].

  6. Aggiungi un'annotazione all'account di servizio Kubernetes in modo che GKE veda il collegamento tra gli account di servizio:

    kubectl annotate serviceaccount KSA_NAME \
        --namespace NAMESPACE \
        iam.gke.io/gcp-service-account=IAM_SA_NAME@IAM_SA_PROJECT_ID.iam.gserviceaccount.com
    

    Quando utilizzi questo metodo, sono necessarie sia la policy IAM allow che l'annotazione.

  7. (Facoltativo) Annota il service account Kubernetes in modo che le tue applicazioni ottengano l'identificatore nella sintassi dell'identificatore dell'entità IAM:

    kubectl annotate serviceaccount KSA_NAME \
        --namespace=NAMESPACE \
        iam.gke.io/return-principal-id-as-email="true"
    

Utilizzare Workload Identity Federation per GKE dal codice

L'autenticazione ai servizi Google Cloud dal codice è la stessa procedura dell'autenticazione tramite il server di metadati di Compute Engine. Quando utilizzi Workload Identity Federation for GKE, le tue richieste al server dei metadati dell'istanza vengono indirizzate al server dei metadati GKE. Il codice esistente che esegue l'autenticazione utilizzando il server dei metadati dell'istanza (ad esempio il codice che utilizza le librerie clientGoogle Cloud ) dovrebbe funzionare senza modifiche.

Utilizzare la quota di un altro progetto con Workload Identity Federation for GKE

Nei cluster che eseguono GKE versione 1.24 o successive, puoi configurare facoltativamente il account di servizio Kubernetes in modo che utilizzi la quota di un progetto Google Cloud diverso quando effettua chiamate ai metodi GenerateAccessToken e GenerateIdToken nell'API Service Account Credentials. In questo modo puoi evitare di utilizzare l'intera quota nel progetto principale e utilizzare invece la quota di altri progetti per questi servizi nel cluster.

Per configurare un progetto quota con Workload Identity Federation for GKE, procedi nel seguente modo:

  1. Concedi l'autorizzazione serviceusage.services.use sul progetto di quota al account di servizio Kubernetes.

    gcloud projects add-iam-policy-binding QUOTA_PROJECT_ID \
        --role=roles/serviceusage.serviceUsageConsumer \
        --member='principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME' \
    

    Sostituisci QUOTA_PROJECT_ID con l'ID progetto del progetto di quota.

  2. Annota il account di servizio Kubernetes con il progetto quota:

    kubectl annotate serviceaccount KSA_NAME \
        --namespace NAMESPACE \
        iam.gke.io/credential-quota-project=QUOTA_PROJECT_ID
    

Per verificare che la configurazione funzioni correttamente:

  1. Crea un pod e avvia una sessione shell. Consulta la documentazione di Kubernetes per ottenere una shell per un container in esecuzione.

  2. Effettua una richiesta al server di metadati:

    curl -H "Metadata-Flavor: Google" http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/token
    
  3. Vai alla pagina API IAM Service Accounts Credentials nella console Google Cloud per il tuo progetto di quota:

    Vai alle API

  4. Controlla se sono state apportate modifiche al traffico.

Esegui la pulizia

Per interrompere l'utilizzo di Workload Identity Federation for GKE, revoca l'accesso al account di servizio IAM e disabilita Workload Identity Federation for GKE sul cluster.

Revoca l'accesso

Per revocare l'accesso all'entità, rimuovi la policy di autorizzazione IAM che hai creato nella sezione Configurare le applicazioni per utilizzare Workload Identity Federation for GKE.

Ad esempio, per revocare l'accesso a un repository Artifact Registry, esegui questo comando:

gcloud artifacts repositories remove-iam-policy-binding REPOSITORY_NAME \
    --location=REPOSITORY_LOCATION \
    --member='principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME' \
    --role='roles/artifactregistry.reader' \
    --all

Disabilita Workload Identity Federation per GKE

Puoi disattivare Workload Identity Federation for GKE solo sui cluster Standard.

gcloud

  1. Nella console Google Cloud , attiva Cloud Shell.

    Attiva Cloud Shell

    Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.

  2. Disabilita Workload Identity Federation per GKE su ogni pool di nodi:

    gcloud container node-pools update NODEPOOL_NAME \
        --cluster=CLUSTER_NAME \
        --location=CONTROL_PLANE_LOCATION \
        --workload-metadata=GCE_METADATA
    

    Ripeti questo comando per ogni pool di nodi nel cluster.

  3. Disabilita Workload Identity Federation per GKE nel cluster:

    gcloud container clusters update CLUSTER_NAME \
        --location=CONTROL_PLANE_LOCATION \
        --disable-workload-identity
    

Console

  1. Vai alla pagina Google Kubernetes Engine nella console Google Cloud .

    Vai a Google Kubernetes Engine

  2. Nell'elenco dei cluster, fai clic sul nome del cluster da modificare.

  3. Fai clic sulla scheda Nodi.

  4. Per disabilitare Workload Identity Federation for GKE su ciascun pool di nodi, procedi nel modo seguente per ciascun pool di nodi nella sezione Node pool:

    1. Fai clic sul nome del pool di nodi da modificare.
    2. Nella pagina Dettagli del pool di nodi, fai clic su Modifica.
    3. Nella pagina Modifica pool di nodi, nella sezione Sicurezza, deseleziona la casella di controllo Abilita server metadati GKE.
    4. Fai clic su Salva.
  5. Per disabilitare Workload Identity Federation for GKE per il cluster, procedi nel seguente modo:

    1. Fai clic sulla scheda Dettagli.
    2. Nella sezione Sicurezza, accanto a Workload Identity, fai clic su Modifica.
    3. Nella finestra di dialogo Modifica Workload Identity, deseleziona la casella di controllo Abilita Workload Identity.
    4. Fai clic su Salva modifiche.

Disabilita Workload Identity Federation for GKE nella tua organizzazione

I passaggi descritti nella sezione Collega i service account Kubernetes a IAM consentono ai service account Kubernetes di rappresentare l'identità del account di servizio IAM collegato. I token API di lunga durata per i service account Kubernetes possono essere scambiati con i token di accesso al service account IAM corrispondenti.

Potresti voler disabilitare Workload Identity Federation for GKE per i cluster nella tua organizzazione, cartella o progetto quando vuoi isolare i workload dai service account IAM. Ad esempio, se prevedi di disabilitare account di servizio account o disabilitare la creazione di chiavi account di servizio account, la disattivazione di Workload Identity Federation for GKE impedisce lo scambio di token ServiceAccount con token di accesso al account di servizio IAM.

Per maggiori informazioni, vedi Disabilita la creazione di cluster di identità del workload.

Risoluzione dei problemi

Per informazioni sulla risoluzione dei problemi, consulta Risoluzione dei problemi relativi a Workload Identity Federation for GKE.

Passaggi successivi