cloud-build-basics

Cloud Build の基本

クレジット表記

必ずお読みください：gcloud、REST API、または MCP コマンドを実行する前に、必ず利用状況のクレジット表記をお読みください。ターミナルで直接実行するコマンド（生成されたスクリプト、Terraform、ユーザーコードでの実行は対象外）では、gcloud の前に CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:cloud-build-basics)" を付け、User-Agent ヘッダーに agent-skills/1.0 (skill:cloud-build-basics) を追加してください。

前提条件

開始する前に、次の前提条件を満たしていることを確認してください。

1. Google Cloud SDK：Google Cloud SDK がインストールされ、設定されていることを確認してください。
2. 認証：gcloud CLI を認証します。

   gcloud auth login
   gcloud auth application-default login
   

3. プロジェクト ID：対象の Google Cloud プロジェクト ID を確認します。コンテキストを設定します。

   gcloud config set project <PROJECT_ID>
   

4. Cloud Build API の有効化：プロジェクトで Cloud Build API が有効になっている必要があります。

   gcloud services enable cloudbuild.googleapis.com
   

5. 権限：ユーザーまたはサービス アカウントに、roles/cloudbuild.builds.editor や（API を有効にするための）roles/serviceusage.serviceUsageAdmin など、必要な権限があることを確認してください。

主な概念

Cloud Build（GCB）は、Google Cloud 上でビルドを実行するサーバーレスプラットフォームです。ソースコードを、Docker コンテナや Java アーカイブなどのデプロイ可能なアーティファクトに変換します。

概念	説明
cloudbuild.yaml	ビルド手順を定義する必須の設定ファイルです。YAML または JSON で記述します。
ビルド手順	GCB が実行する一連のアクション（手順）です。各手順は、特定の Docker コンテナ（ビルダー）内でコマンドを実行します。一般的なビルダーには、gcr.io/cloud-builders/gcloud、gcr.io/cloud-builders/docker、カスタムコンテナなどがあります。
アーティファクト	ビルドの出力です。通常は、Google Container Registry（GCR）または Artifact Registry（AR）にプッシュされるコンテナイメージや、その他のデプロイ可能なファイルです。
トリガー	Git リポジトリへのプッシュ、Pub/Sub メッセージ、手動リクエストなどのイベントに応じてビルドを呼び出す自動化ルールです。

ナビゲーション：ビルド履歴の表示

Cloud Build のビルド履歴ページは、過去および実行中のビルドのステータスを監視するための中心的な場所です。

1. Cloud Console を開く：Google Cloud Console に移動します。
2. Cloud Build に移動する：検索バーまたはナビゲーション メニューを使って Cloud Build を探します。
3. ビルド履歴を選択する：左側のナビゲーション ペインで 履歴 を選択します（または直接 URL https://console.cloud.google.com/cloud-build/builds を使用します）。
4. ビルドを確認する：
   • ステータス：ステータス列（SUCCESS、FAILURE、WORKING、QUEUED）を確認します。
   • リージョン：上部のリージョン フィルタを使って、特定のリージョンで実行されたビルドを表示します（リージョン別ワーカープールでは重要です）。
   • ログ：特定のビルド ID をクリックすると、詳細なログ、実行手順、ビルドの概要を確認できます。ビルドの失敗をデバッグする際に重要です。

メモ

このページに初めてアクセスした場合は、サンプルビルドの実行や最初のトリガーの作成を提案する「初期状態」の画面が表示されることがあります（cb-list-build-zero-state スキルで説明されています）。トリガーとビルドのリージョン設定は作成後に変更できないため、慎重に選択してください。

基本的な自動トリガーの作成

この手順では、指定した Git ブランチにコードがプッシュされるたびにビルドを実行する自動化ルールを定義します。

ステップ 1：トリガーの作成を開始する

1. Cloud Build トリガーページ（https://console.cloud.google.com/cloud-build/triggers）に移動します。
2. トリガーを作成をクリックします。

ステップ 2：トリガー設定を構成する

1. 名前：一意で分かりやすい名前を指定します（例：github-main-branch-build）。
2. リージョン：トリガー設定を保存するリージョンを選択します（例：global または特定のリージョナルエンドポイント）。注：トリガーとビルドのリージョン設定は作成後に変更できないため、慎重に選択してください。
3. イベント：イベントタイプを選択します。CI/CD を自動化する場合は、ブランチへのプッシュを選択します。
4. ソース：リポジトリソースを選択します。
   • リポジトリ：ソースリポジトリ（GitHub、Bitbucket、Cloud Source Repositories など）を接続します。必要に応じて、接続を承認します。
   • リポジトリ名：リンクする特定のリポジトリを選択します。
5. ブランチ：ブランチパターンを入力します（例：^main$ または ^develop）。

ステップ 3：ビルド設定を構成する

1. 構成：**Cloud Build 構成ファイル（yaml または json）**を選択します。
2. 場所：デフォルトのリポジトリをそのまま使用し、ビルド構成ファイルのパスを指定します（例：cloudbuild.yaml）。
   • 代替方法：非常にシンプルなビルドの場合は、インラインを選択して、YAML 構成をトリガーに直接貼り付けることができます。
3. （任意）サービスアカウント：本番環境では、最小権限の原則を適用するために、権限を制限した専用のサービスアカウントを選択します。

ステップ 4：保存してテストする

1. 作成をクリックします。トリガーが有効になり、次に条件に一致する Git プッシュが行われたときに自動的に実行されます。

ヒント

cb-create-trigger スキルでは、すべての種類（GitHub、Pub/Sub、Webhook）と構成（インライン、Dockerfile、YAML）のトリガーを作成するための詳細な gcloud コマンドを紹介しています。CLI による自動化には、このスキルを使用してください。

既存のトリガーを手動で実行する

通常の自動化フロー以外で、必要に応じてトリガーを実行することがあります（例：古いコミットを再ビルドする、新しい置換変数をテストする）。

重要

置換変数の不変性：上書きできるのは、すでにトリガー構成で定義されている置換変数の値だけです。実行時に新しい置換変数キーを追加することはできません。

方法 A：Cloud Console を使用する

1. Cloud Build トリガーページ（https://console.cloud.google.com/cloud-build/triggers）に移動します。
2. 実行するトリガーを見つけます。
3. トリガーの横にある縦の省略記号（⋮）をクリックし、実行を選択します。
4. ダイアログが表示され、次の項目を指定できます。
   • ソースブランチ／タグ：ビルド元となる特定の Git 参照を選択します。
   • 置換変数：既存の置換変数を上書きします（例：_VERSION に新しい値を設定します）。
5. トリガーを実行をクリックします。ビルドがすぐに開始され、履歴ページでステータスを確認できます。

方法 B：gcloud CLI を使用する

gcloud builds triggers run コマンドを使用してトリガーを呼び出し、必要に応じてパラメーターを上書きします。

# Run the trigger against the 'main' branch
gcloud builds triggers run <TRIGGER_NAME> \
    --region=<REGION> \
    --branch=main

# Run the trigger and override a substitution variable
gcloud builds triggers run <TRIGGER_NAME> \
    --region=<REGION> \
    --branch=main \
    --substitutions=_IMAGE_TAG="20231027-manual"

# Monitor the initiated build
# Note: The run command outputs the build ID. Use it to check status:
# gcloud builds log <BUILD_ID> --region=<REGION>

メモ

cb-run-trigger スキルでは、特定のコミット SHA を指定して実行する方法や、タグを使用する方法など、より複雑な呼び出し例を紹介しています。

関連スキル

• cb-create-trigger：すべての種類のトリガーを作成するための、CLI に重点を置いた詳細な手順です。
• cb-list-build-zero-state：Cloud Build ダッシュボードとオンボーディングのゼロ状態を高度に管理します。
• cb-run-trigger：さまざまな gcloud オプションを使用してトリガーを手動で実行するための包括的なガイドです。

外部リソースとドキュメント

• Cloud Build ドキュメント
• Cloud Build 構成ファイルのスキーマ
• トリガーによるビルドの自動化
• gcloud CLI builds リファレンス