File di configurazione di Cloud Build

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 personalizzazione imagebuilder.yaml. Può essere un percorso Cloud Storage remoto (ad esempio gs://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 file image.tar.gz esportato 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. Imposta attestationType: "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_metrics raccoglie 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_metrics raccoglie 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 su true per assicurarti che le variabili di sostituzione siano mappate nell'ambiente del container.
  • requestedVerifyOption: impostato su VERIFIED. 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 su ALLOW_LOOSE. Questa impostazione è obbligatoria per forzare Cloud Build a ignorare i parametri dinamici o gli argomenti degli script non utilizzati.
  • dynamicSubstitutions: imposta su true per consentire la risoluzione corretta delle variabili di valutazione del sistema, come ${BUILD_ID}.
  • logging: imposta su CLOUD_LOGGING_ONLY per 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}'