prepara l'ambiente

Prima di creare una pipeline Image Builder, devi preparare il tuo ambiente Google Cloud . Per preparare l'ambiente, completa le seguenti attività:

Prima di iniziare

  • Se non l'hai ancora fatto, configura l'autenticazione. L'autenticazione verifica la tua identità per l'accesso ad API e servizi Google Cloud . Per eseguire codice o esempi da un ambiente di sviluppo locale, puoi autenticarti su Compute Engine selezionando una delle seguenti opzioni:

    Seleziona la scheda relativa a come prevedi di utilizzare i campioni in questa pagina:

    Console

    Quando utilizzi la console Google Cloud per accedere ai servizi Google Cloud e alle API, non devi configurare l'autenticazione.

    gcloud

    1. Installa Google Cloud CLI. Dopo l'installazione, inizializza Google Cloud CLI eseguendo il comando seguente: 

      gcloud init

      Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

  • Imposta una regione e una zona predefinite.

    • REST

    Per utilizzare gli esempi di API REST in questa pagina in un ambiente di sviluppo locale, utilizzi le credenziali che fornisci a gcloud CLI.

      Installa Google Cloud CLI.

      Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

    Per saperne di più, consulta Autenticati per usare REST nella documentazione sull'autenticazione di Google Cloud .

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per preparare l'ambiente, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

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.

Richiesta di onboarding

Image Builder è in disponibilità generale con una lista consentita. Per eseguire l'onboarding del tuo Google Cloud progetto per la pipeline di personalizzazione delle immagini, invia il modulo di richiesta di accesso o contatta il team dedicato al tuo account Google Cloud .

Service account inclusi nella lista consentita

La lista consentita concede l'accesso al tuo progetto in base al numero di progetto. Di conseguenza, la lista consentita copre solo i service account, che includono:

  • Service account gestiti dall'utente che crei nel tuo progetto.
  • Service account predefiniti che Google Cloud crea nel tuo progetto, ad esempio il account di servizio predefinito di Compute Engine (PROJECT_NUMBER-compute@developer.gserviceaccount.com).

La lista consentita non copre i service account di proprietà di Google perché Google Cloud crea questi service account in progetti di proprietà di Google anziché nel tuo progetto. I service account di proprietà di Google includono quanto segue:

  • Agenti di servizio, ad esempio service-PROJECT_NUMBER@gcp-sa-SERVICE.iam.gserviceaccount.com.
  • Il service account Cloud Build legacy (PROJECT_NUMBER@cloudbuild.gserviceaccount.com), di proprietà e gestito da Google.

Per saperne di più su questi tipi di account di servizio, consulta Tipi di service account.

Se una build viene eseguita come account di servizio di proprietà di Google, non può leggere le immagini container dell'orchestratore Image Builder in Artifact Registry. Di conseguenza, la pipeline non riesce a causa di un errore di autorizzazione negata. Per evitare questo errore, esegui le pipeline come service account gestito dall'utente che crei nel tuo progetto e specifica il account di servizio quando invii una build. Per saperne di più, consulta Configurare il service account Image Builder e Service account Cloud Build predefinito.

Abilita API

Image Builder richiede l'abilitazione delle API Compute Engine, Cloud Build, Artifact Registry, Service Usage e Resource Manager. Per abilitare le API utilizzando la console Google Cloud o Google Cloud CLI, seleziona una delle seguenti schede:

Console

Abilita le API Compute Engine, Cloud Build, Artifact Registry, Service Usage e Cloud Resource Manager, 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 utilizzo servizi (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

Abilita le API

gcloud

Abilita le API Compute Engine, Cloud Build, Artifact Registry, Service Usage e Cloud Resource Manager, 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 utilizzo servizi (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli. 

gcloud services enable compute.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com serviceusage.googleapis.com cloudresourcemanager.googleapis.com

Configura il account di servizio di Image Builder

L'orchestratore di Image Builder viene eseguito utilizzando un service account gestito dall'utente. Quando esegui una pipeline di creazione di immagini, Cloud Build collega questoaccount di serviziot alle VM worker temporanee e alle VM di test per eseguire azioni di personalizzazione e convalida. Questo account di servizio richiede i seguenti ruoli:

  • Compute Admin (roles/compute.admin): gestisce le istanze VM, i dischi permanenti e le immagini del sistema operativo guest.
  • Utente service account (roles/iam.serviceAccountUser): consente a Cloud Build di collegare il account di servizio al worker effimero e alle istanze VM di test.
  • Amministratore storage (roles/storage.admin): legge e scrive artefatti e log di build temporanei nel bucket di staging workdir di Cloud Storage.
  • Logging Log Writer (roles/logging.logWriter): scrive i log di esecuzione in Cloud Logging.
  • Service Usage Viewer (roles/serviceusage.serviceUsageViewer): controlla gli stati dei servizi del progetto durante l'esecuzione della pipeline.
  • Cloud Build Editor (roles/cloudbuild.builds.editor): attiva ed esegue i job Cloud Build ed esporta le immagini.
  • (Facoltativo) Amministratore Artifact Registry (roles/artifactregistry.admin): carica i file tar dell'immagine del sistema operativo generati in Artifact Registry.

Puoi utilizzare un account di servizio esistente o crearne uno nuovo dedicato per la pipeline di build. Utilizza un account di servizio che si trova nel tuo progetto. Non eseguire le pipeline come account di servizio di proprietà di Google, ad esempio il account di servizio Cloud Build legacy, perché la lista consentita di Image Builder non copre questi service account. Per maggiori informazioni, consulta Service account inclusi nella lista consentita e Service account Cloud Build predefinito.

Per creare un nuovo account di servizio dedicato e concedere i ruoli richiesti utilizzando la console Google Cloud o gcloud CLI, seleziona una delle seguenti schede:

Console

    Assicurati di disporre del ruolo IAM Creazione service account (roles/iam.serviceAccountCreator) e del ruolo Amministratore IAM progetto (roles/resourcemanager.projectIamAdmin). Scopri come concedere i ruoli.

  1. Nella console Google Cloud vai a Crea service account.

    Vai a Crea service account
  2. Seleziona il progetto.

  3. Nel campo Nome service account, inserisci un nome. La console Google Cloud compila il campo ID service account in base a questo nome.

    Nel campo Descrizione service account, inserisci una descrizione. Ad esempio, Service account for quickstart.

  4. Fai clic su Crea e continua.

  5. Concedi i seguenti ruoli al account di servizio: Compute Engine > Compute Admin, Service Accounts > Service Account User, Cloud Storage > Storage Admin, Cloud Logging > Logs Writer, Service Usage > Service Usage Viewer, Cloud Build > Cloud Build Editor, Artifact Registry > Artifact Registry Admin.

    Per concedere un ruolo, trova l'elenco Seleziona un ruolo, poi seleziona il ruolo.

    Per concedere altri ruoli, fai clic su Aggiungi un altro ruolo e aggiungi ogni ruolo successivo.

  6. Fai clic su Continua.

  7. Nel campo Ruolo degli utenti del service account, inserisci l'identificatore dell'entità che collegherà ilaccount di serviziot ad altre risorse, ad esempio le istanze Compute Engine.

    In genere si tratta dell'indirizzo email di un Account Google.

  8. Fai clic su Fine per completare la creazione del service account.

gcloud

  1. Crea un account di servizio per la pipeline di build:

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
    --display-name="Image Builder Service Account"

  2. Concedi i ruoli richiesti (roles/compute.admin, roles/iam.serviceAccountUser, roles/storage.admin, roles/logging.logWriter, roles/serviceusage.serviceUsageViewer e roles/cloudbuild.builds.editor) al tuo account di servizio:

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/compute.admin"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/iam.serviceAccountUser"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/storage.admin"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/logging.logWriter"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/serviceusage.serviceUsageViewer"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/cloudbuild.builds.editor"

  3. (Facoltativo) Concedi il ruolo facoltativo (roles/artifactregistry.admin) al tuo account di servizio:

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/artifactregistry.admin"

Sostituisci quanto segue:

  • SERVICE_ACCOUNT_NAME: il nome del account di servizio di build da creare. Ad esempio, custom-builder-sa.
  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • SERVICE_ACCOUNT_EMAIL: l'indirizzo email del service account del servizio di build.

Configura la policy dell'organizzazione per immagini attendibili

Poiché Image Builder utilizza internamente gli strumenti standard di importazione ed esportazione delle immagini di Compute Engine durante l'esecuzione della build, il criterio delle immagini attendibili del tuo progetto (compute.trustedImageProjects) deve consentire esplicitamente le immagini del seguente progetto:

  • projects/compute-image-import

Se il criterio dell'organizzazione limita questo progetto, la fase di esportazione dell'immagine non riesce.

Per aggiornare la policy dell'organizzazione:

  1. Nella policy dell'organizzazione per il vincolo compute.trustedImageProjects, aggiungi projects/compute-image-import all'elenco dei publisher consentiti.
  2. Per istruzioni dettagliate sulla configurazione dei vincoli delle policy dell'organizzazione, vedi Configura le policy per immagini attendibili e Esporta un'immagine personalizzata in Cloud Storage.

Configura i requisiti di accesso e rete VPC

Durante le fasi di creazione e convalida, Image Builder esegue il provisioning di VM worker e di test temporanee nel tuo Google Cloud progetto. Per impostazione predefinita, Image Builder connette le istanze alla tua rete VPC default e assegna indirizzi IP esterni effimeri.

Se specifichi un network o un subnetwork personalizzato oppure configuri externalIP: none nel file di ricetta imagebuilder.yaml:

  • Accesso privato Google e Cloud NAT:se le VM worker o di test sono configurate con externalIP: none (nessun IP esterno), la subnet VPC deve avere l'accesso privato Google abilitato in modo che le istanze possano raggiungere le API di Google e i servizi (come Cloud Storage e Artifact Registry). Se i passaggi di personalizzazione scaricano pacchetti o dipendenze del sistema operativo da repository internet esterni, devi anche configurare Cloud NAT nella subnet.
  • Regole firewall:assicurati che le regole firewall VPC consentano il traffico di uscita alle API di Google e ai repository software necessari. Se prevedi di connetterti alle VM worker attive per il debug interattivo (debug: true), assicurati che le regole firewall consentano il traffico in entrata sulla porta TCP 22. Se le istanze VM non hanno un IP esterno, consenti l'ingresso dall'intervallo IP di Identity-Aware Proxy (IAP) 35.235.240.0/20 per l'inoltro TCP.

Configura Artifact Registry

Per archiviare e gestire le immagini del sistema operativo personalizzate, i metadati di sicurezza e le attestazioni di provenienza della build SLSA, devi configurare un repository generico in Artifact Registry. L'archiviazione delle immagini in Artifact Registry ti consente di mantenere un record sicuro e immutabile delle immagini pubblicate.

Quando configuri una destinazione Artifact Registry, Image Builder esegue i seguenti passaggi:

  • Esporta il disco di avvio della VM finalizzato come file tar standard (.tar.gz).
  • Carica il file tar nel repository generico in Artifact Registry.
  • Genera e firma le attestazioni di provenienza della build SLSA per l'artefatto per collegarlo ai metadati di origine.
  • Registra l'immagine Compute Engine pronta per la produzione con Compute Engine utilizzando l'URI del file tar di Artifact Registry come origine del modello.

Per configurare un Artifact Registry generico, completa le seguenti attività:

  1. Assicurati che il account di servizio utilizzato per eseguire la pipeline Image Builder disponga del ruolo Amministratore Artifact Registry (roles/artifactregistry.admin) a livello di repository o progetto. Per istruzioni dettagliate, vedi Configurare il service account di Image Builder.

  2. Crea un repository di formato generic. Per creare il repository, esegui il comando gcloud artifacts repositories create:

    gcloud artifacts repositories create REPOSITORY_NAME \
    --repository-format=generic \
    --location=REPOSITORY_LOCATION

    Sostituisci i seguenti segnaposto:

    • REPOSITORY_NAME: un nome per il repository generico. Ad esempio, custom-os-images.
    • REPOSITORY_LOCATION: una regione supportata. Ad esempio, us-central1.

Passaggi successivi