Cloud Run とは、コードやコンテナをクラスタの管理なしで動かす Google Cloud の実行基盤です。
- サービス・revision・traffic の関係と、deploy や環境変数の更新で何が起きるか
gcloud run deploy・gcloud run services update・gcloud run services update-trafficの働きと、戻した後に要る一手- 当社が本番とステージングで踏んだ、配信中の版の読み違いと、そこから決めた測り方
当社は AIエージェント の席を並べて毎日 deploy しています。この頁は、公式の文書の定義と、その運用で踏んだ revision と traffic の記録を並べたものです。
サービス・revision・traffic はどう関係するか
サービスは HTTP の要求に応える単位で、安定した HTTPS の入口を持ちます。コードは最後には必ずコンテナとして動きます。ソースからデプロイすれば、image を自分で作らずに済みます（What is Cloud Run の文書）。
revision は、デプロイや設定の変更のたびに作られる、後から変わらない版です（revision の管理の文書）。環境変数の変更も設定の変更なので、値を 1 つ変えただけでも新しい revision ができます（環境変数の文書）。
運用では、次の層を分けて読みます。
| 場所 | 何を表すか |
|---|---|
spec.template | 次に作る revision の定義。image や環境変数はここにある |
spec.traffic | どの revision へ何割送るかの指定。revisionName・percent・tag・latestRevision で書く |
出典: Google Cloud「Rollbacks, gradual rollouts, and traffic migration」https://docs.cloud.google.com/run/docs/rollouts-rollbacks-traffic-migration （2026-11-06 に確認）。
gcloud run の命令と、revision・traffic への効き方
Cloud Run のデプロイから戻しまでで使う命令を、公式の文書の範囲で並べます。
| やりたい事 | 命令 | 効き方 |
|---|---|---|
| traffic を流さずに新しい版を置く | gcloud run deploy <サービス名> --image <image> --no-traffic --tag <タグ> | 新しい revision は traffic を受けず、タグの専用 URL で試せる |
| 環境変数を足す・変える | gcloud run services update <サービス名> --update-env-vars KEY=VALUE | 指定した鍵だけ変え、他の鍵は残す。新しい revision ができる |
| 環境変数を一覧で置き換える | --set-env-vars | 一覧に無い鍵は消える |
| 環境変数を消す | --remove-env-vars KEY／--clear-env-vars | 指定した鍵だけ消す／全部消す |
| revision を見る | gcloud run revisions list --service <サービス名> --region <リージョン> | 一覧を出す。1 本の詳細は gcloud run revisions describe |
| 前の版へ戻す | gcloud run services update-traffic <サービス名> --to-revisions <revision>=100 | 指定の revision へ全部送る。デプロイ時の健全性の確かめは走り直さない |
| 最新へ戻す | gcloud run services update-traffic <サービス名> --to-latest | 最新の revision へ全部送り、以後に作る revision も traffic を受ける |
| タグを足す・変える | --update-tags <タグ>=<revision> | 他のタグは残る |
| タグを全部決め直す | --set-tags <タグ>=<revision> | 既存のタグを全部消してから付ける |
出典: Google Cloud「Rollbacks, gradual rollouts, and traffic migration」https://docs.cloud.google.com/run/docs/rollouts-rollbacks-traffic-migration ・「Manage revisions」https://docs.cloud.google.com/run/docs/managing/revisions ・「Configure environment variables」https://docs.cloud.google.com/run/docs/configuring/services/environment-variables ・「gcloud run services update-traffic」https://docs.cloud.google.com/sdk/gcloud/reference/run/services/update-traffic （いずれも 2026-11-06 に確認）。
環境変数は DB の認証情報や API キーの置き場としては勧められておらず、公式の文書は Secret Manager を案内しています（環境変数の文書）。秘密の扱いは Secret Manager の頁に書いています。
本番に環境変数を直接当てたら、未昇格の image が配信された
本番の API サービスに gcloud run services update で環境変数を直接当てました。この時サービスの template は、配信中の revision より先に進んでいました。それを確かめずに撃ったので、まだ昇格していない image に環境変数を載せた revision ができ、直後の昇格で 100% になりました。戻すまで 84 秒、その間の要求は 18、5xx は 0 でした（社の実測 2026-10-03）。
以後、デプロイの正本を持つサービスの環境変数は gcloud で直接触りません。触る必要がある時は、先に配信中の revision と template の image が一致するかを測ります（社の実測 2026-10-03）。
# template の image
gcloud run services describe <サービス名> --region <リージョン> --format=json \
| jq -r '.spec.template.spec.containers[0].image'
# 配信中の revision（percent が付いている物）
gcloud run services describe <サービス名> --region <リージョン> --format=json \
| jq -r '.status.traffic[] | select(.percent>0) | "\(.revisionName) \(.percent)"'
# その revision の image
gcloud run revisions describe <revision> --region <リージョン> --format=json \
| jq -r '.spec.containers[0].image'同じ値の update-traffic が、以後の deploy を止めていた
--to-revisions=<今の名前>=100 は、今と同じ配分でも何もしない命令ではありません。latestRevision:True を名前固定に変えます。すると以後の deploy は success と出るのに、新しい revision は traffic を取りません。ステージングでは 17 回の deploy・5 日間、通しの試験が古い版を測っていました。--to-latest で戻しました（社の実測 2026-09-24・2026-09-25・2026-10-21）。
公式の文書にも、以前の revision へ traffic を割り当てると、以後のデプロイでも同じ配分が続くと書かれています（Rollbacks の文書）。deploy の表示だけでは、この状態に気づけません。
| 決まり | 中身 |
|---|---|
| 戻しの後 | 戻しを撃ったら、必ず --to-latest まで済ませる |
| deploy の最後 | 配信中の revision を測って出す |
| 戻せるかの確かめ | 権限の確かめ（describe・get-iam-policy）で足りる |
出典: 社の実測 2026-09-24・2026-09-25・2026-10-21。
--set-tags で、タグの URL が消えた
--set-tags はタグの集合の置き換えです。撃ったら既存の 5 本が消え、約 7 分の間 URL が引けませんでした。100% の traffic は無傷でした。監査ログの ReplaceService で特定し、以後は --update-tags を使っています（社の実測 2026-10-07）。
公式の文書にも --set-tags は既存のタグを先に全部消すと書かれています（update-traffic の文書）。名前の印象で「付ける」と読むと、ここを踏みます。
status.traffic の先頭は、配信中の版とは限らない
status.traffic[0] の先頭に、percent が空のタグ付きの古い revision が来ることがあり、新旧を読み違えました。今は jq の select(.percent>0) で選ぶ形にしています。template の image を本番の版と誤報した事もあり、その版は実際は 0% でした（社の実測 2026-09-19・2026-10-03・2026-10-04・2026-10-18）。
タグだけの revision に percent を書かない形は、公式の文書の例にもあります（Rollbacks の文書）。「配列の先頭」も「template の image」も、配信中の版を指す読み方ではありません。
Ready が True のまま、deploy も戻しも落ちた
Ready は、起動に失敗した revision でも True のまま残りました。spec だけが not ready の revision を 100% で指していて、以後の deploy と戻しが全部落ちたのに、status は無傷に見えました（社の実測 2026-09-20・2026-09-24）。
status だけを読むと、この食い違いは見えません。spec と status を両方読んで見つけます。
--update-env-vars の並びから消しても、本番の鍵は消えない
--update-env-vars の並びから鍵を消しても、本番には残ります。別の鍵で 3 回踏みました（社の実測 2026-10-04・2026-10-10・2026-10-21）。公式の文書の通り、この印は指定していない鍵を残すからです（環境変数の文書）。
消すには --remove-env-vars を使い、spec.template を読んで確かめます（社の実測 2026-10-04・2026-10-10・2026-10-21）。
--service-account も、省くと前のサービスアカウントを引き継ぎます。traffic だけの戻しでは template は戻りませんでした（社の実測 2026-10-04）。
services replace の ALREADY_EXISTS と、revision の番号
--format=export の YAML をそのまま services replace に渡すと、ALREADY_EXISTS で落ちます。revision 名の 1 行を外すと通ります（社の実測 2026-09-21）。
revision の番号は、単調でも一意でもありませんでした。新しい物が 00034 で古い物が 00036 の例と、00036 が接尾辞違いで 2 本ある例が出ています（社の実測 2026-09-21）。番号の大小で新旧を決めず、配信中かどうかは traffic で読みます。
--source の CI が 403 になり、足りたのは 3 点だった
--source の CI が、source のバケットで 403 になりました。バケットを読めないと gcloud は作成に倒れるので、別の権限不足に見えます（社の実測 2026-10-06・2026-10-07）。
足りた最小の組は、次の 3 点です（社の実測 2026-10-06・2026-10-07）。
- 条件付きの storage.admin
- bucketViewer
- build 専用のサービスアカウントへの actAs
gcloud がどの資格情報で撃っているかの確かめ方は gcloud auth の頁に、Cloud Run を定時に呼ぶ形は Cloud Scheduler の頁に書いています。
よくある質問
Cloud Run の revision とは何ですか？
デプロイや設定の変更のたびに作られる、後から変わらない版です（revision の管理の文書）。一覧は gcloud run revisions list で見られます。どの版が配信中かは、traffic の配分で読みます。
Cloud Run の環境変数を変えると、どうなりますか？
新しい revision ができます（環境変数の文書）。--update-env-vars は指定した鍵だけを変え、--set-env-vars は一覧に無い鍵を消します。template が配信中の版より先に進んでいると、未昇格の image まで一緒に出る事があるので、当社は先に両方の image を測ります（社の実測 2026-10-03）。
gcloud run deploy が success なのに、新しい版にならないのはなぜですか？
traffic が名前固定になっている時に起きます。--to-revisions を撃つと latestRevision:True が名前固定に変わり、以後の deploy では新しい revision が traffic を取りません（社の実測 2026-09-24）。gcloud run services update-traffic <サービス名> --to-latest で戻します。
Cloud Run で前の revision に戻すには？
gcloud run services update-traffic <サービス名> --to-revisions <revision>=100 を撃ちます（Rollbacks の文書）。戻しでは traffic だけが動き、template は戻りません（社の実測 2026-10-04）。戻しを撃った後は、必ず --to-latest まで済ませます。
--set-tags と --update-tags はどう違いますか？
--set-tags は既存のタグを全部消してから付け、--update-tags は指定したタグだけを足すか変えます（update-traffic の文書）。既存のタグの URL を生かすなら --update-tags です。
出典
- Google Cloud「What is Cloud Run」https://docs.cloud.google.com/run/docs/overview/what-is-cloud-run （2026-11-06 に確認）
- Google Cloud「Manage revisions」https://docs.cloud.google.com/run/docs/managing/revisions （2026-11-06 に確認）
- Google Cloud「Rollbacks, gradual rollouts, and traffic migration」https://docs.cloud.google.com/run/docs/rollouts-rollbacks-traffic-migration （2026-11-06 に確認）
- Google Cloud「Configure environment variables」https://docs.cloud.google.com/run/docs/configuring/services/environment-variables （2026-11-06 に確認）
- Google Cloud「gcloud run services update-traffic」https://docs.cloud.google.com/sdk/gcloud/reference/run/services/update-traffic （2026-11-06 に確認）
- 社の実測 2026-09-19・2026-09-20・2026-09-21・2026-09-24・2026-09-25・2026-10-03・2026-10-04・2026-10-06・2026-10-07・2026-10-10・2026-10-18・2026-10-21（本番とステージングの Cloud Run の運用の記録）
ブルーランプ 記事の編集部／更新日 2026-11-06