環境を準備する

Image Builder パイプラインを作成する前に、まず Google Cloud 環境を準備する必要があります。環境を準備するには、次のタスクを行います。

始める前に

  • まだ設定していない場合は、認証を設定します。認証では、 Google Cloud サービスと API にアクセスするための ID が確認されます。ローカル開発環境からコードまたはサンプルを実行するには、次のいずれかのオプションを選択して Compute Engine に対する認証を行います。

    このページのサンプルをどのように使うかに応じて、タブを選択してください。

    コンソール

    Google Cloud コンソールを使用して Google Cloud サービスと API にアクセスする場合、認証を設定する必要はありません。

    gcloud

    1. Google Cloud CLI をインストールします。インストール後、次のコマンドを実行して Google Cloud CLI を初期化します。

      gcloud init

      外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

  • デフォルトのリージョンとゾーンを設定します。

    • REST

    このページの REST API サンプルをローカル開発環境で使用するには、gcloud CLI に指定した認証情報を使用します。

      Google Cloud CLI をインストールします。

      外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

    詳細については、 Google Cloud 認証ドキュメントの REST を使用して認証するをご覧ください。

必要なロール

環境の準備に必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

  • Service Usage 管理者（roles/serviceusage.serviceUsageAdmin）
  • プロジェクトの Identity and Access Management（IAM）管理者（roles/resourcemanager.projectIamAdmin）またはサービス アカウント管理者（roles/iam.serviceAccountAdmin）
  • Artifact Registry 管理者（roles/artifactregistry.admin）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

オンボーディングのリクエスト

Image Builder は、許可リスト付きで一般提供されています。イメージ カスタマイズ パイプライン用に Google Cloud プロジェクトをオンボーディングするには、アクセス リクエスト フォームを送信するか、 Google Cloud アカウント チームにお問い合わせください。

許可リストに含まれるサービス アカウント

許可リストでは、プロジェクト番号でプロジェクトへのアクセス権が付与されます。その結果、許可リストにはサービス アカウントのみが含まれます。これには次のものが含まれます。

  • プロジェクト内に作成するユーザー管理サービス アカウント。
  • Compute Engine のデフォルトのサービス アカウント（PROJECT_NUMBER-compute@developer.gserviceaccount.com）など、プロジェクトで Google Cloud が作成するデフォルトのサービス アカウント。

許可リストは Google 所有のサービス アカウントを対象としていません。これは、Google Cloud がこれらのサービス アカウントをユーザーのプロジェクトではなく、Google 所有のプロジェクトに作成するためです。Google 所有のサービス アカウントには、次のものがあります。

  • サービス エージェント（例: service-PROJECT_NUMBER@gcp-sa-SERVICE.iam.gserviceaccount.com）。
  • Google が所有および管理する以前の Cloud Build サービス アカウント（PROJECT_NUMBER@cloudbuild.gserviceaccount.com）。

これらのサービス アカウントのタイプについて詳しくは、サービス アカウントのタイプをご覧ください。

ビルドが Google 所有のサービス アカウントとして実行される場合、ビルドは Artifact Registry の Image Builder オーケストレータ コンテナ イメージを読み取ることができません。その結果、パイプラインは権限拒否エラーで失敗します。このエラーを回避するには、プロジェクトで作成したユーザー管理サービス アカウントとしてパイプラインを実行し、ビルドを送信するときにそのサービス アカウントを指定します。詳細については、Image Builder サービス アカウントを構成するとデフォルトの Cloud Build サービス アカウントをご覧ください。

API を有効にする

Image Builder では、Compute Engine、Cloud Build、Artifact Registry、Service Usage、Resource Manager の各 API を有効にする必要があります。 Google Cloud コンソールまたは Google Cloud CLI を使用して API を有効にするには、次のいずれかのタブを選択します。

コンソール

Compute Engine、Cloud Build、Artifact Registry、Service Usage、Cloud Resource Manager の各 API を有効にします（まだ有効になっていない場合）。

API を有効にするために必要なロール

API を有効にするには、serviceusage.services.enable 権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を通じてこの権限がすでに付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（roles/serviceusage.serviceUsageAdmin）を通じてこの権限を取得できます。ロールを付与する方法を確認する。

API を有効にする

gcloud

Compute Engine、Cloud Build、Artifact Registry、Service Usage、Cloud Resource Manager の各 API を有効にします（まだ有効になっていない場合）。

API を有効にするために必要なロール

API を有効にするには、serviceusage.services.enable 権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を介してこの権限がすでに付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（roles/serviceusage.serviceUsageAdmin）を介してこの権限を取得できます。ロールを付与する方法をご覧ください。

gcloud services enable compute.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com serviceusage.googleapis.com cloudresourcemanager.googleapis.com

Image Builder サービス アカウントを構成する

Image Builder オーケストレーターは、ユーザー管理のサービス アカウントを使用して実行されます。イメージ ビルド パイプラインを実行すると、Cloud Build はこのサービス アカウントを一時的なワーカー VM インスタンスとテスト VM インスタンスに接続して、カスタマイズ アクションと検証アクションを実行します。このサービス アカウントには次のロールが必要です。

  • Compute 管理者（roles/compute.admin）: VM インスタンス、永続ディスク、ゲスト OS イメージを管理します。
  • サービス アカウント ユーザー（roles/iam.serviceAccountUser）: Cloud Build がサービス アカウントをエフェメラル ワーカーとテスト VM インスタンスに接続できるようにします。
  • Storage 管理者（roles/storage.admin）: Cloud Storage workdir ステージング バケットで一時的なビルド アーティファクトとログを読み書きします。
  • Logging ログ書き込み（roles/logging.logWriter）: 実行ログを Cloud Logging に書き込みます。
  • Service Usage 閲覧者（roles/serviceusage.serviceUsageViewer）: パイプライン実行中にプロジェクト サービスの状態を確認します。
  • Cloud Build 編集者（roles/cloudbuild.builds.editor）: Cloud Build ジョブをトリガーして実行し、イメージをエクスポートします。
  • （省略可）Artifact Registry 管理者（roles/artifactregistry.admin）: 生成された OS イメージの tar ファイルを Artifact Registry にアップロードします。

既存のサービス アカウントを使用することも、ビルド パイプライン専用の新しいサービス アカウントを作成することもできます。プロジェクトにあるサービス アカウントを使用します。Image Builder の許可リストにはこれらのサービス アカウントが含まれていないため、パイプラインを Google 所有のサービス アカウント（以前の Cloud Build サービス アカウントなど）として実行しないでください。詳細については、許可リストに含まれるサービス アカウントとデフォルトの Cloud Build サービス アカウントをご覧ください。

Google Cloud コンソールまたは gcloud CLI を使用して新しい専用サービス アカウントを作成し、必要なロールを付与するには、次のいずれかのタブを選択します。

コンソール

    サービス アカウントの作成 IAM ロール（roles/iam.serviceAccountCreator）とプロジェクト IAM 管理者ロール（roles/resourcemanager.projectIamAdmin）があることを確認します。ロールを付与する方法をご覧ください。

  1. Google Cloud コンソールで、[サービス アカウントの作成] ページに移動します。

    [サービス アカウントの作成] に移動
  2. プロジェクトを選択します。

  3. [サービス アカウント名] フィールドに名前を入力します。 Google Cloud コンソールでは、この名前に基づいて [サービス アカウント ID] フィールドの値が設定されます。

    [サービス アカウントの説明] フィールドに説明を入力します。例: Service account for quickstart

  4. [作成して続行] をクリックします。

  5. サービス アカウントに次のロールを付与します。Compute Engine > Compute 管理者、サービス アカウント > サービス アカウント ユーザー、Cloud Storage > Storage 管理者、Cloud Logging > ログ書き込み、Service Usage > Service Usage 閲覧者、Cloud Build > Cloud Build 編集者、Artifact Registry > Artifact Registry 管理者。

    ロールを付与するには、[ロールを選択] リストを見つけてロールを選択します。

    追加のロールを付与するには、 [別のロールを追加] をクリックして各ロールを追加します。

  6. [続行] をクリックします。

  7. [サービス アカウント ユーザーロール] フィールドに、サービス アカウントを他のリソース（Compute Engine インスタンスなど）に関連付けるプリンシパルの ID を入力します。

    通常は、Google アカウントのメールアドレスです。

  8. [完了] をクリックして、サービス アカウントの作成を完了します。

gcloud

  1. ビルド パイプラインのサービス アカウントを作成します。

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
    --display-name="Image Builder Service Account"

  2. サービス アカウントに必要なロール（roles/compute.admin、roles/iam.serviceAccountUser、roles/storage.admin、roles/logging.logWriter、roles/serviceusage.serviceUsageViewer、roles/cloudbuild.builds.editor）を付与します。

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/compute.admin"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/iam.serviceAccountUser"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/storage.admin"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/logging.logWriter"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/serviceusage.serviceUsageViewer"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/cloudbuild.builds.editor"

  3. 省略可: サービス アカウントに省略可能なロール（roles/artifactregistry.admin）を付与します。

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/artifactregistry.admin"

次のように置き換えます。

  • SERVICE_ACCOUNT_NAME: 作成するビルド サービス アカウントの名前。例: custom-builder-sa
  • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
  • SERVICE_ACCOUNT_EMAIL: ビルド サービス アカウントのメールアドレス。

信頼できるイメージの組織のポリシーを構成する

Image Builder はビルド実行中に標準の Compute Engine イメージのインポート ツールとエクスポート ツールを内部で使用するため、プロジェクトの信頼できるイメージ ポリシー（compute.trustedImageProjects）で、次のプロジェクトのイメージを明示的に許可する必要があります。

  • projects/compute-image-import

組織のポリシーでこのプロジェクトが制限されている場合、イメージのエクスポート フェーズは失敗します。

組織のポリシーを更新するには:

  1. compute.trustedImageProjects 制約の組織のポリシーで、許可されたパブリッシャーのリストに projects/compute-image-import を追加します。
  2. 組織のポリシーの制約を構成する詳細な手順については、信頼できるイメージのポリシーを設定するとカスタム イメージを Cloud Storage にエクスポートするをご覧ください。

VPC ネットワークとアクセス要件を構成する

ビルドと検証のフェーズでは、Image Builder は Google Cloud プロジェクトに一時的なワーカー VM とテスト VM をプロビジョニングします。デフォルトでは、Image Builder はインスタンスを default VPC ネットワークに接続し、エフェメラル外部 IP アドレスを割り当てます。

カスタム network または subnetwork を指定するか、imagebuilder.yaml レシピ ファイルで externalIP: none を構成する場合:

  • プライベート Google アクセスと Cloud NAT: ワーカー VM またはテスト VM が externalIP: none（外部 IP なし）で構成されている場合、インスタンスが Google API とサービス（Cloud Storage や Artifact Registry など）にアクセスできるように、VPC サブネットワークでプライベート Google アクセスを有効にする必要があります。カスタマイズ手順で外部インターネット リポジトリから OS パッケージまたは依存関係をダウンロードする場合は、サブネットワークで Cloud NAT も構成する必要があります。
  • ファイアウォール ルール: VPC ファイアウォール ルールで、Google API と必要なソフトウェア リポジトリへの下り（外向き）トラフィックが許可されていることを確認します。インタラクティブ デバッグ（debug: true）のためにアクティブなワーカー VM に接続する場合は、ファイアウォール ルールで TCP ポート 22 での内向きが許可されていることを確認してください。VM インスタンスに外部 IP がない場合は、TCP 転送用に Identity-Aware Proxy（IAP）IP 範囲 35.235.240.0/20 からの上り（内向き）を許可します。

Artifact Registry を構成する

カスタム OS イメージ、セキュリティ メタデータ、SLSA ビルドの来歴証明書を保存して管理するには、Artifact Registry に汎用リポジトリを設定する必要があります。Artifact Registry にイメージを保存すると、公開されたイメージの安全で不変のレコードを維持できます。

Artifact Registry の宛先を構成すると、Image Builder は次の手順を実行します。

  • 最終処理された VM ブートディスクを標準の tar ファイル（.tar.gz）としてエクスポートします。
  • tar ファイルを Artifact Registry の汎用リポジトリにアップロードします。
  • アーティファクトの SLSA ビルドの来歴証明書を生成して署名し、ソース メタデータにリンクします。
  • Artifact Registry の tar ファイル URI をテンプレート ソースとして使用して、プロダクション レディな Compute Engine イメージを Compute Engine に登録します。

汎用 Artifact Registry を構成するには、次のタスクを行います。

  1. Image Builder パイプラインの実行に使用されるサービス アカウントに、リポジトリまたはプロジェクト レベルで Artifact Registry 管理者ロール（roles/artifactregistry.admin）があることを確認します。詳細な手順については、Image Builder サービス アカウントを構成するをご覧ください。

  2. 形式 generic のリポジトリを作成します。リポジトリを作成するには、gcloud artifacts repositories create コマンドを実行します。

    gcloud artifacts repositories create REPOSITORY_NAME \
    --repository-format=generic \
    --location=REPOSITORY_LOCATION

    各プレースホルダを次のように置き換えます。

    • REPOSITORY_NAME: 汎用リポジトリの名前。例: custom-os-images
    • REPOSITORY_LOCATION: サポート対象の地域。例: us-central1

次のステップ