イメージのカスタマイズ ファイル

このドキュメントでは、Image Builder パイプラインのベース OS イメージ、ハードウェア構成、リリース先、カスタマイズ アクションを定義するために使用するカスタマイズ レシピ ファイル imagebuilder.yaml の構造とパラメータについて説明します。

スキーマの概要

カスタマイズ構成では、API バージョン imagebuilder.gcp.com/v1 とリソースの種類 OSImageCustomization が使用されます。

標準のレシピ ファイルの構造は次のとおりです。

apiVersion: imagebuilder.gcp.com/v1
kind: OSImageCustomization
metadata:
  # Recipe metadata and identifying details
  name: CONFIG_NAME
  description: DESCRIPTION
infrastructureConfig:
  # VM machine type, zone, and network settings
  machineType: MACHINE_TYPE
  zone: ZONE
  network: projects/PROJECT_ID/global/networks/NETWORK_NAME
  subnetwork: projects/PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME
  externalIP: ephemeral
  acceleratorType: ACCELERATOR_TYPE
  acceleratorCount: ACCELERATOR_COUNT
  debug: DEBUG_BOOLEAN
  instanceDurationHours: DURATION_HOURS
  reservations:
    - RESERVATION_NAME
  validationConcurrency: VALIDATION_CONCURRENCY
source:
  # Base source image profile
  imageFamily: projects/IMAGE_PROJECT/global/images/family/IMAGE_FAMILY
  # Alternatively, use a direct image version URI:
  # imagePath: projects/IMAGE_PROJECT/global/images/IMAGE_NAME
destinations:
  # Output OS image release targets
  - diskImage:
      name: IMAGE_NAME
      project: PROJECT_ID
      family: IMAGE_FAMILY
      description: DESCRIPTION
      licenses:
        - projects/PROJECT_ID/global/licenses/LICENSE_NAME
      labels:
        env: production
      signatureDatabaseFile: SIGNATURE_DB_PATH
      storageLocations:
        - STORAGE_LOCATION
spec:
  config:
    # Build options and validation test flags
    skipSystemTests: false
  steps:
    # Customization actions (Shell, FileCopy, UpdateKernelCommandLine, InstallGPU)
    - name: STEP_NAME
      action: ACTION_TYPE
      inputs:
        # Action-specific input parameters

メタデータ

このカスタムビルド テンプレートの識別情報を提供します。

metadata:
  name: CONFIG_NAME
  description: DESCRIPTION
  • name（文字列、必須）: この構成の識別子。
  • description（文字列、省略可）: ビルドの目的の説明。

インフラストラクチャの構成

Image Builder がビルドタスクと検証タスク中に作成する一時的な仮想マシン インスタンスのハードウェアとネットワークのプロパティを指定します。

infrastructureConfig:
  machineType: MACHINE_TYPE
  zone: ZONE
  network: projects/PROJECT_ID/global/networks/NETWORK_NAME
  subnetwork: projects/PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME
  externalIP: ephemeral
  acceleratorType: ACCELERATOR_TYPE
  acceleratorCount: ACCELERATOR_COUNT
  debug: DEBUG_BOOLEAN
  instanceDurationHours: DURATION_HOURS
  reservations:
    - RESERVATION_NAME
  validationConcurrency: VALIDATION_CONCURRENCY
  • machineType（文字列、必須）: ワーカー VM とテスト VM に使用する Compute Engine マシンタイプ。マシンタイプが、imageFamily または imagePath で指定したソースイメージのアーキテクチャと一致していることを確認します。たとえば、x86 イメージには e2-standard-4 を使用し、Arm イメージには c4a-standard-4 を使用します。ベアメタル マシンタイプは対象外です。
  • zone（文字列、必須）: ワーカー VM とテスト VM が実行されるゾーン（us-central1-a など）。
  • network（文字列、省略可）: ワーカー VM と検証テスト VM に接続する VPC ネットワーク（projects/<var>PROJECT_ID</var>/global/networks/<var>NETWORK_NAME</var> や default など）。省略すると、Image Builder はデフォルト ネットワークを使用します。
  • subnetwork（文字列、省略可）: ワーカー VM と検証テスト VM に接続する VPC サブネットワーク（projects/<var>PROJECT_ID</var>/regions/<var>REGION</var>/subnetworks/<var>SUBNET_NAME</var> など）。
  • externalIP（文字列、省略可）: ワーカーと検証テスト VM の外部 IP アドレスの割り当てを指定します。使用できる値:
    • ephemeral（デフォルト）: 共有プールからパブリック エフェメラル IPv4 アドレスを割り当てます。
    • none: 外部 IP アドレスのない VM を作成します。これは、プライベート VPC ネットワーキングのみを使用します。none に設定されている場合は、VM が必要な Cloud de Confiance サービスとパッケージ リポジトリにアクセスできるように、VPC サブネットで限定公開の Google アクセスまたは Cloud NAT が有効になっていることを確認してください。
  • acceleratorType（文字列、省略可）: ワーカー VM にアタッチする GPU アクセラレータのタイプ（nvidia-tesla-t4 や nvidia-l4 など）。
  • acceleratorCount（数値、省略可）: ワーカー VM にアタッチする GPU アクセラレータの数。
  • debug（ブール値、省略可）: debug を true に設定すると、カスタマイズが完了したか失敗したかに関係なく、Image Builder はワーカー VM を保持します。これにより、SSH を使用してアクティブなインスタンスを検査またはトラブルシューティングできます。デフォルトは false です。
  • instanceDurationHours（数値、省略可）: ワーカー VM のランタイムを制限します。カスタマイズが完了するか、スクリプト エラーが発生すると、制限時間が開始されます。これにより、インタラクティブ デバッグ セッション中にアクティブな VM に接続できます。最大 2.0 時間に制限されます。
  • reservations（文字列の配列、省略可）: Image Builder が VM を作成するときに使用する容量予約リソース名（同じプロジェクト内の test-reservation など）。
  • validationConcurrency（数値、省略可）: 一時的な検証テスト コンピューティング インスタンスで並行して実行する検証テストの最大数を指定します。使用できる値は次のとおりです。
    • 0 または省略（デフォルト）: Image Builder は、マシンタイプとアクセラレータの構成に基づいて同時実行を自動検出し、次のように設定します。
      • GPU アクセラレータがアタッチされたベアメタル マシンタイプまたは構成の 1（シーケンシャル）。これにより、割り当て上限の超過やリソースの枯渇を防ぐことができます。
      • 4（並列）。その他のすべてのマシンタイプの場合。
    • 1: 検証テストを順番に実行します。プロジェクトで指定された machineType の割り当てが制限されている場合は、同時実行数を 1 に設定すると、複数のコンピューティング インスタンスが同時に起動されるのを防ぐことができるため、役立ちます。
    • 2 以上: 指定された数の検証テストを並行して実行します。十分な容量または予約がある場合、同時実行数を増やすと、検証テストの全体的な実行時間を短縮できます。

ソースイメージ

Image Builder がワーカー VM の起動に使用するベース オペレーティング システム イメージを識別します。次のいずれかのオプションを指定する必要があります。

標準イメージ ファミリーを指定するには:

source:
  imageFamily: projects/IMAGE_PROJECT/global/images/family/IMAGE_FAMILY

画像モード バージョンの直接 URI を指定するには:

source:
  imagePath: projects/IMAGE_PROJECT/global/images/IMAGE_NAME
  • imageFamily（文字列）: 標準イメージ ファミリー グループのパス（projects/ubuntu-os-cloud/global/images/family/ubuntu-2204-lts など）。
  • imagePath（文字列）: 特定の Compute Engine イメージ バージョンの直接リソース URI（例: projects/cos-cloud/global/images/cos-105-17412-226-28）。

宛先

コンパイルされたカスタム OS イメージをリリースする場所と方法を定義します。このプロパティには、diskImage のリリース先オブジェクトのリストが含まれます。

destinations:
  - diskImage:
      name: IMAGE_NAME
      project: PROJECT_ID
      family: IMAGE_FAMILY
      description: DESCRIPTION
      licenses:
        - projects/PROJECT_ID/global/licenses/LICENSE_NAME
      labels:
        env: production
      signatureDatabaseFile: SIGNATURE_DB_PATH
      storageLocations:
        - STORAGE_LOCATION
  • name（文字列、必須）: 最終的な Compute Engine イメージ リソースに割り当てられるベース名の接頭辞。Image Builder は、この接頭辞に一意のビルド ID を自動的に追加し、最終的なイメージ名を 63 文字に切り捨てます。
  • family（文字列、省略可）: 新しく生成されたイメージに適用するイメージ ファミリー。
  • project（文字列、必須）: Image Builder が出力イメージを書き込む Cloud de Confiance プロジェクト。
  • description（文字列、省略可）: 生成された画像メタデータに付加される説明テキスト。
  • licenses（文字列の配列、省略可）: このイメージに適用される特定のソフトウェア ライセンスのリソースパス。
  • labels（マップ、省略可）: env: production などのタグ付けメタデータの Key-Value ペア。
  • signatureDatabaseFile（文字列、省略可）: セキュアブート署名データベース ファイルへのリソースパス。
  • storageLocations（文字列の配列、省略可）: Compute Engine が最終的なディスクブロックを保存するターゲット ストレージ リージョンまたはマルチリージョン（us-central1 や us など）。注: このプロパティはリストとしてフォーマットされますが、画像送信先ごとに 1 つの場所のみを指定できます。

仕様の構成

一般的な実行オプションを適用します。

spec:
  config:
    skipSystemTests: false
  • skipSystemTests（ブール値、省略可）: テスト VM がブート条件、ネットワーク、UEFI 構造を評価するかどうかを切り替えます。デフォルトは false です。

仕様の手順

Image Builder がワーカー VM で順番に実行するステップ オブジェクトのリストを指定します。各ステップタイプの入力パラメータ スキーマと使用例については、サポートされているカスタマイズ アクションをご覧ください。

すべてのカスタマイズ ステップ オブジェクトには、次の共通プロパティがあります。

spec:
  steps:
    - name: STEP_NAME
      action: ACTION_TYPE
      inputs:
        # Action-specific input parameters
  • name（文字列、必須）: このカスタマイズ ステップのユーザー定義の名前。
  • action（文字列、必須）: 呼び出すヘルパー アクション。サポートされているアクション:
    • Shell: VM でターミナル スクリプトを実行します。
    • FileCopy: Cloud Storage バケットまたはワークスペースからアセットを転送します。
    • UpdateKernelCommandLine: ブート パラメータを更新します。
    • InstallGPU: NVIDIA GPU ドライバを登録します。
  • inputs（オブジェクト、必須）: 選択したアクションに必要な Key-Value プロパティ。パラメータのリファレンスと例については、サポートされているカスタマイズ アクションをご覧ください。

次のスニペットは、Shell アクションを使用するステップの例を示しています。

spec:
  steps:
    - name: setup-environment
      action: Shell
      inputs:
        inlineScript: |
          #!/usr/bin/env bash
          echo "Running customization..."

次のステップ