Cloud Build 配置文件

本文档介绍了 Cloud Build 配置文件 (cloudbuild.yaml) 的结构和参数，该文件用于编排 Image Builder 流水线的各个步骤：解析、构建、验证和发布。

架构概览

标准 Image Builder cloudbuild.yaml 文件遵循标准 Cloud Build 配置文件结构，并编排三个连续的容器构建步骤：/build、/validate 和 /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'

替代变量

cloudbuild.yaml 文件使用以下替换变量直接映射到执行所需的环境变量：

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：用作制品（例如序列日志、临时映像归档和 guest 执行历史记录）临时暂存位置的区域 Cloud Storage 路径。存储桶必须已存在。

  • _IMAGE_BUILDER_CONFIG_PATH：imagebuilder.yaml 自定义配方的路径。这可以是远程 Cloud Storage 路径（例如 gs://BUCKET_NAME/imagebuilder.yaml），也可以是工作区或 GitHub 代码库中的相对路径，具体取决于来源。

  • _SERVICE_ACCOUNT：配置为运行 build 并授权编排器步骤的服务账号的完整 Identity and Access Management (IAM) 资源名称。

  • _IMAGE_OUTPUT_PATH：导出的 tar 文件在 Cloud Build /workspace/ 目录中的输出路径。

  • _ARTIFACT_REGISTRY_RESOURCE_URI（可选）：Artifact Registry 中通用制品的库的资源 URI。如果提供了此位置，流水线会将生成的不可变映像 tar 文件推送到此位置，并在此位置生成证明。

步骤

Image Builder 依次运行三个不同的容器步骤，以编排操作系统映像构建。将容器映像路径中的 REGION 替换为您设置流水线的 Cloud de Confiance 目标区域，例如 us-central1、europe-west1 或 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'

遥测和步数 ID 要求

编排器容器通过读取 cloudbuild.yaml 文件中每个步骤的 id 字段来识别和跟踪每个构建阶段（自定义、验证和发布）的进展情况。

步骤 ID 必须以 imagebuilder- 前缀开头，例如 imagebuilder-customize、imagebuilder-validate 和 imagebuilder-publish，以便 Image Builder 收集特定于服务的遥测指标。

如果您在每个步骤的 results 块中添加 image_builder_telemetry_metrics，Image Builder 会安全地收集高级流水线执行指标，以监控和跟踪服务可靠性，如下所示：

  • build 执行和状态：每个 build 步骤和自定义操作的成功或失败状态以及完成时长。
  • 环境详细信息：执行期间使用的 Compute Engine 机器类型、可用区和容器版本标记。
  • 映像元数据：基础操作系统发行版、版本和配置的客机操作系统功能。
  • 验证测试结果：自动化系统验证测试（例如虚拟机启动、安全启动、块存储健康状况、guest 代理状态和网络驱动程序绑定）的通过、失败或跳过状态。

自定义步骤

自定义步骤会验证 imagebuilder.yaml 的架构、检查 IAM 权限、启动工作器虚拟机实例、装载自定义二进制磁盘、运行自定义预配工具，并安全地导出启动磁盘分区。

  • 容器映像：us-central1-docker.pkg.dev/image-builder-official/release/builder:stable
  • 脚本命令：/build
  • “结果”子区块：
    • image_builder_telemetry_metrics：收集自定义 build 执行指标。
    • base_image（可选）：在指定 Artifact Registry 通用代码库目标位置时，在 build 证明元数据中记录基本源映像详细信息。设置 attestationType: "https://cloudbuild.googleapis.com/attestations/build_content_restrictions" 以创建可验证的图片来源记录。

验证步骤

验证步骤会从自定义操作系统映像启动临时测试虚拟机，并运行主动自动化验证测试套件。

  • 容器映像：us-central1-docker.pkg.dev/image-builder-official/release/validator:stable
  • 脚本命令：/validate
  • 结果子块：image_builder_telemetry_metrics 收集验证测试执行指标。

发布步骤

发布步骤会注册最终的操作系统映像、删除临时中间磁盘、将 tar 文件载荷上传到 Artifact Registry（如果已配置），并写出软件制品供应链级别 (SLSA) 出处记录。

  • 容器映像：us-central1-docker.pkg.dev/image-builder-official/release/builder:stable
  • 脚本命令：/publish
  • 结果子块：image_builder_telemetry_metrics 收集发布版本执行指标。

选项

选项标志用于定义 Cloud Build 服务器上的执行设置。 您必须配置以下选项：

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

如需详细了解这些设置，请参阅 Cloud Build 配置文件中的选项。

  • automapSubstitutions：设置为 true 可确保将替换变量映射到容器环境。
  • requestedVerifyOption：设置为 VERIFIED。此设置指示 Cloud Build 自动生成 SLSA build 出处证明。此来源信息可提供加密验证，证明映像是完全按照流水线中的定义构建的，有助于防止篡改并确保软件供应链的完整性。
  • substitutionOption：设置为 ALLOW_LOOSE。此设置是必需的，用于强制 Cloud Build 忽略动态参数或未使用的脚本实参。
  • dynamicSubstitutions：设置为 true，以允许系统评估变量（例如 ${BUILD_ID}）正确解析。
  • logging：设置为 CLOUD_LOGGING_ONLY 可将构建日志严格限制在 Cloud Logging 中。

制品

在将映像归档和证明导出到 Artifact Registry 时，配置 artifacts 块：

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