Fichier de configuration de Cloud Build

Ce document décrit la structure et les paramètres du fichier de configuration Cloud Build (cloudbuild.yaml) utilisé pour orchestrer les étapes du pipeline Image Builder : analyse, compilation, validation et publication de la version.

Présentation du schéma

Un fichier cloudbuild.yaml Image Builder standard suit la structure standard des fichiers de configuration Cloud Build et orchestre trois étapes de compilation de conteneurs séquentielles : /build, /validate et /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'

Variables de substitution

Le fichier cloudbuild.yaml utilise les variables de substitution suivantes pour établir une correspondance directe avec les variables d'environnement pour l'exécution :

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 : chemin d'accès Cloud Storage régional utilisé comme emplacement de préproduction temporaire pour les artefacts tels que les journaux série, les archives d'images temporaires et les historiques d'exécution des invités. Le bucket doit déjà exister.

  • _IMAGE_BUILDER_CONFIG_PATH : chemin d'accès à votre recette de personnalisation imagebuilder.yaml. Il peut s'agir d'un chemin d'accès Cloud Storage distant (par exemple, gs://BUCKET_NAME/imagebuilder.yaml) ou d'un chemin d'accès relatif dans votre espace de travail ou votre dépôt GitHub, selon la source.

  • _SERVICE_ACCOUNT : nom de ressource Identity and Access Management (IAM) complet du compte de service configuré pour exécuter le build et autoriser les étapes de l'orchestrateur.

  • _IMAGE_OUTPUT_PATH : chemin d'accès au fichier tar exporté dans le répertoire /workspace/ de Cloud Build.

  • _ARTIFACT_REGISTRY_RESOURCE_URI (facultatif) : URI de la ressource pour le dépôt générique dans Artifact Registry. Si elle est fournie, le pipeline envoie le fichier tar d'image immuable généré et crée des attestations à cet emplacement.

Étapes

Image Builder exécute trois étapes de conteneur distinctes de manière séquentielle pour orchestrer la compilation de votre image d'OS. Remplacez REGION dans le chemin d'accès à l'image de conteneur par la région Cloud de Confiance cible dans laquelle vous avez configuré vos pipelines, par exemple us-central1, europe-west1 ou 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'

Exigences concernant la télémétrie et l'ID de l'étape

Le conteneur d'orchestration identifie et suit la progression de chaque phase de compilation (personnalisation, validation et publication) en lisant le champ id de chaque étape de votre fichier cloudbuild.yaml.

Les ID d'étape doivent commencer par le préfixe imagebuilder-, par exemple imagebuilder-customize, imagebuilder-validate et imagebuilder-publish, pour permettre à Image Builder de collecter des métriques de télémétrie spécifiques au service.

Lorsque vous incluez image_builder_telemetry_metrics dans le bloc results de chaque étape, Image Builder collecte de manière sécurisée des métriques d'exécution de pipeline de haut niveau pour surveiller et suivre la fiabilité du service comme suit :

  • Exécution et état de la compilation : état de réussite ou d'échec et durée d'exécution pour chaque étape de compilation et action de personnalisation.
  • Détails de l'environnement : type de machine Compute Engine, zone et tag de version du conteneur utilisés lors de l'exécution.
  • Métadonnées de l'image : distribution et version de l'OS de base, et fonctionnalités configurées de l'OS invité.
  • Résultats des tests de validation : état (réussite, échec ou ignoré) des tests de validation automatisés du système, tels que le démarrage de la VM, le démarrage sécurisé, l'état du stockage de blocs, l'état de l'agent invité et la liaison du pilote réseau.

Étape de personnalisation

L'étape de personnalisation valide le schéma de imagebuilder.yaml, vérifie les autorisations IAM, lance l'instance de VM de nœud de calcul, monte le disque binaire de personnalisation, exécute le provisionneur de personnalisation et exporte de manière sécurisée la partition du disque de démarrage.

  • Image de conteneur : us-central1-docker.pkg.dev/image-builder-official/release/builder:stable
  • Commande de script : /build
  • Sous-bloc "Résultats" :
    • image_builder_telemetry_metrics : collecte les métriques d'exécution de la compilation de personnalisation.
    • base_image (Facultatif) : enregistre les détails de l'image source de base dans les métadonnées d'attestation de compilation lorsque vous spécifiez une destination de dépôt générique Artifact Registry. Définissez attestationType: "https://cloudbuild.googleapis.com/attestations/build_content_restrictions" pour créer un enregistrement vérifiable des origines de votre image.

Étape de validation

L'étape de validation démarre une VM de test temporaire à partir de l'image OS personnalisée et exécute des suites de tests de validation automatisés actifs.

  • Image de conteneur : us-central1-docker.pkg.dev/image-builder-official/release/validator:stable
  • Commande de script : /validate
  • Sous-bloc "Résultats" : image_builder_telemetry_metrics collecte les métriques d'exécution des tests de validation.

Étape de publication

L'étape de publication enregistre l'image OS finale, supprime les disques intermédiaires temporaires, importe la charge utile du fichier tar dans Artifact Registry si elle est configurée et écrit les enregistrements de provenance SLSA (Supply Chain Levels for Software Artifacts).

  • Image de conteneur : us-central1-docker.pkg.dev/image-builder-official/release/builder:stable
  • Commande de script : /publish
  • Sous-bloc "Résultats" : image_builder_telemetry_metrics collecte les métriques d'exécution des versions de publication.

Options

Les indicateurs d'options définissent les paramètres d'exécution sur le serveur Cloud Build. Vous devez configurer les options suivantes :

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

Pour en savoir plus sur ces paramètres, consultez Options du fichier de configuration de compilation Cloud Build.

  • automapSubstitutions : définissez la valeur sur true pour vous assurer que les variables de substitution sont mappées dans l'environnement du conteneur.
  • Définissez requestedVerifyOption sur VERIFIED. Ce paramètre indique à Cloud Build de générer automatiquement des attestations de provenance du build SLSA. Cette provenance fournit une vérification cryptographique indiquant que l'image a été créée exactement comme défini dans votre pipeline, ce qui permet d'éviter toute falsification et d'assurer l'intégrité de la chaîne d'approvisionnement logicielle.
  • Définissez substitutionOption sur ALLOW_LOOSE. Ce paramètre est nécessaire pour forcer Cloud Build à ignorer les paramètres dynamiques ou les arguments de script inutilisés.
  • dynamicSubstitutions : défini sur true pour permettre aux variables d'évaluation du système, comme ${BUILD_ID}, de se résoudre correctement.
  • logging : définissez la valeur sur CLOUD_LOGGING_ONLY pour limiter strictement les journaux de compilation à Cloud Logging.

Artefacts

Configurez le bloc artifacts lorsque vous exportez des archives d'images et des attestations vers Artifact Registry :

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