最終更新日: 2026-08-27
TOP(About this memo)) > 一覧(Google Cloud) > Cloud Build
gcloud builds listgcloud builds describe [BUILD_ID].gcloudignoreを使う。gcloud builds submit [[SOURCE] --no-source] [--region=REGION] (省略)
[--config=CONFIG; default="cloudbuild.yaml"
| --pack=[builder=BUILDER],[env=ENV],[image=IMAGE]
| --tag=TAG, -t TAG] [GCLOUD_WIDE_FLAG ...]
.を指定すると現在のディレクトリがすべてアップロードされる。.gcloudignoreで対象外のファイルを指定可能。.gcloudignoreがなく.gitignoreが存在する場合は、.gitignoreで指定されるファイルに基づくGit互換の.gcloudignoreがgcloud CLIによって生成される。
--no-sourceを指定した場合は、アップロードするものが何もないことを示す。.がデフォルトになる(検証済み。--helpには記載がない)。gcloud builds submitを実行すると、Cloud Buildがそのプロジェクトに[PROJECT_ID]_cloudbuildという名前のCloud Storageバケットを作成する。--regionで指定したロケーションのホスト環境上で行われ、Cloud Storageにアップロードされたファイルが入力として使用される。
デフォルトでは、Cloud Build でビルドを実行すると、ビルドは公共のインターネットにアクセスできる安全なホスト環境で実行されます。各ビルドは独自のワーカー上で実行され、他のワークロードから分離されます。
--tagが指定されている場合は、イメージのビルドを行い、指定された名前でタグ付けしてリポジトリにpushする。
gcr.io/cloud-builders/dockerのはず(?)。--configが指定されている場合は、指定された構成ファイルに基づいて処理が行われる。--packが指定されている場合は、buildpacksを使ってビルド・pushする。gcloud builds submit --config cloudbuild.yaml [SOURCE_DIRECTORY]
nameでクラウドビルダーを指定できる。たとえば以下のようなもの。
gcr.io/cloud-builders/dockergcr.io/cloud-builders/gcloudgcr.io/cloud-builders/kubectlgcloud builds submit --tag [IMAGE_URL] [SOURCE_DIRECTORY]
IMAGE_URLは[ホスト名]/[プロジェクトID]/[リポジトリ名]/[イメージ名]:[タグ]である必要がある。gcloud builds submit --pack image=[IMAGE_URL]
docker build . --tag [IMAGE_URL]
gcloud auth configure-docker # 初回のみ。認証設定
docker push [IMAGE_URL]
packコマンドのインストールが必要。gcloud auth configure-docker
pack build --publish [IMAGE_URL]
pack build --builder=gcr.io/buildpacks/builder [NAME]docker compose upで確認したほうが効率は良い(IMO)。POST https://cloudbuild.googleapis.com/v1/projects/{projectId}/buildsであり、リファレンスを見る限り、ソースコードは手動でアップロード済みである前提でこのAPIをコールする必要がありそう。
gcloud builds submitは、まず指定されたソースコードをストレージにアップロードし、その後上記のAPIを呼び出しているのではないか、という推測に至った(?)。--tagが付いている場合は、以下のようなstepsを渡しているはず。このargsの中の.は、gcloud builds submitで指定する.とは関係なく、Cloud Buildがgcr.io/cloud-builders/dockerを実行する際のcontextになる。"steps": [{
"name": "gcr.io/cloud-builders/docker",
"args": ["build", "-t", "gcr.io/$PROJECT_ID/my-image", "."]
}]
公式のクイックスタート(https://cloud.google.com/build/docs/build-push-docker-image )を、以下の構成で試した。testディレクトリの中にはquickstart.shを入れていない。
Dockerfile
quickstart.sh
test
└ Dockerfile
gcloud projects create [PROJECT_ID] --organization=[ORGANIZATION_ID]
gcloud --project [PROJECT_ID] services enable cloudbuild.googleapis.com artifactregistry.googleapis.com
gcloud --project [PROJECT_ID] artifacts repositories create quickstart-docker-repo \
--repository-format=docker --location=us-west2 --description="Docker repository"
# (1) ソースコードの場所を指定しない
gcloud --project [PROJECT_ID] builds submit --region=us-west2 \
--tag us-west2-docker.pkg.dev/[PROJECT_ID]/quickstart-docker-repo/quickstart-image:tag1
# (2) ソースコードの場所として ./test を指定する
gcloud --project [PROJECT_ID] builds submit --region=us-west2 \
--tag us-west2-docker.pkg.dev/[PROJECT_ID]/quickstart-docker-repo/quickstart-image:tag2 ./test
gcloud projects delete [PROJECT_ID]
.がソースコードとしてCloud Storageへアップロードされた。実行時にUploading tarball of [.] to [gs://[PROJECT_ID]_cloudbuild/source/...]というメッセージが出ていた。./testの中身がアップロードされ、ビルド時にquickstart.shがないためエラーとなった。testの中にquickstart.shを入れて再実行したところ成功した。.が指定される(--helpに記載がなかったのでフィードバックした)。--tagを指定している場合、docker実行時のcontextは.になる。これはソースコードのディレクトリの指定とは無関係。Dockerがビルド時に入力とするソースコードはCloud Storageから取得されるデータであり、その中身は「指定したディレクトリ」ではなく「ディレクトリの中身」が入るため、.以外をcontextにするとエラーになるはず。google.devtools.cloudbuild.v1.CloudBuild.CreateBuildのAPIが記録されていた。RPC定義のpostは https://cloud.google.com/build/docs/api/reference/rest/v1/projects.builds/create と一致している。ただし、ログ上ではリクエストbodyの中身が分からないため、argsとしてcontextの.を指定していることまでは確認できなかった。
COMMIT_SHAやSHORT_SHAは、トリガーで呼ばれるビルド(GitHub連携のCIなど)を対象にデフォルトで用意されているもの。--substitutionsで指定すれば上書きできる。substitutions(置換変数と値のmap)に該当の置換変数が存在しない場合はエラーになる。
substitutionsフィールドで指定しても、--substitutionsで指定してもよい。substitutionsフィールドや--substitutionsで指定した置換変数がフローの中に存在しない場合もエラーになる。options:
substitution_option: 'ALLOW_LOOSE'
imagesフィールドで指定してもレジストリへのpushは実現できる。後者だとビルド結果にイメージが表示される。imagesを併用することも可能。--cache-fromを使った最適化
waitForを使った並行処理
stepsで失敗したときは特にリトライ処理はされない。imagesフィールドによるpushは失敗した際に10回リトライを行った後、以下のようなメッセージが出力される。ERROR: failed to push because we ran out of retries.
〜 retry budget exhausted (10 attempts): step exited with non-zero status: 1
- "--tag"
- "test0000"
- "--tag test0000"
ERROR: (gcloud.run.deploy) unrecognized arguments:
PROJECT_NUMBER@cloudbuild.gserviceaccount.com。現在は「Cloud Buildレガシーサービスアカウント」と呼ばれる)PROJECT_NUMBER-compute@developer.gserviceaccount.com)roles/iam.serviceAccountUserをCloud Buildのサービスアカウントが保持している必要がある。
ERROR: (gcloud.beta.run.jobs.deploy) User [[PROJECT_NUMBER]@cloudbuild.gserviceaccount.com] does not have permission to access namespaces instance [[PROJECT_ID]] (or it may not exist): The caller does not have permission
(1) プロジェクト全体のroles/iam.serviceAccountUserを与える。範囲が広いので本番ではやらないほうがよい。
gcloud projects add-iam-policy-binding [PROJECT_ID] \
--member=serviceAccount:[CLOUD_BUILD_SA_EMAIL] \
--role=roles/iam.serviceAccountUser
(2) Cloud Runのサービスアカウントに紐づくroles/iam.serviceAccountUserを与える。こちらのほうが最小限で望ましい。
ユーザー指定のCloud Runのサービスアカウントの場合:
gcloud iam service-accounts add-iam-policy-binding \
[SA_NAME]@[PROJECT_ID].iam.gserviceaccount.com \
--member="serviceAccount:[CLOUD_BUILD_SA_EMAIL]" \
--role="roles/iam.serviceAccountUser"
デフォルトのCloud Runのサービスアカウントの場合:
gcloud iam service-accounts add-iam-policy-binding \
[PROJECT_NUMBER]-compute@developer.gserviceaccount.com \
--member="serviceAccount:[CLOUD_BUILD_SA_EMAIL]" \
--role="roles/iam.serviceAccountUser"