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: Parsen, Erstellen, Validieren und Veröffentlichen des Release.

Schemaübersicht

Eine Standard-Image Builder-cloudbuild.yaml-Datei folgt der Standardstruktur der Cloud Build-Konfigurationsdatei und orchestriert drei aufeinanderfolgende 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 sie für die Ausführung direkt Umgebungsvariablen 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 Image-Archive und Gast-Ausführungsverläufe verwendet wird. Der Bucket muss bereits vorhanden sein.
  • _IMAGE_BUILDER_CONFIG_PATH: Der Pfad zu Ihrem imagebuilder.yaml-Anpassungsrezept. Dies 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 für die Ausführung des Builds konfiguriert ist und Orchestrator-Schritte autorisiert.

  • _IMAGE_OUTPUT_PATH: Der relative Pfad im Cloud Build-Verzeichnis /workspace/, in den die Pipeline die exportierte image.tar.gz-Datei herunterlädt, wenn Sie _ARTIFACT_REGISTRY_RESOURCE_URI angeben. Dieser Pfad muss sich im Verzeichnis /workspace/ befinden und ist auch dann erforderlich, wenn Sie _ARTIFACT_REGISTRY_RESOURCE_URI nicht angeben.

  • _ARTIFACT_REGISTRY_RESOURCE_URI (optional): Der Ressourcen-URI für das generische Repository in Artifact Registry. Falls angegeben, überträgt die Pipeline die generierte unveränderliche Image-TAR-Datei und generiert Attestierungen an diesem Speicherort.

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 Zielregion von Google Cloud , in der Sie Ihre Pipelines eingerichtet haben, 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 Pipelineausführung, um die Zuverlässigkeit des Dienstes wie folgt zu überwachen und zu verfolgen:

  • Build-Ausführung und -Status: Erfolgs- oder Fehlerstatus und Abschlussdauer für jeden Build-Schritt und jede Anpassungsaktion.
  • Umgebungsdetails: Der Compute Engine-Maschinentyp, die Zone und das Containerversions-Tag, die während der Ausführung verwendet wurden.
  • Image-Metadaten: Basis-Betriebssystemverteilung, Version und konfigurierte Gastbetriebssystem-Features.
  • Validierungstestergebnisse: Status „Bestanden“, „Fehlgeschlagen“ oder „Übersprungen“ von automatisierten Systemvalidierungstests, z. B. VM-Boot, Secure Boot, Zustand des Blockspeichers, Status des Gast-Agents und Netzwerk-Treiberbindung.

Anpassungsschritt

Im Anpassungsschritt wird das Schema von imagebuilder.yaml validiert, die IAM-Berechtigungen werden geprüft, die Worker-VM-Instanz wird gestartet, das Laufwerk mit der Anpassungsbinärdatei wird bereitgestellt, 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
  • Scriptbefehl: /build
  • Unterblock „Ergebnisse“:
    • image_builder_telemetry_metrics: Erfasst Messwerte zur Ausführung von Anpassungs-Builds.
    • base_image (optional): Zeichnet Details zum Basis-Quell-Image in den Metadaten der Build-Attestierung auf, wenn Sie ein generisches Repository-Ziel in Artifact Registry angeben. Legen Sie attestationType: "https://cloudbuild.googleapis.com/attestations/build_content_restrictions" fest, um einen überprüfbaren Eintrag des Ursprungs Ihres Images zu erstellen.

Validierungsschritt

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

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

Veröffentlichungsschritt

Im Veröffentlichungsschritt wird das endgültige Betriebssystem-Image registriert, temporäre Zwischenlaufwerke werden gelöscht, die TAR-Datei-Nutzlast wird in Artifact Registry hochgeladen, falls konfiguriert, und es werden Herkunftsdatensätze für Supply Chain Levels for Software Artifacts (SLSA) geschrieben.

  • Container-Image: us-central1-docker.pkg.dev/image-builder-official/release/builder:stable
  • Scriptbefehl: /publish
  • Unterblock „Results“: image_builder_telemetry_metrics erfasst Messwerte zur Ausführung von Veröffentlichungsreleases.

Optionen

Mit den Options-Flags werden Ausführungseinstellungen auf dem Cloud Build-Server definiert. 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: Legen Sie den Wert auf true fest, damit 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, dass das Image genau so erstellt wurde, wie es in Ihrer Pipeline definiert ist. Dadurch werden Manipulationen verhindert und die Integrität der Softwarelieferkette wird gewährleistet.
  • substitutionOption: Legen Sie ALLOW_LOOSE fest. Diese Einstellung ist erforderlich, damit Cloud Build dynamische Parameter oder nicht verwendete Skriptargumente ignoriert.
  • dynamicSubstitutions: Legen Sie den Wert auf true fest, damit Systembewertungsvariablen wie ${BUILD_ID} korrekt aufgelöst werden können.
  • logging: Setzen Sie den Wert auf CLOUD_LOGGING_ONLY, um Build-Logs strikt auf Cloud Logging zu beschränken.

Artefakte

Konfigurieren Sie den Block artifacts, wenn Sie Image-Archive und Attestierungen in Artifact Registry exportieren:

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