Cloud Build-Konfigurationsdatei

In diesem Dokument werden die Struktur und die Parameter der Cloud Build-Konfigurationsdatei (cloudbuild.yaml) beschrieben, die zum Orchestrieren der Schritte der Image Builder-Pipeline verwendet wird: Parsing, Erstellen, Validieren und Veröffentlichen von Releases.

Schemaübersicht

Eine standardmäßige Image Builder-Datei cloudbuild.yaml folgt der Standardstruktur der Cloud Build-Konfigurationsdatei und orchestriert drei sequenzielle Container-Build-Schritte: /build, /validate und /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'

Substitutionsvariablen

In der Datei cloudbuild.yaml werden die folgenden Substitutionsvariablen verwendet, um direkt Umgebungsvariablen für die Ausführung zuzuordnen:

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: Der regionale Cloud Storage-Pfad, der als temporärer Staging-Speicherort für Artefakte wie serielle Logs, temporäre Bildarchive und Ausführungsverläufe von Gastbetriebssystemen verwendet wird. Der Bucket muss bereits vorhanden sein.

  • _IMAGE_BUILDER_CONFIG_PATH: Der Pfad zu Ihrem benutzerdefinierten imagebuilder.yaml-Anpassungsrezept. Das kann ein Remote-Cloud Storage-Pfad (z. B. gs://BUCKET_NAME/imagebuilder.yaml) oder ein relativer Pfad in Ihrem Arbeitsbereich oder GitHub-Repository sein, je nach Quelle.

  • _SERVICE_ACCOUNT: Der vollständige IAM-Ressourcenname (Identity and Access Management) des Dienstkontos, das zum Ausführen des Builds konfiguriert ist, und zum Autorisieren von Orchestrator-Schritten.

  • _IMAGE_OUTPUT_PATH: Der Ausgabepfad der exportierten TAR-Datei im Cloud Build-Verzeichnis /workspace/.

  • _ARTIFACT_REGISTRY_RESOURCE_URI (Optional): Der Ressourcen-URI für das generische Repository in Artifact Registry. Falls angegeben, wird die generierte unveränderliche Image-TAR-Datei von der Pipeline an diesen Speicherort übertragen und es werden Attestierungen generiert.

Schritte

Image Builder führt drei verschiedene Container-Schritte nacheinander aus, um den Build Ihres Betriebssystem-Images zu orchestrieren. Ersetzen Sie REGION im Container-Image-Pfad durch die Cloud de Confiance Zielregion, in der Sie Ihre Pipelines einrichten, z. B. us-central1, europe-west1 oder 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'

Anforderungen an Telemetrie und Schritt-ID

Der Orchestrator-Container identifiziert und verfolgt den Fortschritt jeder Build-Phase – Anpassung, Validierung und Veröffentlichung –, indem er das Feld id jedes Schritts in Ihrer cloudbuild.yaml-Datei liest.

Schritt-IDs müssen mit dem Präfix imagebuilder- beginnen, z. B. imagebuilder-customize, imagebuilder-validate und imagebuilder-publish, damit Image Builder dienstspezifische Telemetriemesswerte erfassen kann.

Wenn Sie image_builder_telemetry_metrics in den results-Block jedes Schritts einfügen, erfasst Image Builder auf sichere Weise allgemeine Messwerte zur Pipeline-Ausführung, um die Dienstzuverlässigkeit so zu überwachen und zu verfolgen:

  • Build-Ausführung und ‑Status: Status (Erfolg oder Fehler) und Dauer der einzelnen Build-Schritte und Anpassungsaktionen.
  • Umgebungsdetails: Der Compute Engine-Maschinentyp, die Zone und das Containerversions-Tag, die während der Ausführung verwendet werden.
  • Image-Metadaten: Basis-Betriebssystem-Distribution, Version und konfigurierte Gastbetriebssystemfunktionen.
  • Ergebnisse von Validierungstests: Status der automatisierten Systemvalidierungstests, z. B. VM-Boot, Secure Boot, Blockspeicher-Systemdiagnose, Gastagentstatus und Netzwerk-Treiberbindung (bestanden, fehlgeschlagen oder übersprungen).

Anpassungsschritt

Im Anpassungsschritt wird das Schema von imagebuilder.yaml validiert, IAM-Berechtigungen werden geprüft, die Worker-VM-Instanz wird gestartet, das Anpassungs-Binärlaufwerk wird eingebunden, der Anpassungs-Provisioner wird ausgeführt und die Bootlaufwerkpartition wird sicher exportiert.

  • Container-Image: us-central1-docker.pkg.dev/image-builder-official/release/builder:stable
  • Script-Befehl: /build
  • Unterblock „Ergebnisse“:
    • image_builder_telemetry_metrics: Erfasst Messwerte zur Ausführung von Anpassungs-Builds.
    • base_image (Optional): Erfasst Details zum Quellbasis-Image in den Metadaten der Build-Attestierung, wenn Sie ein generisches Artifact Registry-Repository als Ziel angeben. Legen Sie attestationType: "https://cloudbuild.googleapis.com/attestations/build_content_restrictions" fest, um einen überprüfbaren Herkunftsnachweis für Ihr Bild zu erstellen.

Validierungsschritt

Im Validierungsschritt wird eine temporäre Test-VM aus dem benutzerdefinierten Betriebssystem-Image gestartet und es werden aktive automatisierte Validierungstestsuiten ausgeführt.

  • Container-Image: us-central1-docker.pkg.dev/image-builder-official/release/validator:stable
  • Script-Befehl: /validate
  • Unterblock „Ergebnisse“: image_builder_telemetry_metrics erfasst Messwerte zur Ausführung von Validierungstests.

Veröffentlichungsschritt

Im Veröffentlichungsschritt wird das endgültige Betriebssystem-Image registriert, temporäre Zwischendatenträger werden gelöscht, die Tar-Datei-Nutzlast wird in Artifact Registry hochgeladen (falls konfiguriert) und SLSA-Herkunftsnachweise (Supply Chain Levels for Software Artifacts) werden geschrieben.

  • Container-Image: us-central1-docker.pkg.dev/image-builder-official/release/builder:stable
  • Script-Befehl: /publish
  • Unterblock „Ergebnisse“: In image_builder_telemetry_metrics werden Messwerte zur Ausführung von Veröffentlichungen erfasst.

Optionen

Die Options-Flags definieren Ausführungseinstellungen auf dem Cloud Build-Server. Sie müssen die folgenden Optionen konfigurieren:

options:
  automapSubstitutions: true
  requestedVerifyOption: VERIFIED
  substitutionOption: ALLOW_LOOSE
  dynamicSubstitutions: true
  logging: CLOUD_LOGGING_ONLY

Weitere Informationen zu diesen Einstellungen finden Sie unter Optionen in der Cloud Build-Konfigurationsdatei.

  • automapSubstitutions: Auf true festgelegt, um sicherzustellen, dass Substitutionsvariablen der Containerumgebung zugeordnet werden.
  • requestedVerifyOption: Legen Sie VERIFIED fest. Mit dieser Einstellung wird Cloud Build angewiesen, automatisch SLSA-Build-Herkunftsattestierungen zu generieren. Diese Herkunft bietet eine kryptografische Bestätigung dafür, dass das Image genau wie in Ihrer Pipeline definiert erstellt wurde. So werden Manipulationen verhindert und die Integrität der Softwarelieferkette sichergestellt.
  • substitutionOption: Legen Sie ALLOW_LOOSE fest. Diese Einstellung ist erforderlich, damit Cloud Build dynamische Parameter oder nicht verwendete Skriptargumente ignoriert.
  • dynamicSubstitutions: Auf true setzen, damit Systembewertungsvariablen wie ${BUILD_ID} richtig aufgelöst werden.
  • logging: Auf CLOUD_LOGGING_ONLY gesetzt, um Build-Logs ausschließlich auf Cloud Logging zu beschränken.

Artefakte

Konfigurieren Sie den artifacts-Block, wenn Sie Bildarchive und Atteste in Artifact Registry exportieren:

artifacts:
  generic_artifacts:
    - folder: '${_IMAGE_OUTPUT_PATH}'
      registry_path: '${_ARTIFACT_REGISTRY_RESOURCE_URI}'