Cloud Run に新しいリビジョンを出した直後に 5xx が増えたとき、コードを直して出し直すより先に、前のリビジョンへトラフィックを戻したい場面があります。この記事では、gcloud run services update-traffic で前のリビジョンに戻す手順と、戻したあとに必ず元へ戻しておくべき設定を説明します。あわせて、デプロイ時にリビジョンへコミットの SHA をラベルとして付けておき、「どのリビジョンがどのコミットか」を後から引けるようにする方法も扱います。
前提の環境は Cloud Run（サービス）と Google Cloud CLI（gcloud）です。2026年11月時点の公式ドキュメントで確かめた内容です。
戻す前に知っておくこと
Cloud Run では、デプロイのたびにリビジョン（その時点のコンテナイメージと設定のスナップショット）が作られ、どのリビジョンに何%のトラフィックを流すかをサービスごとに指定できます。ロールバックは「古いリビジョンに100%を割り当てる」操作で、イメージのビルドもデプロイもやり直しません。
注意点が2つあります。
- トラフィックの切り替えは即座に設定されますが、Cloud Run は戻し先のリビジョンに対してデプロイ時のヘルスチェックを再実行しません。外部の依存先（データベースのスキーマなど）が戻し先のリビジョンと合っているかも確かめません
- 古いリビジョンにトラフィックを割り当てると、その割り当てが以降のデプロイにも引き継がれます。つまり、戻したまま次のデプロイをすると、新しいリビジョンはトラフィックを受けません。詳しくは後の「最新のリビジョンに戻す」で扱います
必要な権限は、コンテナイメージから出したサービスなら Cloud Run デベロッパー（roles/run.developer）と、サービスのサービスアカウントに対するサービス アカウント ユーザー（roles/iam.serviceAccountUser）です。
前のリビジョンに戻す手順
1. リビジョンの一覧を出す
gcloud run revisions list --service=SERVICE --region=REGION
SERVICE はサービス名、REGION はサービスのリージョン（asia-northeast1 など）です。リビジョン名は SERVICE-00012-abc のように、サービス名の後ろに連番と文字列が付いた形になります。
いまトラフィックを受けているリビジョンは、サービスの describe で確かめます。
gcloud run services describe SERVICE --region=REGION --format='yaml(status.traffic)'
status.traffic に、リビジョン名（revisionName）と割合（percent）が並びます。
2. 戻し先のリビジョンに100%を割り当てる
gcloud run services update-traffic SERVICE --region=REGION --to-revisions=REVISION=100
REVISION は戻し先のリビジョン名です。完了すると、戻し先のリビジョンが100%、問題のあったリビジョンが0%を受ける状態になります。
一部だけ戻したいときは、カンマ区切りで割合を並べます。割合の合計は100にします。
gcloud run services update-traffic SERVICE --region=REGION --to-revisions=SERVICE-00012-abc=90,SERVICE-00013-def=10
コンソールから戻す場合は、Cloud Run のサービス一覧から対象のサービスを開き、リビジョンの一覧で戻し先のリビジョンの右にあるメニューから［トラフィックを管理］を選びます。すべてのトラフィックを1つのリビジョンに送る設定にして、戻し先のリビジョンを選んで保存します。
3. 原因を直したら、最新のリビジョンに戻す
ロールバックは応急処置です。原因を直したコードをデプロイする前か後に、トラフィックの割り当てを「常に最新のリビジョン」に戻します。
gcloud run services update-traffic SERVICE --region=REGION --to-latest
--to-latest を打つと、最新のリビジョンと、それ以降にデプロイするリビジョンが100%を受けるようになります。これを忘れると、直したリビジョンをデプロイしても、トラフィックは古いリビジョンに流れたままになります。
CI からデプロイしている場合は、デプロイのジョブの最後で毎回 --to-latest を打つようにしておくと、手で戻したあとに戻し忘れても次のデプロイで外れます。
どのリビジョンがどのコミットかをラベルで引けるようにする
リビジョン名は連番なので、どのコミットから作られたかは名前からは分かりません。戻し先を選ぶときに困らないよう、デプロイ時にコミットの SHA をラベルとして付けておきます。
gcloud run deploy SERVICE --image=IMAGE --region=REGION --labels=commit-sha=${GITHUB_SHA}
--labels は --update-labels の別名で、既にあるキーなら値を書き換え、無ければ追加します。ラベルを付けると、そのラベルを持つ新しいリビジョンが作られます。古いリビジョンにはさかのぼって付きません。ラベルのキーと値は Google Cloud のラベルの規則（英小文字・数字・_・-、63文字以内）に従う必要があり、Git の SHA（40文字の16進数）はそのまま使えます。
リビジョンとラベルの対応は次のように出せます。
gcloud run revisions list --service=SERVICE --region=REGION \
--format='table(metadata.name,metadata.labels.commit-sha)'
デプロイ後に「100%を受けているリビジョンが、いま出したコミットのものか」を確かめる場合も、このラベルを使います。
REV=$(gcloud run services describe SERVICE --region=REGION \
--format='value(status.traffic[0].revisionName)')
gcloud run revisions describe "$REV" --region=REGION \
--format='value(metadata.labels.commit-sha)'
動作を確認する
トラフィックの割り当てを確かめます。
gcloud run services describe SERVICE --region=REGION --format='yaml(status.traffic)'
ロールバック後は、戻し先のリビジョンだけが percent: 100 になっていれば成功です。
status:
traffic:
- percent: 100
revisionName: SERVICE-00012-abc
--to-latest を打った後は、latestRevision: true の行が percent: 100 を持ちます。
status:
traffic:
- latestRevision: true
percent: 100
revisionName: SERVICE-00014-ghi
うまくいかないとき
直したリビジョンをデプロイしたのにトラフィックが流れない
古いリビジョンに割り当てたトラフィックが、以降のデプロイにも引き継がれています。次を打って最新に戻します。
gcloud run services update-traffic SERVICE --region=REGION --to-latest
コンソールからデプロイする場合は、［このリビジョンをすぐに利用する］にチェックを入れてデプロイすると、既存の割り当てを上書きして新しいリビジョンが100%を受けます。
戻したのにエラーが止まらない
戻し先のリビジョンは、ヘルスチェックも外部の依存先の確認もされないまま100%を受けます。新しいリビジョンがデータベースのスキーマや保存するデータの形を変えていた場合、古いリビジョンに戻してもその変更は残ります。この場合はトラフィックを戻すのではなく、データの形に合わせて直したリビジョンを出します。
Terraform で Revision template was empty が出る
Terraform の google_cloud_run_v2_service の traffic ブロックで、まだ存在しないリビジョン名を指定すると次のエラーになります。
Error creating Service: googleapi: Error 400: spec.template.spec: Revision template was empty
traffic の revision には、既にデプロイ済みのリビジョン名を指定します。
サービスが見つからない
サービスと別のリージョンを見に行っている可能性があります。--region を毎回付けるか、run/region プロパティに既定値を設定しておきます。
gcloud config set run/region asia-northeast1
コメント