Gestisci service account

Un'identità di servizio in Google Distributed Cloud (GDC) air-gapped fornisce un'identità dedicata per consentire a workload o servizi di accedere in modo programmatico a risorse e microservizi in modo sicuro. Si tratta di identità speciali utilizzate da applicazioni o carichi di lavoro, anziché da una persona, e non possono essere utilizzate per l'accesso umano. Analogamente agli account utente, concedi autorizzazioni e ruoli a un'identità di servizio per definire a cosa è autorizzata ad accedere.

Potresti notare due termini utilizzati per questo concetto. La console GDC utilizza principalmente il termine identità del servizio, mentre i comandi gdcloud e le interazioni API spesso utilizzano il termine account di servizio. Il secondo riflette il nome della risorsa personalizzata Kubernetes sottostante, ProjectServiceAccount. Entrambi i termini si riferiscono alla stessa cosa: l'identità non umana per i tuoi carichi di lavoro. Questo documento utilizza l'identità del servizio come termine principale.

Le identità di servizio sono utili per gestire l'infrastruttura GDC, ad esempio:

• Servizi e workload Distributed Cloud interni per accedere in modo sicuro all'interfaccia di programmazione delle applicazioni (API) del control plane Distributed Cloud. Ad esempio, i servizi di database interagiscono con le API Kubernetes per creare ed eliminare database.
• Carichi di lavoro dei clienti in Distributed Cloud per accedere ai servizi Distributed Cloud ed effettuare chiamate API (Application Programming Interface) autorizzate. Ad esempio, le identità di servizio possono gestire un cliente utilizzando un notebook Vertex AI Workbench per trascrivere file audio utilizzando l'API Speech-to-Text.
• Workload esterni da federare con Distributed Cloud. Ad esempio, le identità di servizio possono gestire un'applicazione esterna a Distributed Cloud che digitalizza i documenti, ma vuole utilizzare l'API Optical Character Recognition (OCR) per sostituire il motore OCR attuale.
• Servizi cloud distribuiti o controller di sistema per accedere in modo sicuro alle risorse dei clienti o ai cluster utente. Ad esempio, le identità di servizio possono gestire i flussi di lavoro di autenticazione e autorizzazione in cui i controller di servizio in esecuzione nei cluster di amministrazione devono eseguire i workload all'interno dei cluster utente gestiti dai clienti.

Puoi gestire gli account per le identità di servizio utilizzando la console GDC, gcloud CLI o l'API. Con gcloud CLI, la funzionalità di identità del servizio si basa sull'API ProjectServiceAccount globale. Poiché le risorse ProjectServiceAccount sono configurate a livello globale, operano in tutte le zone del tuo universo gdcloud.

Prima di iniziare

Puoi creare un'identità di servizio solo all'interno di un progetto. Per scoprire come creare un progetto, consulta Creare un progetto.

La gestione delle identità di servizio coinvolge sia l'identità di servizio (rappresentata da una risorsa ProjectServiceAccount) sia le relative credenziali (coppie di chiavi pubbliche e private). Per ottenere le autorizzazioni necessarie per gestire le identità di servizio e le relative credenziali, chiedi all'amministratore IAM dell'organizzazione o all'amministratore IAM del progetto di concederti il ruolo Amministratore IAM del progetto (project-iam-admin) nel progetto.

Nota: gli utenti con il ruolo Amministratore IAM progetto possono accedere a tutte le identità di servizio all'interno del progetto. Ciò include la gestione delle risorse ProjectServiceAccount e delle chiavi pubbliche associate.

Crea un'identità del servizio

La creazione di un'identità di servizio include la creazione di un account e delle relative credenziali.

Crea un account

Per creare un account per un'identità di servizio, utilizza la console GDC, gcloud CLI o l'API per creare una risorsa ProjectServiceAccount in un progetto.

Console

1. Accedi alla console GDC.
2. Nel menu di navigazione, seleziona Identity & Access > Service identities.
3. Fai clic su Crea identità di servizio. Viene visualizzata la pagina Dettagli identità di servizio.
4. Nel campo Nome identità di servizio, inserisci un nome per l'identità di servizio. Ad esempio: testserviceidentity.
5. Fai clic su Crea.

gdcloud

Crea un account:

gdcloud iam service-accounts create NAME \
    --project=PROJECT

Sostituisci i seguenti valori:

• NAME: il nome del ProjectServiceAccount. Il nome deve essere univoco all'interno dello spazio dei nomi del progetto.
• PROJECT: il progetto in cui creare l'identità del servizio. Se gdcloud init è già impostato, ometti il flag --project.

Questo comando crea un ProjectServiceAccount nello spazio dei nomi del progetto sul server dell'API Management.

API

1. Crea un file YAML della risorsa personalizzata ProjectServiceAccount, ad esempio my-project-sa.yaml:

   apiVersion: resourcemanager.global.gdc.goog/v1
   kind: ProjectServiceAccount
   metadata:
     name: NAME
     namespace: PROJECT
   spec:
     keys:
     - algorithm: ALGORITHM
     id: KEY_ID
     key: BASE64_ENCODED_KEY
     validAfter: "START_TIME"
     validBefore: "EXPIRATION_TIME"
   

   Sostituisci le seguenti variabili:

   • NAME: il nome della risorsa ProjectServiceAccount. Il nome deve essere univoco all'interno dello spazio dei nomi del progetto.
   • PROJECT: il progetto in cui creare l'identità del servizio.
   • ALGORITHM: l'algoritmo della chiave. Sono supportate solo le chiavi ES256.
   • KEY_ID: l'identificatore univoco della chiave. L'ID viene utilizzato per determinare la chiave da verificare.
   • BASE64_ENCODED_KEY: la chiave pubblica con codifica Base64 in formato PEM da verificare. La chiave privata utilizzata per generare questa chiave pubblica è prevista nel formato PEM ECDSA P256.
   • START_TIME: l'ora di inizio in cui la chiave diventa valida, ad esempio 2025-02-07T00:59:34Z.
   • EXPIRATION_TIME: la data di scadenza della chiave, ad esempio 2026-02-07T00:59:34Z.

2. Applica la risorsa personalizzata ProjectServiceAccount al server API globale:

   kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG apply -f my-project-sa.yaml
   

   Sostituisci la variabile GLOBAL_API_SERVER_KUBECONFIG con il percorso del file kubeconfig per il server API globale.

Crea credenziali

Per consentire a un carico di lavoro o a un'applicazione di autenticarsi come identità del servizio (rappresentata dall'account che hai creato), devi generare le credenziali. La creazione delle credenziali comporta la generazione di una coppia di chiavi crittografiche privata e pubblica e l'associazione della chiave pubblica all'identità del servizio.

Per creare credenziali per un'identità di servizio, utilizza la console GDC, gcloud CLI o l'API.

Console

1. Accedi alla console GDC.
2. Nel menu di navigazione, seleziona Identità e accesso > Identità del servizio.
3. Fai clic sul nome dell'identità del servizio che vuoi aggiungere alla chiave.
4. Fai clic su Crea nuova chiave.
5. La nuova chiave viene visualizzata nell'elenco Chiavi e una finestra di dialogo conferma che la chiave è stata creata correttamente.

gdcloud

Il comando gdcloud crea un file JSON delle credenziali predefinite dell'applicazione e una coppia di chiavi pubblica e privata:

gdcloud iam service-accounts keys create APPLICATION_DEFAULT_CREDENTIALS_FILENAME \
    --project=PROJECT \
    --iam-account=NAME \
    --ca-cert-path=CA_CERTIFICATE_PATH

Sostituisci i seguenti valori:

• APPLICATION_DEFAULT_CREDENTIALS_FILENAME: il nome del file JSON.
• PROJECT : seleziona il progetto per cui creare la chiave. Se gdcloud init è già impostato, puoi omettere il flag --project.
• NAME: il nome dell'identità del servizio a cui aggiungere la chiave.
• CA_CERTIFICATE_PATH: (facoltativo) il percorso del certificato dell'autorità di certificazione (CA) per verificare l'endpoint di autenticazione. Se non specifichi questo percorso, vengono utilizzati i certificati CA di sistema. Devi installare la CA nei certificati CA del sistema.

Distributed Cloud aggiunge la chiave pubblica alle chiavi che utilizzi per verificare i token web JSON (JWT) firmati dalla chiave privata.ProjectServiceAccount La chiave privata viene scritta nel file JSON delle credenziali predefinite dell'applicazione.

L'esempio seguente mostra il file JSON delle credenziali predefinite dell'applicazione:

{
"type": "gdch_service_account",
"format_version": "1",
"project": "project_name",
"private_key_id": "abcdef1234567890",
"private_key": "-----BEGIN PRIVATE KEY-----\nETC\n-----END PRIVATE KEY-----\n",
"name": "service_identity_name",
"ca_cert_path": "/path/to/ca.crt",
"token_uri": "https://service-identity.<Domain>/authenticate"
}

Questo esempio utilizza i seguenti valori:

• project: lo spazio dei nomi del progetto nell'organizzazione.
• private_key_id: l'ID assegnato alla chiave.
• private_key: la chiave privata ECDSA P256 in formato PEM generata dalla CLI.
• name: il nome dell'identità del servizio.
• ca_cert_path: il percorso del certificato dell'autorità di certificazione (CA) utilizzato per verificare l'endpoint di autenticazione.
• token_uri: l'indirizzo dell'endpoint di autenticazione.

API

1. Genera la coppia di chiavi pubblica e privata. I seguenti comandi utilizzano openssl come esempio, uno strumento comune per questo scopo.

   openssl ecparam -name prime256v1 -genkey -noout -out "key.pem"
   openssl ec -in "key.pem" -pubout > "pub.pem"
   

2. Codifica in base64 la chiave pubblica e recupera il relativo ID chiave:

   KEY_ID=$(openssl pkey -in key.pem -pubout -outform der | openssl dgst -sha256 | sed 's/^.* //')
   BASE64_ENCODED_KEY=$(cat pub.pem | base64)
   

3. Crea o aggiorna il file YAML della risorsa personalizzata ProjectServiceAccount, inclusi i dati della chiave generati nel passaggio precedente:

   apiVersion: resourcemanager.global.gdc.goog/v1
   kind: ProjectServiceAccount
   metadata:
     name: NAME
     namespace: PROJECT
   spec:
     keys:
     - algorithm: ALGORITHM
     id: KEY_ID
     key: BASE64_ENCODED_KEY
     validAfter: "START_TIME"
     validBefore: "EXPIRATION_TIME"
   

   Sostituisci le seguenti variabili:

   • NAME: il nome della risorsa ProjectServiceAccount. Il nome deve essere univoco all'interno dello spazio dei nomi del progetto.
   • PROJECT: il progetto in cui stai creando la chiave.
   • ALGORITHM: l'algoritmo della chiave. Sono supportate solo le chiavi ES256.
   • KEY_ID: l'identificatore univoco della chiave. L'ID viene utilizzato per determinare la chiave da verificare.
   • BASE64_ENCODED_KEY: la chiave pubblica con codifica Base64 in formato PEM da verificare. La chiave privata utilizzata per generare questa chiave pubblica è prevista nel formato PEM ECDSA P256.
   • START_TIME: l'ora di inizio in cui la chiave diventa valida, ad esempio 2025-02-07T00:59:34Z.
   • EXPIRATION_TIME: la data di scadenza della chiave, ad esempio 2026-02-07T00:59:34Z.

4. Applica la risorsa personalizzata ProjectServiceAccount al server API globale:

   kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG apply -f my-project-sa.yaml
   

   Sostituisci la variabile GLOBAL_API_SERVER_KUBECONFIG con il percorso del file kubeconfig per il server API globale.

5. Crea il file JSON delle credenziali predefinite dell'applicazione contenente la chiave privata. Assicurati che la variabile KEY_ID nel file JSON sia impostata sullo stesso valore della variabile KEY_ID che hai utilizzato nella specifica ProjectServiceAccount.

   cat <<EOF > "key_file.json"
   {
     "format_version": "1",
     "name": "NAME",
     "private_key": "$(tr '\n' '\t' < "key.pem" | sed 's/\t/\\n/g')",
     "private_key_id": "KEY_ID",
     "project": "PROJECT",
     "token_uri": "AUTH_URL",
     "type": "gdch_service_account"
   }
   EOF
   

   Sostituisci le seguenti variabili:

   • NAME: il nome dell'identità del servizio.
   • KEY_ID: l'identificatore univoco della chiave. L'ID viene utilizzato per determinare la chiave da verificare e deve corrispondere al valore KEY_ID utilizzato nella specifica ProjectServiceAccount.
   • PROJECT: lo spazio dei nomi del progetto nell'organizzazione.
   • AUTH_URL: l'indirizzo dell'endpoint di autenticazione.

Per informazioni dettagliate su come utilizzare il file della chiave generato per autenticare gcloud CLI come questa identità di servizio, consulta la sezione Autorizzare un'identità di servizio utilizzando una chiave.

Visualizzare le identità del servizio

Questa sezione descrive come visualizzare le identità di servizio e le relative chiavi pubbliche.

Visualizzare un elenco di identità di servizio

Per visualizzare un elenco delle identità di servizio all'interno di un progetto, utilizza la console GDC o gcloud CLI.

Console

1. Accedi alla console GDC.
2. Seleziona un progetto.
3. Nel menu di navigazione, fai clic su Identità e accesso > Identità di servizio per visualizzare l'elenco delle identità di servizio per il progetto.

gdcloud

Elenca gli account di identità del servizio in un progetto:

gdcloud iam service-accounts list \
    --project=PROJECT

Sostituisci PROJECT con l'ID progetto.

Visualizzare un elenco di chiavi pubbliche per un'identità di servizio

Elenca le chiavi pubbliche registrate con un account di identità del servizio nel progetto:

gdcloud iam service-accounts keys list \
    --project=PROJECT \
    --iam-account=NAME

Sostituisci quanto segue:

• PROJECT: l'ID progetto
• NAME: il nome dell'account dell'identità del servizio da utilizzare.

Concedi le autorizzazioni per le identità di servizio

Per concedere le autorizzazioni a un'identità di servizio, assegnale uno o più ruoli creando associazioni di ruoli utilizzando la console GDC o gcloud CLI.

Console

1. Accedi alla console GDC.
2. Seleziona un progetto.
3. Nel menu di navigazione, seleziona Identità e accesso > Accesso.
4. Nell'elenco Membro, fai clic su Aggiungi membro. Viene visualizzata la pagina Utenti e ruoli.
5. Seleziona Identità servizio nell'elenco Tipo di membro.
6. Nell'elenco Identità del servizio, seleziona l'identità del servizio a cui vuoi assegnare un binding del ruolo.
7. Nell'elenco Ruolo, seleziona il ruolo che vuoi assegnare all'identità di servizio, ad esempio Backup Creator.
8. (Facoltativo) Per aggiungere un altro ruolo, fai clic su Aggiungi un altro ruolo. Seleziona il ruolo aggiuntivo.
9. Fai clic su Aggiungi.

gdcloud

Puoi associare l'account dell'identità di servizio ai ruoli all'interno dello spazio dei nomi del progetto o ai ruoli in uno spazio dei nomi diverso.

Nota: i flag --project e --role-namespace si escludono a vicenda, il che significa che puoi utilizzarne solo uno in un singolo comando, non entrambi.

• Associa l'account a un ruolo all'interno dello spazio dei nomi del progetto:

  gdcloud iam service-accounts add-iam-policy-binding \
      --project=PROJECT \
      --role=ROLE \
      --iam-account=NAME
  

  Sostituisci quanto segue:

  • PROJECT: il progetto in cui creare l'associazione del ruolo. Se gdcloud init è già impostato, puoi omettere il flag --project.
  • ROLE: il ruolo predefinito da assegnare all'account. Specifica i ruoli nel formato Role/name, dove Role è il tipo di Kubernetes IAMRole e name è il nome del ruolo predefinito. Ad esempio, per assegnare il ruolo Visualizzatore progetto, imposta il ruolo su IAMRole/project-viewer.
  • NAME: il nome dell'account dell'identità di servizio da utilizzare.

• Associa l'account a un ruolo all'interno di uno spazio dei nomi diverso:

  gdcloud iam service-accounts add-iam-policy-binding \
      --role=ROLE \
      --role-namespace=ROLE_NAMESPACE \
      --iam-account=NAME
  

  Sostituisci quanto segue:

  • ROLE: il ruolo predefinito da assegnare all'account. Specifica i ruoli nel formato Role/name, dove Role è il tipo di Kubernetes IAMRole e name è il nome del ruolo predefinito. Ad esempio, per assegnare il ruolo Visualizzatore progetto, imposta il ruolo su IAMRole/project-viewer.
  • ROLE_NAMESPACE: lo spazio dei nomi del ruolo da associare all'account diverso dallo spazio dei nomi del progetto.
  • NAME: il nome dell'account dell'identità di servizio da utilizzare.

Autenticare e utilizzare un'identità di servizio

Per configurare gdcloud e altri strumenti in modo che funzionino come identità del servizio, devi prima autenticarti in gdcloud utilizzando il file delle chiavi dell'identità del servizio. Una volta autenticato, puoi utilizzare le credenziali dell'identità del servizio per generare token o file kubeconfig.

Autorizza un'identità di servizio utilizzando una chiave

Nota :le chiavi dell'identità del servizio comportano un rischio per la sicurezza se non vengono gestite con attenzione. Consulta la sezione Proteggere le chiavi degli account di servizio per informazioni sulle best practice per la gestione, l'utilizzo e la protezione delle chiavi dell'identità di servizio.

Il comando gdcloud auth activate-service-account autentica gcloud CLI con un'identità di servizio. Ciò ti consente di eseguire azioni sulle risorse Distributed Cloud utilizzando le autorizzazioni dell'account dell'identità di servizio anziché un account utente.

Autorizza un'identità di servizio utilizzando una chiave:

1. Crea un file della chiave delle credenziali, se non ne hai già uno.

2. Attiva l'identità del servizio eseguendo questo comando:

   gdcloud auth activate-service-account --key-file=KEY_FILE
   

   Sostituisci KEY_FILE con il percorso del file della chiave delle credenziali, in genere in formato JSON.

   Dopo l'attivazione riuscita, gdcloud utilizza le credenziali dell'identità del servizio anziché le tue credenziali utente.

Stampa un token ID per l'identità del servizio

Dopo aver autorizzato un'identità di servizio, puoi stamparne un token di identità. Puoi utilizzare questo token come token di autenticazione per autenticare le richieste HTTP. Ciò significa che il token concede a chiunque lo possieda l'accesso ai servizi definiti nel parametro AUDIENCES.

Stampa un token ID per l'account identità del servizio specificato:

gdcloud auth print-identity-token --audiences=AUDIENCES

Sostituisci AUDIENCES con il destinatario o il servizio a cui è destinato il token. È possibile specificare un solo segmento di pubblico.

Genera il file kubeconfig

Dopo aver autorizzato un'identità di servizio, puoi generare un file kubeconfig per autenticarti ai cluster.

1. Imposta la proprietà gdcloud core/organization_console_url:

   gdcloud config set core/organization_console_url
   https://GDC_URL
   

   Sostituisci GDC_URL con l'URL della tua organizzazione.

2. Genera il file kubeconfig per accedere a un cluster utilizzando l'identità del servizio attivo:

   • Per un cluster zonale:

     export KUBECONFIG=KUBECONFIG_PATH
     gdcloud clusters get-credentials CLUSTER_NAME --zone ZONE
     

     Sostituisci quanto segue:

     • KUBECONFIG_PATH: il percorso in cui vuoi salvare il file kubeconfig generato.

     • CLUSTER_NAME: il nome del cluster zonale.

       Nota: l'elenco dei nomi dei cluster è disponibile nell'URL di configurazione dell'accesso:
       https://GDC_URL/.well-known/login-config.

     • ZONE: il nome della zona in cui si trova il cluster.

   • Per il server API globale:

     export KUBECONFIG=KUBECONFIG_PATH
     gdcloud clusters get-credentials global-api
     

     Sostituisci KUBECONFIG_PATH con il percorso in cui vuoi salvare il file kubeconfig generato.

Viene generato un file kubeconfig, configurato per l'autenticazione come identità del servizio. Di seguito è riportato un esempio di file YAML:

apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: <REDACTED>
    server: <REDACTED>
  name: cluster-name
contexts:
- context:
    cluster: cluster-name
    user: gdch_console-<REDACTED>_cluster-name
  name: cluster-name-gdch_console-<REDACTED>_cluster-name
current-context: cluster-name-gdch_console-gdc1-staging-gpcdemolabs-com_cluster-name
kind: Config
preferences: {}
users:
- name: gdch_console-<REDACTED>_cluster-name
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1
      args:
      - --audience=<REDACTED>
      command: gdcloud-k8s-auth-plugin
      env: null
      installHint: Run 'gdcloud components install gdcloud-k8s-auth-plugin' to use
        plugin
      interactiveMode: Never
      provideClusterInfo: false

Eliminare un'identità del servizio

Importante: quando elimini un'identità di servizio, le associazioni di ruoli associate non vengono rimosse automaticamente. Se crei una nuova identità di servizio con lo stesso nome, eredita automaticamente le autorizzazioni dell'identità di servizio eliminata in precedenza. Per evitare autorizzazioni orfane che possono rimanere da un'identità di servizio eliminata, prima rimuovi eventuali associazioni di ruoli esistenti associate all'identità di servizio prima di eliminare l'identità di servizio stessa.

Dopo aver eliminato un'identità di servizio, l'ProjectServiceAccount e le relative chiavi pubbliche vengono eliminati, le chiavi private esistenti diventano non valide e le applicazioni non hanno più accesso alle risorse del progetto tramite l'identità di servizio.

Per eliminare un'identità di servizio, utilizza la console GDC o gcloud CLI.

Console

1. Accedi alla console GDC.
2. Nel menu di navigazione, seleziona Identità e accesso > Identità del servizio.
3. Seleziona la casella di controllo dell'identità del servizio che vuoi eliminare.
4. Fai clic su Elimina.
5. Viene visualizzata la finestra di dialogo di conferma. Nel campo Conferma digitando quanto segue di seguito, inserisci remove.
6. Fai clic su Elimina.

gdcloud

Esegui questo comando per eliminare un'identità di servizio:

gdcloud iam service-accounts delete NAME \
    --project=PROJECT

Sostituisci quanto segue:

• NAME: il nome dell'account identità del servizio da eliminare.
• PROJECT: l'ID progetto

Elimina credenziali

Se vuoi disattivare una coppia di chiavi specifica senza eliminare l'intero account dell'identità di servizio, puoi eliminare la relativa chiave pubblica dall'account dell'identità di servizio. Questa azione invalida la chiave privata corrispondente.

Nota :l'eliminazione della chiave pubblica non revoca le credenziali di breve durata emesse utilizzando la chiave privata corrispondente.

Per eliminare la chiave pubblica, utilizza la console GDC o gcloud CLI.

Console

1. Accedi alla console GDC.
2. Nel menu di navigazione, seleziona Identità e accesso > Identità del servizio.
3. Fai clic sul nome dell'identità del servizio che contiene la chiave che vuoi eliminare.
4. Fai clic su Elimina.
5. Nella finestra di dialogo di conferma, fai clic su Elimina.

gdcloud

Rimuovi la chiave pubblica con l'ID chiave da un account di identità del servizio nel progetto:

gdcloud iam service-accounts keys delete KEY_ID \
    --project=PROJECT \
    --iam-account=NAME

Sostituisci quanto segue:

• KEY_ID: l'identificatore univoco della chiave.
• PROJECT: l'ID progetto
• NAME: il nome dell'account dell'identità di servizio.