このページの一部またはすべての情報は、S3NS の Cloud de Confiance に適用されない場合があります。詳細については、Google Cloud との違いをご確認ください。

Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

Cloud Build 構成ファイル

このドキュメントでは、Image Builder パイプラインのステップ（解析、ビルド、検証、リリース公開）のオーケストレーションに使用される Cloud Build 構成ファイル（cloudbuild.yaml）の構造とパラメータについて説明します。

スキーマの概要

標準の Image Builder cloudbuild.yaml ファイルは、標準の Cloud Build 構成ファイル構造に従い、/build、/validate、/publish の 3 つの連続したコンテナビルドステップを調整します。

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 リポジトリ内の相対パスにできます。

注: リモートの Cloud Storage の場所から構成ファイルを取得する場合、オブジェクトのサイズは 1 MB を超えないようにする必要があります。
_SERVICE_ACCOUNT: ビルドの実行とオーケストレーターステップの承認用に構成されたサービスアカウントの完全な Identity and Access Management（IAM）リソース名。
_IMAGE_OUTPUT_PATH: Cloud Build の /workspace/ ディレクトリ内のエクスポートされた tar ファイルの出力パス。
_ARTIFACT_REGISTRY_RESOURCE_URI（省略可）: Artifact Registry の汎用リポジトリのリソース URI。指定された場合、パイプラインは生成された変更不可能なイメージ tar ファイルをこの場所に push し、証明書を生成します。

手順

Image Builder は、3 つの異なるコンテナステップを順番に実行して、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 フィールドを読み取って、カスタマイズ、検証、公開という各ビルドフェーズの進行状況を特定して追跡します。

Image Builder がサービス固有のテレメトリー指標を収集できるようにするには、ステップ ID を imagebuilder- プレフィックス（imagebuilder-customize、imagebuilder-validate、imagebuilder-publish など）で始める必要があります。

各ステップの results ブロックに image_builder_telemetry_metrics を含めると、Image Builder は高レベルのパイプライン実行指標を安全に収集し、次のようにサービスの信頼性をモニタリングして追跡します。

ビルドの実行とステータス: 各ビルドステップとカスタマイズアクションの成功または失敗のステータスと完了までの時間。
環境の詳細: 実行中に使用される Compute Engine マシンタイプ、ゾーン、コンテナバージョンタグ。
イメージメタデータ: ベース OS のディストリビューション、バージョン、構成されたゲスト OS の機能。
検証テストの結果: VM 起動、セキュアブート、ブロックストレージの健全性、ゲストエージェントのステータス、ネットワークドライバのバインディングなど、自動システム検証テストの合格、不合格、スキップのステータス。

カスタマイズステップ

カスタマイズステップでは、imagebuilder.yaml のスキーマを検証し、IAM 権限を確認し、ワーカー 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 に設定します。この設定は、SLSA ビルドの来歴証明書を自動的に生成するように Cloud Build に指示します。この来歴は、イメージがパイプラインで定義されたとおりに構築されたことを暗号で検証し、改ざんを防ぎ、ソフトウェアサプライチェーンの完全性を確保するのに役立ちます。
substitutionOption: ALLOW_LOOSE に設定します。この設定は、Cloud Build に動的パラメータまたは未使用のスクリプト引数を無視させるために必要です。
dynamicSubstitutions: ${BUILD_ID} などのシステム評価変数が正しく解決されるように、true に設定します。
logging: ビルドログを Cloud Logging に厳密に制限するには、CLOUD_LOGGING_ONLY に設定します。

アーティファクト

イメージアーカイブと構成証明を Artifact Registry にエクスポートするときに、artifacts ブロックを構成します。

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