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 ai service account 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 disponi già di 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. 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 disponi già di 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.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.
-
Nella console Google Cloud , vai alla pagina settings Autorizzazioni Cloud Build:
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.
Per utilizzare il account di servizio selezionato come account di servizio per i nuovi trigger, attiva Imposta come preselezionato per i nuovi trigger.
Nell'elenco dei servizi Google Cloud , abilita i ruoli IAM che vuoi concedere al tuo account di servizio.
Se il ruolo necessario per la pipeline di build non è elencato qui, puoi concedere ruoli aggiuntivi nella pagina delle configurazioni IAM.
Se hai selezionato un account di servizio in un altro progetto, completa i passaggi descritti in Configurazione tra progetti.
Identifica il account di servizio da configurare
Prima di concedere i ruoli, verifica quale account di servizio è configurato per le tue build:
Trigger di build esistenti: controlla il account di servizio configurato su un trigger:
gcloud builds triggers describe TRIGGER_NAME \ --region=REGION \ --format="value(serviceAccount)"Sostituisci quanto segue:
TRIGGER_NAME: il nome del trigger di build.REGION: la regione del trigger di build.
Interpreta l'output come segue:
- Se il comando restituisce un nome risorsa del account di servizio nel formato
projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL, concedi i ruoli richiesti a quell'account. Questo output può identificare un account di servizio gestito dall'utente o il account di servizio predefinito di Compute Engine. - Se il campo
serviceAccountè vuoto, il trigger utilizza il service account Cloud Build legacy. L'omissione diserviceAccountdurante la creazione di un trigger è supportata solo nei progetti che utilizzano il account di servizio predefinito legacy. Nei progetti che utilizzano il account di servizio predefinito di Compute Engine o che limitano il account di servizio predefinito in base alla policy dell'organizzazione, la creazione del trigger non riesce con un erroreINVALID_ARGUMENTche indica che devi specificare un account di servizio (BYOSA is required when creating triggers). Se le policy dell'organizzazione limitano il account di servizio predefinito in fase di build, la build non riesce conbuild.service_account must be specified due to the evaluation of the following org policies.
File di configurazione della build: se esegui le build manualmente utilizzando
gcloud builds submit, controlla il camposerviceAccountnel filecloudbuild.yaml. Se omesso, Cloud Build utilizza il service account di build predefinito o non riesce conbuild.service_account must be specified due to the evaluation of the following org policiesse le policy dell'organizzazione limitano il account di servizio predefinito.
Ruoli obbligatori
Per assicurarti che il tuo account di servizio gestito dall'utente disponga delle autorizzazioni necessarie per eseguire le build utilizzando un account di servizio gestito dall'utente, chiedi all'amministratore di concedere i seguenti ruoli IAM al tuo account di servizio gestito dall'utente nel progetto in cui vengono eseguite le build:
-
Scrivere ed eseguire lo streaming dei log di build in Cloud Logging:
Logs Writer (
roles/logging.logWriter) -
Scarica archivi di origine o dipendenze dai bucket Cloud Storage:
Storage Object Viewer (
roles/storage.objectViewer)
Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.
L'amministratore potrebbe anche essere in grado di concedere al tuo account di servizio gestito dall'utente le autorizzazioni richieste tramite ruoli personalizzati o altri ruoli predefiniti.
Simulazione dell'identità dei service account
Per consentire a Cloud Build e ai tuoi trigger di eseguire build utilizzando un account di servizio gestito dall'utente, assicurati che al account di servizio gestito dall'utente siano concesse le seguenti autorizzazioni:
- Per l'identità dell'utente o dell'automazione che crea, aggiorna o esegue manualmente il trigger di build (o invia build con
gcloud builds submit), concedi il ruolo Service Account User (roles/iam.serviceAccountUser), che include l'autorizzazioneiam.serviceAccounts.actAs. - Per l'agente di servizio Cloud Build (
service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com), è richiesta l'autorizzazioneiam.serviceAccounts.getAccessToken. Nello stesso progetto, questa autorizzazione è inclusa per impostazione predefinita nel ruolo Cloud Build Service Agent (roles/cloudbuild.serviceAgent). Se il ruolo è stato rimosso o se il account di servizio gestito dall'utente si trova in un progetto diverso, concedi il ruolo Service Account Token Creator (roles/iam.serviceAccountTokenCreator).
Per scoprire di più sui ruoli IAM comunemente richiesti per una build, consulta le seguenti informazioni:
- Service account Cloud Build predefinito.
- Configurazione dell'accesso alle risorse Cloud Build.
- Ruoli e autorizzazioni IAM di Cloud Build.
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:
Bucket Cloud Storage nel progetto dell'utente. Possono essere bucket creati dall'utente o bucket creati daGoogle Cloude di proprietà dell'utente.
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 saperne di più 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:
Nella directory root del progetto, crea un file di configurazione di build Cloud Build denominato
cloudbuild.yamlocloudbuild.json.Aggiungi il campo
serviceAccounte la configurazione di logging preferita.Se archivi i log di build in Cloud Logging, aggiungi un campo
logginge impostane il valore suCLOUD_LOGGING_ONLY.Se archivi i log di build in un bucket Cloud Storage creato dall'utente:
- Aggiungi un campo
logginge impostane il valore suGCS_ONLY. - Aggiungi un campo
logsBuckete imposta il relativo valore sulla località del bucket Cloud Storage.
- Aggiungi un campo
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_ONLYJSON
{ "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, un indirizzo email di un service account ha il seguente aspetto:service-account-name@project-id.iam.gserviceaccount.com.
Avvia la build utilizzando il file di configurazione della build:
gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORYSostituisci 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 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.
Nel file di configurazione di compilazione:
Se archivi i log di build in Cloud Logging, aggiungi un campo
logginge imposta il valore del campo suCLOUD_LOGGING_ONLY.Se archivi i log di build in un bucket Cloud Storage creato dall'utente:
- Aggiungi un campo
logginge impostane il valore suGCS_ONLY. - Aggiungi un campo
logsBuckete imposta il relativo valore sulla località del bucket Cloud Storage.
- Aggiungi un campo
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_ONLYJSON
{ "steps": [ { "name": "bash", "args": [ "echo", "Hello world!" ] } ], "logsBucket": "LOGS_BUCKET_LOCATION", "options": { "logging": "GCS_ONLY" } }Sostituisci
LOGS_BUCKET_LOCATIONcon il bucket Cloud Storage in cui archiviare i log di build. Ad esempio,gs://mylogsbucket.Specifica un account di servizio da utilizzare con il trigger di build:
Console
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.
Nei progetti che utilizzano il service account Cloud Build legacy, se ometti questo campo, il valore predefinito è il account di servizio legacy. Nei progetti che utilizzano il account di servizio predefinito di Compute Engine o lo limitano in base alla policy dell'organizzazione, devi selezionare un account di servizio, altrimenti la creazione del trigger non va a buon fine e viene visualizzato un errore
INVALID_ARGUMENTche indica che devi specificare un account di servizio.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. Nei progetti che non utilizzano il account di servizio predefinito legacy, il flag--service-accountè obbligatorio, altrimenti la creazione del trigger non riesce con un erroreINVALID_ARGUMENTche indica che devi specificare un account di servizio. Nell'esempio seguente, il comandogcloudcrea 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_PROJECTSostituisci 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 ramo 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 di compilazione.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 è applicato il vincolo della policy dell'organizzazione iam.disableCrossProjectServiceAccountUsage. Questo vincolo viene applicato per impostazione predefinita.
Scopri di più.
Il comando seguente 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_IDIn questo comando, SERVICE_ACCOUNT_PROJECT_ID è il progetto che contiene il account di servizio gestito dall'utente
Nel progetto che contiene il account di servizio gestito dall'utente, concedi il ruolo
roles/iam.serviceAccountTokenCreatorper l'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 che contiene il account di servizio gestito dall'utente.BUILD_SERVICE_AGENT: l'ID email dell'agente di servizio nel formatoservice-BUILD_PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com, doveBUILD_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 submitogcloud builds triggers create.Se ricevi un errore
service account not foundquando concedi il ruolo IAM, potrebbe essere necessario creare manualmente l'agente di servizio.
Passaggi successivi
- Scopri di più sui ruoli e sulle autorizzazioni IAM di Cloud Build.
- Scopri in che modo le modifiche ai service account influiscono sulla modalità di esecuzione delle build.