Questo documento descrive la struttura e i parametri del file di configurazione di Cloud Build (cloudbuild.yaml) utilizzato per orchestrare i passaggi della pipeline di Image Builder: analisi, build, convalida e pubblicazione della release.
Panoramica dello schema
Un file Image Builder cloudbuild.yaml standard segue la struttura del file di configurazione di Cloud Build standard e orchestra tre passaggi sequenziali di creazione dei container: /build, /validate e /publish.
substitutions: _GCS_WORKDIR: 'gs://BUCKET_NAME/workdir/' _IMAGE_BUILDER_CONFIG_PATH: 'imagebuilder.yaml' _SERVICE_ACCOUNT: 'projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL' _IMAGE_OUTPUT_PATH: 'image-builder/binaryOut' _ARTIFACT_REGISTRY_RESOURCE_URI: 'projects/PROJECT_ID/locations/REGION/repositories/REPOSITORY_NAME/packages/PACKAGE_NAME/versions/v${BUILD_ID}' steps: # Step 1: Parse configs and run OS customization on the worker VM - name: 'REGION-docker.pkg.dev/image-builder-official/release/builder:stable' script: | #!/usr/bin/env bash /build id: 'imagebuilder-customize' results: - name: image_builder_telemetry_metrics - name: base_image attestationType: "https://cloudbuild.googleapis.com/attestations/build_content_restrictions" attestationContent: base_image # Step 2: Validate by running system boot checks on the test VM - name: 'REGION-docker.pkg.dev/image-builder-official/release/validator:stable' script: | #!/usr/bin/env bash /validate id: 'imagebuilder-validate' results: - name: image_builder_telemetry_metrics # Step 3: Register OS image and publish tar file to Artifact Registry - name: 'REGION-docker.pkg.dev/image-builder-official/release/builder:stable' script: | #!/usr/bin/env bash /publish id: 'imagebuilder-publish' results: - name: image_builder_telemetry_metrics options: automapSubstitutions: true requestedVerifyOption: VERIFIED substitutionOption: ALLOW_LOOSE dynamicSubstitutions: true logging: CLOUD_LOGGING_ONLY artifacts: generic_artifacts: - folder: '${_IMAGE_OUTPUT_PATH}' registry_path: '${_ARTIFACT_REGISTRY_RESOURCE_URI}' timeout: '3600s'
Variabili di sostituzione
Il file cloudbuild.yaml utilizza le seguenti variabili di sostituzione per mappare direttamente alle variabili di ambiente per l'esecuzione:
substitutions: _GCS_WORKDIR: 'gs://BUCKET_NAME/workdir/' _IMAGE_BUILDER_CONFIG_PATH: 'imagebuilder.yaml' _SERVICE_ACCOUNT: 'projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL' _IMAGE_OUTPUT_PATH: 'image-builder/binaryOut' _ARTIFACT_REGISTRY_RESOURCE_URI: 'projects/PROJECT_ID/locations/REGION/repositories/REPOSITORY_NAME/packages/PACKAGE_NAME/versions/v${BUILD_ID}'
_GCS_WORKDIR: il percorso Cloud Storage regionale utilizzato come posizione di gestione temporanea per artefatti come log seriali, archivi di immagini temporanei e cronologie di esecuzione guest. Il bucket deve esistere già._IMAGE_BUILDER_CONFIG_PATH: il percorso della ricetta di personalizzazioneimagebuilder.yaml. Può essere un percorso Cloud Storage remoto (ad esempiogs://BUCKET_NAME/imagebuilder.yaml) o un percorso relativo nel tuo workspace o repository GitHub, a seconda dell'origine._SERVICE_ACCOUNT: il nome completo della risorsa Identity and Access Management (IAM) del service account configurato per eseguire la build e autorizzare i passaggi dell'orchestratore._IMAGE_OUTPUT_PATH: il percorso relativo all'interno della directory Cloud Build/workspace/in cui la pipeline scarica il fileimage.tar.gzesportato quando specifichi_ARTIFACT_REGISTRY_RESOURCE_URI. Questo percorso deve trovarsi all'interno della directory/workspace/ed è obbligatorio anche se non specifichi_ARTIFACT_REGISTRY_RESOURCE_URI._ARTIFACT_REGISTRY_RESOURCE_URI(facoltativo): l'URI della risorsa per il repository generico in Artifact Registry. Se fornito, la pipeline esegue il push del file tar dell'immagine immutabile generato e genera attestazioni in questa posizione.
Procedura
Image Builder esegue tre passaggi distinti del container in sequenza per orchestrare la build dell'immagine sistema operativo. Sostituisci REGION nel percorso dell'immagine container con la regione Google Cloud di destinazione in cui hai configurato le pipeline, ad esempio us-central1, europe-west1 o asia-east1:
steps: - name: 'REGION-docker.pkg.dev/image-builder-official/release/builder:stable' script: | #!/usr/bin/env bash /build id: 'imagebuilder-customize' - name: 'REGION-docker.pkg.dev/image-builder-official/release/validator:stable' script: | #!/usr/bin/env bash /validate id: 'imagebuilder-validate' - name: 'REGION-docker.pkg.dev/image-builder-official/release/builder:stable' script: | #!/usr/bin/env bash /publish id: 'imagebuilder-publish'
Requisiti di telemetria e ID passaggio
Il container dell'orchestratore identifica e monitora l'avanzamento di ogni fase della build (personalizzazione, convalida e pubblicazione) leggendo il campo id di ogni passaggio nel file cloudbuild.yaml.
Gli ID dei passaggi devono iniziare con il prefisso imagebuilder-, ad esempio
imagebuilder-customize, imagebuilder-validate e imagebuilder-publish,
per consentire a Image Builder di raccogliere metriche di telemetria
specifiche del servizio.
Quando includi image_builder_telemetry_metrics nel blocco results di ogni passaggio, Image Builder raccoglie in modo sicuro metriche di esecuzione della pipeline di alto livello per monitorare e monitorare l'affidabilità del servizio come segue:
- Esecuzione e stato della build: stato di esito positivo o negativo e durata del completamento di ogni passaggio della build e di ogni azione di personalizzazione.
- Dettagli dell'ambiente: il tipo di macchina, la zona e il tag della versione del container di Compute Engine utilizzati durante l'esecuzione.
- Metadati dell'immagine: distribuzione del sistema operativo di base, versione e funzionalità del sistema operativo guest configurate.
- Risultati dei test di convalida: stato di superamento, errore o salto dei test di convalida automatica del sistema, come l'avvio della VM, l'avvio protetto, l'integrità dell'archiviazione a blocchi, lo stato dell'agente guest e l'associazione dei driver di rete.
Passaggio di personalizzazione
Il passaggio di personalizzazione convalida lo schema di imagebuilder.yaml, controlla le autorizzazioni IAM, avvia l'istanza VM worker, monta il disco binario di personalizzazione, esegue il provisioner di personalizzazione ed esporta in modo sicuro la partizione del disco di avvio.
- Immagine container:
us-central1-docker.pkg.dev/image-builder-official/release/builder:stable - Comando dello script:
/build - Blocco secondario dei risultati:
image_builder_telemetry_metrics: raccoglie le metriche di esecuzione della build di personalizzazione.base_image(facoltativo): registra i dettagli dell'immagine di origine di base nei metadati di attestazione della build quando specifichi una destinazione del repository generico di Artifact Registry. ImpostaattestationType: "https://cloudbuild.googleapis.com/attestations/build_content_restrictions"per creare un record verificabile delle origini dell'immagine.
Passaggio di convalida
Il passaggio di convalida avvia una VM di test temporanea dall'immagine sistema operativo personalizzata ed esegue suite di test di convalida automatizzati attivi.
- Immagine container:
us-central1-docker.pkg.dev/image-builder-official/release/validator:stable - Comando dello script:
/validate - Blocco secondario dei risultati:
image_builder_telemetry_metricsraccoglie le metriche di esecuzione dei test di convalida.
Passaggio di pubblicazione
Il passaggio di pubblicazione registra l'immagine sistema operativo finale, elimina i dischi intermedi temporanei, carica il payload del file tar su Artifact Registry, se configurato, e scrive i record di provenienza di Supply Chain Levels for Software Artifacts (SLSA).
- Immagine container:
us-central1-docker.pkg.dev/image-builder-official/release/builder:stable - Comando dello script:
/publish - Sottoblocco Results:
image_builder_telemetry_metricsraccoglie le metriche di esecuzione della release di pubblicazione.
Opzioni
I flag delle opzioni definiscono le impostazioni di esecuzione sul server Cloud Build. Devi configurare le seguenti opzioni:
options:
automapSubstitutions: true
requestedVerifyOption: VERIFIED
substitutionOption: ALLOW_LOOSE
dynamicSubstitutions: true
logging: CLOUD_LOGGING_ONLY
Per ulteriori informazioni su queste impostazioni, consulta Opzioni nel file di configurazione di Cloud Build.
automapSubstitutions: impostala sutrueper assicurarti che le variabili di sostituzione siano mappate nell'ambiente del container.requestedVerifyOption: impostato suVERIFIED. Questa impostazione indica a Cloud Build di generare automaticamente attestazioni di provenienza della build SLSA. Questa provenienza fornisce una verifica crittografica che l'immagine è stata creata esattamente come definito nella pipeline, contribuendo a prevenire le manomissioni e a garantire l'integrità della catena di fornitura del software.substitutionOption: impostato suALLOW_LOOSE. Questa impostazione è obbligatoria per forzare Cloud Build a ignorare i parametri dinamici o gli argomenti degli script non utilizzati.dynamicSubstitutions: imposta sutrueper consentire la risoluzione corretta delle variabili di valutazione del sistema, come${BUILD_ID}.logging: imposta suCLOUD_LOGGING_ONLYper limitare i log di build esclusivamente a Cloud Logging.
Artefatti
Configura il blocco artifacts quando esporti archivi di immagini e attestazioni in Artifact Registry:
artifacts:
generic_artifacts:
- folder: '${_IMAGE_OUTPUT_PATH}'
registry_path: '${_ARTIFACT_REGISTRY_RESOURCE_URI}'