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：區域 Cloud Storage 路徑，用來暫時存放序列記錄、暫存映像檔封存和客層執行記錄等構件。值區必須已存在。

  • _IMAGE_BUILDER_CONFIG_PATH：自訂食譜的路徑。imagebuilder.yaml 可以是遠端 Cloud Storage 路徑 (例如 gs://BUCKET_NAME/imagebuilder.yaml)，也可以是工作區或 GitHub 存放區中的相對路徑，視來源而定。

  • _SERVICE_ACCOUNT：設定為執行建構作業並授權協調器步驟的服務帳戶，其完整身分與存取權管理 (IAM) 資源名稱。

  • _IMAGE_OUTPUT_PATH：Cloud Build /workspace/ 目錄中匯出 tar 檔案的輸出路徑。

  • _ARTIFACT_REGISTRY_RESOURCE_URI (選用)：Artifact Registry 中一般存放區的資源 URI。如果提供這個位置，管道會推送產生的不可變更映像檔 tar 檔案，並在這個位置產生認證。

步驟

Image Builder 會依序執行三個不同的容器步驟，協調 OS 映像檔建構作業。將容器映像檔路徑中的 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 會安全地收集高階管道執行指標，以監控及追蹤服務可靠性，如下所示：

  • 建構執行和狀態：每個建構步驟和自訂動作的成功或失敗狀態，以及完成時間。
  • 環境詳細資料：執行期間使用的 Compute Engine 機型、可用區和容器版本標記。
  • 映像檔中繼資料：基本 OS 發行版本、版本和已設定的客體 OS 功能。
  • 驗證測試結果：自動系統驗證測試的通過、失敗或略過狀態，例如 VM 啟動、安全啟動、區塊儲存空間健康狀態、客體代理程式狀態和網路驅動程式繫結。

自訂步驟

自訂步驟會驗證 imagebuilder.yaml 的結構定義、檢查 IAM 權限、啟動 worker VM 執行個體、掛接自訂二進位檔磁碟、執行自訂佈建工具，並安全地匯出開機磁碟分割區。

  • 容器映像檔：us-central1-docker.pkg.dev/image-builder-official/release/builder:stable
  • 指令碼指令：/build
  • 結果子區塊：
    • image_builder_telemetry_metrics：收集自訂建構執行指標。
    • base_image (選用)：指定 Artifact Registry 通用存放區目的地時，在建構認證中繼資料中記錄基本來源圖片詳細資料。設定 attestationType: "https://cloudbuild.googleapis.com/attestations/build_content_restrictions"，建立圖片來源的可驗證記錄。

驗證步驟

驗證步驟會從自訂 OS 映像檔啟動臨時測試 VM，並執行主動式自動驗證測試套件。

  • 容器映像檔：us-central1-docker.pkg.dev/image-builder-official/release/validator:stable
  • 指令碼指令：/validate
  • 結果子區塊：image_builder_telemetry_metrics 收集驗證測試執行指標。

發布步驟

發布步驟會註冊最終的 OS 映像檔、刪除暫時的中繼磁碟、將 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 建構作業來源資訊證明。這項出處資訊提供加密驗證，確保映像檔是按照管道中定義的內容建構，有助於防止竄改，並確保軟體供應鏈的完整性。
  • 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}'