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 Ihremimagebuilder.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 exportierteimage.tar.gz-Datei herunterlädt, wenn Sie_ARTIFACT_REGISTRY_RESOURCE_URIangeben. Dieser Pfad muss sich im Verzeichnis/workspace/befinden und ist auch dann erforderlich, wenn Sie_ARTIFACT_REGISTRY_RESOURCE_URInicht 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 SieattestationType: "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_metricserfasst 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_metricserfasst 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 auftruefest, damit Substitutionsvariablen der Containerumgebung zugeordnet werden.requestedVerifyOption: Legen SieVERIFIEDfest. 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 SieALLOW_LOOSEfest. Diese Einstellung ist erforderlich, damit Cloud Build dynamische Parameter oder nicht verwendete Skriptargumente ignoriert.dynamicSubstitutions: Legen Sie den Wert auftruefest, damit Systembewertungsvariablen wie${BUILD_ID}korrekt aufgelöst werden können.logging: Setzen Sie den Wert aufCLOUD_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}'