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

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

スキーマの概要

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

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

apiVersion: imagebuilder.gcp.com/v1
kind: OSImageCustomization
metadata:
  # Recipe metadata and identifying details
infrastructureConfig:
  # VM machine type, zone, and network settings
source:
  # Base source image profile
destinations:
  # Output OS image release targets
spec:
  config:
    # Build options and validation test flags
  steps:
    # Customization actions (Shell, FileCopy, UpdateKernelCommandLine, InstallGPU)

メタデータ

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

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: nvidia-l4
  acceleratorCount: 1
  debug: false
  instanceDurationHours: 2.0
  reservations:
    - RESERVATION_NAME
  • 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 と検証テスト VM の外部 IP アドレスの割り当てを指定します。使用できる値:
    • ephemeral （デフォルト）: 共有プールからパブリック エフェメラル IPv4 アドレスを割り当てます。
    • none: 外部 IP アドレスのない VM を作成します。この VM はプライベート VPC ネットワーキングのみを使用します。none に設定する場合は、VM が必要な Google Cloud サービスと Package Repository にアクセスできるように、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 など）。

ソースイメージ

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:
        - us-central1
  • name （文字列、必須）: 最終的な Compute Engine イメージ リソースに割り当てられるベース名接頭辞。Image Builder は、この接頭辞に一意のビルド ID を自動的に追加し、最終的なイメージ名を 63 文字に切り捨てます。
  • family （文字列、省略可）: 新しく生成されたイメージに適用するイメージ ファミリー。
  • project（文字列、必須）: Image Builder が出力イメージを書き込む Google Cloud プロジェクト 。
  • description （文字列、省略可）: 生成されたイメージ メタデータに添付される説明テキスト。
  • licenses （文字列の配列、省略可）: このイメージに適用される特定のソフトウェア ライセンスのリソースパス。
  • labels （マップ、省略可）: タグ付けメタデータの Key-Value ペア（env: production など）。
  • 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..."

次のステップ