Esegui build con un account di servizio gestito dall'utente

Questo documento descrive come configurare le build in modo che utilizzino un service account gestito dall'utente.

Se non specifichi un account di servizio gestito dall'utente per le tue build, Cloud Build utilizza automaticamente il service account Cloud Build predefinito. Questo account di servizio predefinito potrebbe avere autorizzazioni inutilmente ampie, ad esempio l'accesso ai tuoi repository Cloud Source Repositories e a qualsiasi bucket Cloud Storage nel tuo progetto.

Ti consigliamo di seguire il principio del privilegio minimo assegnando autorizzazioni e ruoli agli account di servizio con ambito limitato all'attività che eseguono. Ad esempio, puoi utilizzare un account di servizio per creare ed eseguire il push delle immagini in Artifact Registry, come mostrato nel blogGoogle Cloud .

Prima di iniziare

  • Abilita le API Cloud Build e IAM, se non sono già abilitate.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

    Abilita le API

  • Se prevedi di utilizzare questo account per creare e gestire le credenziali, ad esempio per creare credenziali di breve durata, attiva l'API Service Account Credentials IAM.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

    Abilitare l'API

  • Se non l'hai ancora fatto, crea un service account.

Configurare il service account

Concedi i ruoli IAM al tuo account di servizio gestito dall'utente in modo che disponga delle autorizzazioni necessarie per eseguire le build. Puoi anche configurare Cloud Build in modo che scelga automaticamente questo account di servizio per i nuovi trigger.

  1. Nella console Google Cloud , vai alla pagina Autorizzazioni Cloud Build:

    Vai ad Autorizzazioni

  2. Vai al menu Service account e seleziona il tuo account di servizio. Per scegliere un account di servizio in un altro progetto, fai clic su Cambia progetto.

  3. Per utilizzare il account di servizio selezionato come account di servizio per i nuovi trigger, attiva Imposta come preselezionato per i nuovi trigger.

  4. Nell'elenco dei servizi Google Cloud , abilita i ruoli IAM che vuoi concedere al tuo account di servizio.

  5. Se il ruolo necessario per la pipeline di build non è elencato qui, puoi concedere ruoli aggiuntivi nella pagina delle configurazioni IAM.

  6. Se hai selezionato un account di servizio in un altro progetto, completa i passaggi descritti in Configurazione tra progetti.

Per scoprire di più sui ruoli IAM comunemente richiesti per una build, consulta le seguenti informazioni:

Configura i log di build

Quando specifichi il tuo account di servizio per le build, devi archiviare i log di build in uno dei seguenti tipi di bucket:

Se crei un bucket di log, assicurati che non abbia una policy di conservazione, poiché questa potrebbe impedire a Cloud Build di scrivere i log di build nel bucket.

Non puoi archiviare i log in un bucket di log di proprietà di Google Cloud.

Per ulteriori informazioni su dove archiviare i log di build, consulta Opzioni di archiviazione dei log di build.

Esegui una build utilizzando un file di configurazione

Per eseguire manualmente una build utilizzando un file di configurazione:

  1. Nella directory root del progetto, crea un file di configurazione di build Cloud Build denominato cloudbuild.yaml o cloudbuild.json.

  2. Aggiungi il campo serviceAccount e la configurazione di logging preferita.

    • Se archivi i log di build in Cloud Logging, aggiungi un campo logging e impostane il valore su CLOUD_LOGGING_ONLY.

    • Se archivi i log di build in un bucket Cloud Storage creato dall'utente:

      • Aggiungi un campo logging e impostane il valore su GCS_ONLY.
      • Aggiungi un campo logsBucket e imposta il relativo valore sulla località del bucket Cloud Storage.

    L'esempio seguente configura Cloud Build per l'esecuzione di build utilizzando un account di servizio gestito dall'utente e configura i log di build in modo che vengano archiviati in un bucket Cloud Storage creato dall'utente:

    YAML 

    steps:
- name: 'bash'
  args: ['echo', 'Hello world!']
logsBucket: 'LOGS_BUCKET_LOCATION'
serviceAccount: 'projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT'
options:
  logging: GCS_ONLY

    JSON 

    {
  "steps": [
  {
    "name": "bash",
    "args": [
      "echo",
      "Hello world!"
    ]
  }
  ],
  "logsBucket": "LOGS_BUCKET_LOCATION",
  "serviceAccount": "projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT",
  "options": {
    "logging": "GCS_ONLY"
  }
}

    Sostituisci le variabili nel file di configurazione di build con quanto segue:

    • LOGS_BUCKET_LOCATION è il bucket Cloud Storage in cui archiviare i log di build. Ad esempio, gs://mylogsbucket.
    • PROJECT_ID è l'ID del progetto Google Cloud in cui stai eseguendo la build.
    • SERVICE_ACCOUNT è l'indirizzo email o l'ID univoco del account di servizio che vuoi specificare per le build. Ad esempio, l'indirizzo email di un service account è simile al seguente: service-account-name@project-id.iam.gserviceaccount.com.

  3. Avvia la build utilizzando il file di configurazione della build:

    gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORY

    Sostituisci le variabili nei comandi con i seguenti valori:

    • CONFIG_FILE_PATH è il percorso del file di configurazione della build.
    • SOURCE_DIRECTORY è il percorso o l'URL del codice sorgente.

    Se non specifichi CONFIG_FILE_PATH e SOURCE_DIRECTORY nel comando gcloud builds submit, Cloud Build presuppone che il file di configurazione di compilazione e il codice sorgente si trovino nella directory di lavoro corrente.

Esegui le build utilizzando i trigger

Per eseguire una build con i trigger di Cloud Build utilizzando il tuo account di servizio, configura l'opzione di logging che preferisci e seleziona il account di servizio che preferisci durante la creazione del trigger.

Se vuoi utilizzare lo stesso account di servizio per tutti i nuovi trigger, puoi configurare Cloud Build in modo che selezioni automaticamente il service account.

  1. Nel file di configurazione di compilazione:

    • Se archivi i log di build in Cloud Logging, aggiungi un campo logging e imposta il valore del campo su CLOUD_LOGGING_ONLY.

    • Se archivi i log di build in un bucket Cloud Storage creato dall'utente:

      • Aggiungi un campo logging e impostane il valore su GCS_ONLY.
      • Aggiungi un campo logsBucket e imposta il relativo valore sulla località del bucket Cloud Storage.

    L'esempio seguente configura i log di build in modo che vengano archiviati in un bucket Cloud Storage creato dall'utente:

    YAML 

    steps:
- name: 'bash'
  args: ['echo', 'Hello world!']
logsBucket: 'LOGS_BUCKET_LOCATION'
options:
  logging: GCS_ONLY

    JSON 

    {
  "steps": [
  {
    "name": "bash",
    "args": [
      "echo",
      "Hello world!"
    ]
  }
  ],
  "logsBucket": "LOGS_BUCKET_LOCATION",
  "options": {
    "logging": "GCS_ONLY"
  }
}

    Sostituisci LOGS_BUCKET_LOCATION con il bucket Cloud Storage in cui archiviare i log di build. Ad esempio, gs://mylogsbucket.

  2. Specifica un account di servizio da utilizzare con il trigger di build:

    Console

    1. Crea o modifica il trigger di build.

    2. Nel campo Service account, specifica il tuo account di servizio. Per scegliere un account di servizio in un altro progetto, fai clic su Cambia progetto.

      Se non specifichi un account di servizio, Cloud Build utilizza il service account predefinito.

    3. Fai clic su Crea per salvare il trigger di build.

    gcloud

    Quando crei un trigger di build, specifica il account di servizio utilizzando il flag --service-account. Nell'esempio seguente, il comando gcloud crea un trigger di build che estrae il codice da un repository Git:

    gcloud builds triggers create github \
   --name=TRIGGER_NAME \
   --repo-name=REPO_NAME \
   --repo-owner=REPO_OWNER \
   --branch-pattern=BRANCH_PATTERN
   --build-config=BUILD_CONFIG_FILE
   --service-account=SERVICE_ACCOUNT
   --project=BUILD_PROJECT

    Sostituisci le variabili nel file di configurazione di build con i seguenti valori:

    • TRIGGER_NAME è il nome del trigger di build.
    • REPO_NAME è il nome del repository.
    • REPO_OWNER è il nome utente del proprietario del repository.
    • BRANCH_PATTERN è il nome del branch nel tuo repository su cui richiamare la build.
    • TAG_PATTERN è il nome del tag nel tuo repository su cui richiamare la build.
    • BUILD_CONFIG_FILE è il percorso del file di configurazione della build.
    • SERVICE_ACCOUNT è il tuo account di servizio nel formato /projects/PROJECT_ID/serviceAccounts/ACCOUNT_ID_OR_EMAIL.
    • BUILD_PROJECT è il progetto in cui stai avviando le build.

Configurazione tra progetti

Puoi utilizzare un account di servizio gestito dall'utente per eseguire build in un progetto diverso da quello in cui hai creato il account di servizio solo se non viene applicato il vincolo della policy dell'organizzazione iam.disableCrossProjectServiceAccountUsage. Questo vincolo viene applicato per impostazione predefinita. Scopri di più.

  • Il seguente comando disabilita l'applicazione di questo vincolo e concede l'accesso necessario. Prima di impostare il vincolo nella policy dell'organizzazione, la tua organizzazione deve essere consapevole dei compromessi in termini di sicurezza:

    gcloud resource-manager org-policies disable-enforce \
   iam.disableCrossProjectServiceAccountUsage \
   --project=SERVICE_ACCOUNT_PROJECT_ID

    In questo comando, SERVICE_ACCOUNT_PROJECT_ID è il progetto che contiene il tuo account di servizio gestito dall'utente

  • Nel progetto che contiene il tuo account di servizio gestito dall'utente, concedi il ruolo roles/iam.serviceAccountTokenCreator all'agente di servizio Cloud Build del progetto in cui esegui le build:

    gcloud projects add-iam-policy-binding SERVICE_ACCOUNT_PROJECT_ID \
    --member="serviceAccount:BUILD_SERVICE_AGENT" \
    --role="roles/iam.serviceAccountTokenCreator"

    Sostituisci le variabili nel comando con quanto segue:

    • SERVICE_ACCOUNT_PROJECT_ID: l'ID progetto del progetto che contiene il tuo account di servizio gestito dall'utente.
    • BUILD_SERVICE_AGENT: l'ID email dell'agente di servizio nel formato service-BUILD_PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com, dove BUILD_PROJECT_NUMBER è il numero del progetto in cui esegui le build. Puoi trovare il numero di progetto nella pagina delle impostazioni progetto.

Limitazioni:

  • Il tuo progetto Google Cloud deve trovarsi in un'organizzazione Google Cloud .

  • Devi avviare le build nella riga di comando utilizzando gcloud builds submit o gcloud builds triggers create.

  • Se ricevi un errore service account not found quando concedi il ruolo IAM, potresti dover creare manualmente l'agente di servizio.

Passaggi successivi