Configura i service account dei nodi GKE

I nodi Google Kubernetes Engine (GKE) utilizzano service account Identity and Access Management (IAM) per attività come la registrazione e il pull delle immagini container per i carichi di lavoro. Questo documento mostra agli amministratori della piattaforma e agli esperti di sicurezza come concedere ruoli ai service account per casi d'uso specifici e come creare service account personalizzati anziché utilizzare un account di servizio predefinito. Per saperne di più, consulta Service account dei nodi.

Prima di iniziare

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

• Attiva l'API Google Kubernetes Engine.
Attiva l'API Google 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.
  Nota: per le installazioni esistenti di gcloud CLI, assicurati di impostare la proprietà compute/region. Se utilizzi principalmente cluster zonali, imposta invece compute/zone. Se imposti una località predefinita, puoi evitare errori in gcloud CLI come il seguente: One of [--zone, --region] must be supplied: Please specify location. Potresti dover specificare la posizione in determinati comandi se la posizione del cluster è diversa da quella predefinita che hai impostato.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per gestire i ruoli e i service account IAM, chiedi all'amministratore di concederti i seguenti ruoli IAM:

• Security Admin (roles/iam.securityAdmin) sul progetto cluster
• Configura i service account in un progetto separato: Amministratore della sicurezza (roles/iam.securityAdmin) nel progetto del account di servizio

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Concedi il ruolo minimo richiesto per GKE

GKE utilizza i service account IAM collegati ai nodi per eseguire attività di sistema come il logging e il monitoraggio. Come minimo, questi service account nodo devono avere il ruolo Kubernetes Engine Default Node Service Account (roles/container.defaultNodeServiceAccount) sul tuo progetto. Per impostazione predefinita, GKE utilizza l'account di servizio predefinito di Compute Engine, che viene creato automaticamente nel tuo progetto, come service account del nodo.

Se la tua organizzazione applica il vincolo del criterio dell'organizzazione iam.automaticIamGrantsForDefaultServiceAccounts, ilaccount di serviziot Compute Engine predefinito nel tuo progetto potrebbe non ottenere automaticamente le autorizzazioni richieste per GKE.

Nota: se la tua organizzazione è stata creata a partire dal 3 maggio 2024, questo vincolo viene imposto per impostazione predefinita.

Le sezioni seguenti mostrano come concedere il ruolo roles/container.defaultNodeServiceAccount al account di servizio Compute Engine predefinito o a un nuovo account di servizio personalizzato che crei.

Best practice:

Crea un account di servizio personalizzato per i nodi anziché utilizzare quello predefinito di Compute Engine.

Configura il account di servizio Compute Engine predefinito

Per concedere il ruolo roles/container.defaultNodeServiceAccount al account di servizio predefinito di Compute Engine, completa i seguenti passaggi:

Console

1. Vai alla pagina Benvenuto:

   Vai a Benvenuto

2. Nel campo Numero progetto, fai clic su Copia negli appunti.
3. Vai alla pagina IAM:

   Vai a IAM

4. Fai clic su Concedi l'accesso.
5. Nel campo Nuove entità, specifica il seguente valore:

   [e-mail]

   Sostituisci PROJECT_NUMBER con il numero di progetto che hai copiato.
6. Nel menu Seleziona un ruolo, seleziona il ruolo Kubernetes Engine Default Node Service Account.
7. Fai clic su Salva.

gcloud

1. Trova il numero del tuo progetto Google Cloud :

   gcloud projects describe PROJECT_ID \
       --format="value(projectNumber)"

   Sostituisci PROJECT_ID con l'ID progetto.

   L'output è simile al seguente:

   12345678901
   

2. Concedi il ruolo roles/container.defaultNodeServiceAccount all'account di servizio predefinito di Compute Engine:

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:[e-mail]" \
       --role="roles/container.defaultNodeServiceAccount"

   Sostituisci PROJECT_NUMBER con il numero di progetto del passaggio precedente.

Configura un account di servizio del nodo personalizzato

Per creare un account di servizio personalizzato e concedergli il ruolo richiesto per GKE, completa i seguenti passaggi:

Console

1. Vai alla pagina Service Accounts:

   Vai ad Account di servizio

2. Fai clic su Crea service account.
3. Inserisci un nome per il account di servizio. Il campo ID service account genera automaticamente un ID univoco per il account di servizio in base al nome.
4. Fai clic su Crea e continua.
5. Nel menu Seleziona un ruolo, seleziona il ruolo Service account predefinito del nodo Kubernetes Engine.
6. Fai clic su Fine.

gcloud

1. Crea l'account di servizio:

   gcloud iam service-accounts create SA_NAME

   SostituisciSA_NAME con un nome univoco che identifica il service account.

2. Concedi il ruolo Kubernetes Engine Default Node Service Account (roles/container.defaultNodeServiceAccount) al account di servizio:

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
       --role=roles/container.defaultNodeServiceAccount

   Sostituisci quanto segue:

   • PROJECT_ID: il tuo ID progetto Google Cloud .
   • SA_NAME: il nome del account di servizio che hai creato.

Terraform

Crea un account di servizio IAM e concedigli il ruolo roles/container.defaultNodeServiceAccount nel progetto:

resource "google_service_account" "default" {
  account_id   = "gke-node-service-account"
  display_name = "GKE node service account"
}

data "google_project" "project" {
}

resource "google_project_iam_member" "default" {
  project = data.google_project.project.project_id
  role    = "roles/container.defaultNodeServiceAccount"
  member  = "serviceAccount:${google_service_account.default.email}"
}

Config Connector

Nota: questo passaggio richiede Config Connector. Segui le istruzioni di installazione per installare Config Connector sul cluster.

1. Per creare il account di servizio, scarica la seguente risorsa come service-account.yaml:
   apiVersion: iam.cnrm.cloud.google.com/v1beta1
   kind: IAMServiceAccount
   metadata:
     name: [SA_NAME]
   spec:
     displayName: [DISPLAY_NAME]

   Sostituisci quanto segue:

   • [SA_NAME]: il nome del nuovo account di servizio.
   • [DISPLAY_NAME]: un nome visualizzato per il account di servizio.
2. Crea l'account di servizio:

   kubectl apply -f service-account.yaml

3. Applica il ruolo roles/logging.logWriter al account di servizio:
   1. Scarica la seguente risorsa come policy-logging.yaml.
      apiVersion: iam.cnrm.cloud.google.com/v1beta1
      kind: IAMPolicyMember
      metadata:
        name: policy-logging
      spec:
        member: serviceAccount:[SA_NAME]@[PROJECT_ID].iam.gserviceaccount.com
        role: roles/logging.logWriter
        resourceRef:
          kind: Project
          name: [PROJECT_ID]

      Sostituisci quanto segue:

      • [SA_NAME]: il nome del account di servizio.
      • [PROJECT_ID]: il tuo ID progetto Google Cloud .
   2. Applica il ruolo al account di servizio:

      kubectl apply -f policy-logging.yaml

4. Applica il ruolo roles/monitoring.metricWriter al account di servizio:
   1. Scarica la seguente risorsa come policy-metrics-writer.yaml. Sostituisci [SA_NAME] e [PROJECT_ID] con le tue informazioni.
      apiVersion: iam.cnrm.cloud.google.com/v1beta1
      kind: IAMPolicyMember
      metadata:
        name: policy-metrics-writer
      spec:
        member: serviceAccount:[SA_NAME]@[PROJECT_ID].iam.gserviceaccount.com
        role: roles/monitoring.metricWriter
        resourceRef:
          kind: Project
          name: [PROJECT_ID]

      Sostituisci quanto segue:

      • [SA_NAME]: il nome del account di servizio.
      • [PROJECT_ID]: il tuo ID progetto Google Cloud .
   2. Applica il ruolo al account di servizio:

      kubectl apply -f policy-metrics-writer.yaml

5. Applica il ruolo roles/monitoring.viewer al account di servizio:
   1. Scarica la seguente risorsa come policy-monitoring.yaml.
      apiVersion: iam.cnrm.cloud.google.com/v1beta1
      kind: IAMPolicyMember
      metadata:
        name: policy-monitoring
      spec:
        member: serviceAccount:[SA_NAME]@[PROJECT_ID].iam.gserviceaccount.com
        role: roles/monitoring.viewer
        resourceRef:
          kind: Project
          name: [PROJECT_ID]

      Sostituisci quanto segue:

      • [SA_NAME]: il nome del account di servizio.
      • [PROJECT_ID]: il tuo ID progetto Google Cloud .
   2. Applica il ruolo al account di servizio:

      kubectl apply -f policy-monitoring.yaml

6. Applica il ruolo roles/autoscaling.metricsWriter al account di servizio:
   1. Scarica la seguente risorsa come policy-autoscaling-metrics-writer.yaml.
      apiVersion: iam.cnrm.cloud.google.com/v1beta1
      kind: IAMPolicyMember
      metadata:
        name: policy-autoscaling-metrics-writer
      spec:
        member: serviceAccount:[SA_NAME]@[PROJECT_ID].iam.gserviceaccount.com
        role: roles/autoscaling.metricsWriter
        resourceRef:
          kind: Project
          name: [PROJECT_ID]

      Sostituisci quanto segue:

      • [SA_NAME]: il nome del account di servizio.
      • [PROJECT_ID]: il tuo ID progetto Google Cloud .
   2. Applica il ruolo al account di servizio:

      kubectl apply -f policy-autoscaling-metrics-writer.yaml

Puoi utilizzare questo account di servizio anche per le risorse in altri progetti. Per le istruzioni, vedi Abilitare la simulazione dell'identità dei account di servizio tra progetti.

Consenti alle entità di collegare service account personalizzati

Puoi collegare un account di servizio personalizzato quando crei un cluster o un node pool. Per consentire a un'entità (ad esempio un amministratore della piattaforma) di utilizzare un service account personalizzato per creare risorse GKE, concedi a questa entità il ruolo Utente service account (roles/iam.serviceAccountUser) sul service account personalizzato. Per concedere questo ruolo, seleziona una delle seguenti opzioni:

Console

1. Nella console Google Cloud , vai alla pagina Service account:

   Vai ad Account di servizio

   Nel selettore delle risorse, scegli il progetto che contiene il tuo account di servizio personalizzato.

2. Seleziona la casella di controllo per il account di servizio personalizzato che hai creato da utilizzare con i nodi GKE.

3. Fai clic su Gestisci accesso. Viene visualizzato il riquadro Gestisci accesso.

4. Fai clic su Aggiungi entità. Viene visualizzato il riquadro Concedi l'accesso.

5. Nel campo Nuove entità, specifica l'entità, ad esempio un gruppo di amministratori.

6. Nel menu a discesa Seleziona un ruolo, seleziona il ruolo Utente service account.

7. Fai clic su Salva. Il riquadro Concedi l'accesso si chiude.

8. Chiudi il riquadro Gestisci accesso.

gcloud

Concedi il ruolo roles/iam.serviceAccountUser:

gcloud iam service-accounts add-iam-policy-binding \
    SA_NAME@SERVICE_ACCOUNT_PROJECT_ID.iam.gserviceaccount.com \
    --member=PRINCIPAL \
    --role=roles/iam.serviceAccountUser

Sostituisci quanto segue:

• SA_NAME: il nome del account di servizio personalizzato.
• SERVICE_ACCOUNT_PROJECT_ID: l'ID progetto che contiene il account di servizio personalizzato.
• PRINCIPAL: l'identificatore dell'entità, ad esempio user:[e-mail].

Config Connector

Nota: questo passaggio richiede Config Connector. Segui le istruzioni di installazione per installare Config Connector sul cluster.

Applica il ruolo iam.serviceAccountUser al tuo account di servizio. Scarica la risorsa seguente come policy-service-account-user.yaml. Sostituisci [SA_NAME] e [PROJECT_ID] con le tue informazioni.

apiVersion: iam.cnrm.cloud.google.com/v1beta1
kind: IAMPolicyMember
metadata:
  name: policy-service-account-user
spec:
  member: serviceAccount:[SA_NAME]@[PROJECT_ID].iam.gserviceaccount.com
  role: roles/iam.serviceAccountUser
  resourceRef:
    kind: Project
    name: [PROJECT_ID]

kubectl apply -f policy-service-account-user.yaml

Dopo aver concesso il ruolo al account di servizio, questi principal possono utilizzare il account di servizio per creare cluster e pool di nodi. Per saperne di più, consulta i seguenti documenti:

• Creare un cluster Autopilot
• Creazione di un cluster regionale
• Aggiungi un pool di nodi a un cluster standard

Configura l'utilizzo dei account di servizio tra i progetti

Se l'account di servizio del nodo non si trova nello stesso progetto del cluster, gli agenti di servizio nel progetto del cluster hanno bisogno di autorizzazioni aggiuntive per l'account di servizio. Per saperne di più, vedi Service account dei nodi e service agent del progetto.

Per concedere i ruoli richiesti agli service account dei nodi che non si trovano nel progetto del cluster:

1. Per attivare l'associazione di account di servizio tra progetti, aggiorna le policy dell'organizzazione.

2. Per concedere i ruoli richiesti al account di servizio personalizzato agli agenti di servizio nel progetto cluster, seleziona una delle seguenti opzioni:

   Console

   1. Nella Google Cloud console, vai alla pagina Service account.

      Vai ad Account di servizio

   2. Seleziona la casella di controllo per il account di servizio personalizzato che hai creato da utilizzare con i nodi GKE.

   3. Fai clic su Gestisci accesso. Viene visualizzato il riquadro Gestisci accesso.

   4. Concedi il ruolo Creatore token account di servizio all'agente di servizio Compute Engine nel progetto cluster:

      1. Nel riquadro Gestisci accesso, fai clic su Aggiungi entità. Viene visualizzato il riquadro Concedi l'accesso.

      2. Nel campo Nuove entità, specifica l'indirizzo email dell'agente di servizio Compute Engine nel progetto cluster:

         [e-mail]
         

         Sostituisci CLUSTER_PROJECT_NUMBER con il numero di progetto del tuo progetto cluster.

      3. Nel menu Seleziona un ruolo, seleziona il ruolo Creatore token service account.

      4. Fai clic su Salva. Il riquadro Concedi l'accesso si chiude.

   5. Concedi il ruolo Utente account di servizio all'agente di servizio GKE nel progetto del cluster:

      1. Nel riquadro Gestisci accesso, fai clic su Aggiungi entità. Viene visualizzato il riquadro Concedi l'accesso.

      2. Nel campo Nuove entità, specifica l'indirizzo email del service agent GKE nel progetto del cluster:

         [e-mail]
         

      3. Nel menu Seleziona un ruolo, seleziona il ruolo Utente account di servizio.

      4. Fai clic su Salva. Il riquadro Concedi l'accesso si chiude.

   6. Chiudi il riquadro Gestisci accesso.

   gcloud

   1. Recupera il numero di progetto del progetto del cluster:

      gcloud projects describe CLUSTER_PROJECT_ID \
          --format='value(projectNumber)'
      

      Sostituisci CLUSTER_PROJECT_ID con l'ID progetto del tuo progetto cluster.

      L'output è simile a 123456789.

   2. Concedi il ruolo roles/iam.serviceAccountTokenCreator all'account di servizio personalizzato all'agente di servizio Compute Engine nel progetto cluster:

      gcloud iam service-accounts add-iam-policy-binding \
          SA_NAME@SERVICE_ACCOUNT_PROJECT_ID.iam.gserviceaccount.com \
          --member=[e-mail] \
          --role=roles/iam.serviceAccountTokenCreator
      

      Sostituisci quanto segue:

      • SA_NAME: il nome del service account personalizzato.
      • SERVICE_ACCOUNT_PROJECT_ID: l'ID progetto del progetto che contiene il tuo account di servizio personalizzato.
      • CLUSTER_PROJECT_NUMBER: il numero del progetto cluster.

   3. Concedi il ruolo roles/iam.serviceAccountUser al service agent GKE nel progetto del cluster sull'account di servizio personalizzato:

      gcloud iam service-accounts add-iam-policy-binding \
          SA_NAME@SERVICE_ACCOUNT_PROJECT_ID.iam.gserviceaccount.com \
          --member=[e-mail] \
          --role=roles/iam.serviceAccountUser
      

Consenti il pull delle immagini da repository privati

Se hai immagini in repository Artifact Registry privati, devi concedere al account di servizio del nodo l'accesso a questi repository. Anche se utilizzi il account di servizio Compute Engine predefinito, potresti dover concedere l'accesso al service account al tuo repository se si trova in un altro progetto.

Nota :i passaggi descritti in questa sezione consentono l'accesso al repository solo all'account di servizio del nodo. I carichi di lavoro nel cluster non ottengono questo accesso. Per concedere ai tuoi workload GKE l'accesso alle risorse Google Cloud , utilizza Workload Identity Federation for GKE.

Per eseguire il pull di immagini private da Artifact Registry, concedi il ruolo di lettore Artifact Registry (roles/artifactregistry.reader) sul repository al account di servizio del nodo.

Console

1. Nella console Google Cloud , vai alla pagina Repository.

   Vai a Repository

2. Seleziona la casella di controllo relativa al repository.

3. Fai clic su Mostra riquadro informazioni. Viene visualizzato il riquadro delle informazioni sul repository.

4. Nella scheda Autorizzazioni, fai clic su Aggiungi entità. Viene visualizzato il riquadro Concedi l'accesso.

5. Nel campo Nuove entità, specifica l'indirizzo email del service account del nodo.

6. Fai clic su Seleziona un ruolo per aprire la finestra di dialogo di selezione del ruolo.

7. Seleziona il ruolo Lettore Artifact Registry.

8. Fai clic su Salva.

gcloud

Concedi il ruolo roles/artifactregistry.reader sul repository:

gcloud artifacts repositories add-iam-policy-binding REPOSITORY_NAME \
    --member=serviceAccount:SERVICE_ACCOUNT_EMAIL \
    --project=REPOSITORY_PROJECT_ID \
    --role=roles/artifactregistry.reader

Sostituisci quanto segue:

• REPOSITORY_NAME: il nome del repository Artifact Registry.
• SERVICE_ACCOUNT_EMAIL: l'indirizzo email del service account del nodo.
• REPOSITORY_PROJECT_ID: l'ID progetto del progetto che contiene il repository.

Config Connector

Nota: questo passaggio richiede Config Connector. Segui le istruzioni di installazione per installare Config Connector sul cluster.

Nota: questi passaggi presuppongono che tu utilizzi Config Connector per gestire il tuo repository Artifact Registry. Se il repository non esiste come risorsa Config Connector, questi passaggi non funzioneranno.

1. Salva il seguente manifest come policy-artifact-registry-reader.yaml:

   apiVersion: iam.cnrm.cloud.google.com/v1beta1
   kind: IAMPolicyMember
   metadata:
     name: policy-artifact-registry-reader
   spec:
     member: serviceAccount:"SA_NAME"@"PROJECT_ID".iam.gserviceaccount.com
     role: roles/artifactregistry.reader
     resourceRef:
       apiVersion: artifactregistry.cnrm.cloud.google.com/v1beta1
       kind: ArtifactRegistryRepository
       name: "REPOSITORY_NAME"

   Sostituisci quanto segue:

   • SA_NAME: il nome del account di servizio IAM.
   • PROJECT_ID: il tuo ID progetto Google Cloud .
   • REPOSITORY_NAME: il nome del repository Artifact Registry.

2. Concedi il ruolo Lettore Artifact Registry all'account di servizio:

   kubectl apply -f policy-artifact-registry-reader.yaml
   

Passaggi successivi

• Creare un cluster Autopilot
• Crea un cluster regionale
• Aggiungi un pool di nodi a un cluster standard