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, creazione, convalida e pubblicazione della release.

Panoramica dello schema

Un file cloudbuild.yaml standard di Image Builder segue la struttura standard del file di configurazione di Cloud Build e orchestra tre passaggi sequenziali di creazione del 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 le 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 di Cloud Storage regionale utilizzato come posizione di staging temporanea per artefatti come log seriali, archivi di immagini temporanei e cronologie di esecuzione degli ospiti. 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 nello spazio di lavoro o nel repository GitHub, a seconda dell'origine.

  • _SERVICE_ACCOUNT: il nome completo della risorsa Identity and Access Management (IAM) dell'account di servizio configurato per eseguire la build e autorizzare i passaggi dell'orchestratore.

  • _IMAGE_OUTPUT_PATH: il percorso di output del file tar esportato all'interno della directory /workspace/ di Cloud Build.

  • _ARTIFACT_REGISTRY_RESOURCE_URI (facoltativo): l'URI della risorsa per il repository generico in Artifact Registry. Se fornita, la pipeline esegue il push del file tar dell'immagine immutabile generata e genera attestazioni in questa posizione.

Procedura

Image Builder esegue tre passaggi di container distinti in sequenza per orchestrare la creazione dell'immagine del sistema operativo. Sostituisci REGION nel percorso dell'immagine container con la regione di destinazione Cloud de Confiance 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 passo

Il container orchestrator identifica e monitora l'avanzamento di ogni fase di build (personalizzazione, convalida e pubblicazione) leggendo il campo id di ogni passaggio nel file cloudbuild.yaml.

Gli ID passaggio 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 tenere traccia dell'affidabilità del servizio nel seguente modo:

  • Esecuzione e stato della build: stato di esito positivo o negativo e durata del completamento per ogni passaggio della build e azione di personalizzazione.
  • Dettagli ambiente: il tipo di macchina Compute Engine, la zona e il tag della versione del container utilizzati durante l'esecuzione.
  • Metadati dell'immagine: distribuzione del sistema operativo di base, versione e funzionalità del sistema operativo guest configurate.
  • Risultati del test di convalida: stato superato, non superato o ignorato dei test di convalida automatica del sistema, ad esempio avvio della VM, Avvio protetto, integrità dell'archiviazione a blocchi, stato dell'agente guest e binding del 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
  • Sottoblocco Risultati:
    • image_builder_telemetry_metrics: raccoglie le metriche di esecuzione della build di personalizzazione.
    • base_image (facoltativo): registra i dettagli dell'immagine di base di origine 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 del sistema operativo personalizzata e 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 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 in 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 Risultati: image_builder_telemetry_metrics raccoglie le metriche di esecuzione del rilascio della 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: impostato su true per garantire 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 la manomissione e garantendo l'integrità della catena di fornitura del software.
  • substitutionOption: impostato su ALLOW_LOOSE. Questa impostazione è necessaria per forzare Cloud Build a ignorare i parametri dinamici o gli argomenti dello script inutilizzati.
  • dynamicSubstitutions: impostalo su true per consentire la risoluzione corretta delle variabili di valutazione del sistema, come ${BUILD_ID}.
  • logging: imposta su CLOUD_LOGGING_ONLY per limitare rigorosamente i log di build 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}'