KubernetesのRollbackで以前のバージョンに戻す方法｜kubectl rollout undo の手順と戻らないもの

Kubernetes の Deployment で不具合のあるバージョンを出してしまったときは、kubectl rollout undo で直前のリビジョンに戻せます。戻す前に kubectl rollout history で履歴を確認し、戻した後は kubectl rollout status で完了を確かめる、という3つのコマンドが基本の流れです。この記事では、リビジョンの仕組み、具体的な手順、Helm や GitOps を使っている場合の戻し方、そしてロールバックでは戻らないものまでを説明します。

ロールバックの仕組み：リビジョンと ReplicaSet

Deployment は、Pod の設定（.spec.template）が変わるたびに新しい ReplicaSet を作り、古い ReplicaSet は Pod 数を0にして残しておきます。この残された ReplicaSet の1つ1つが「リビジョン」です。ロールバックとは、古い ReplicaSet の Pod テンプレートを使って、もう一度ローリングアップデートを行う操作です。

ここから分かる重要な点が2つあります。

• リビジョンが作られるのは Pod テンプレートが変わったときだけです。 イメージや環境変数、リソース指定の変更はリビジョンになりますが、kubectl scale による Pod 数の変更はリビジョンになりません。
• 残せるリビジョンの数には上限があります。 .spec.revisionHistoryLimit で決まり、既定値は10です。0にすると古い ReplicaSet が残らず、ロールバックできなくなります。

手順1：履歴を確認する

まず、どのリビジョンがあるかを確認します。

kubectl rollout history deployment/web -n production

deployment.apps/web
REVISION  CHANGE-CAUSE
3         image updated to 1.4.0
4         image updated to 1.5.0
5         image updated to 1.5.1

CHANGE-CAUSE 列には、Deployment の kubernetes.io/change-cause アノテーションの値が表示されます。以前は kubectl apply --record で自動記録していましたが、このフラグは非推奨になっています。変更のたびに次のようにアノテーションを付けておくと、履歴から目的のリビジョンを探しやすくなります。

kubectl annotate deployment/web -n production \
  kubernetes.io/change-cause="image updated to 1.5.1" --overwrite

特定のリビジョンの中身（イメージや環境変数）を確認するには --revision を付けます。戻し先を決める前に、ここでイメージのタグが期待どおりかを確かめてください。

kubectl rollout history deployment/web -n production --revision=4

手順2：ロールバックを実行する

直前のリビジョンに戻す場合と、リビジョン番号を指定して戻す場合があります。

# 直前のリビジョンに戻す
kubectl rollout undo deployment/web -n production

# 特定のリビジョンに戻す
kubectl rollout undo deployment/web -n production --to-revision=3

# 実行前に、適用される内容だけを確認する
kubectl rollout undo deployment/web -n production --to-revision=3 --dry-run=server

ロールバックを実行すると、戻し先のリビジョンは新しい番号で履歴の最後に付け直されます。たとえばリビジョン3に戻すと、それはリビジョン6になり、履歴から3は消えます。「戻したのに番号が増えた」と混乱しやすい点です。

手順3：完了を確認する

kubectl rollout status deployment/web -n production --timeout=5m
kubectl get pods -n production -l app=web

rollout status は、新しい Pod がすべて準備完了になるまで待ち、成功すれば終了コード0で終わります。CI のスクリプトから使う場合は、--timeout を付けて待ち時間に上限を設けます。

Pod が起動しない場合は、kubectl describe pod のイベント欄と kubectl logs を確認します。古いイメージがレジストリから削除されていると ImagePullBackOff になり、ロールバックできません。レジストリの保持期間の設定は、ロールバックできる範囲を左右するので確認しておいてください。

失敗した更新は自動では戻らない

Kubernetes の Deployment には、更新に失敗したときに自動で前のバージョンへ戻す機能はありません。決められた時間（.spec.progressDeadlineSeconds、既定600秒）内に更新が進まないと、Deployment の状態に ProgressDeadlineExceeded が記録されますが、そのまま止まるだけです。

被害を小さくするには、更新途中で止まったときに古い Pod が残る設定にしておくことが大切です。

• readinessProbe を設定する。 準備完了と判定されない Pod にはトラフィックが流れず、ローリングアップデートも先に進みません。
• **maxUnavailable を小さくする。** 既定値は25%です。0にすると新しい Pod が準備完了になるまで古い Pod を減らさないため、不具合のある更新でも既存の Pod が動き続けます。

spec:
  revisionHistoryLimit: 10
  progressDeadlineSeconds: 600
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0

自動でロールバックまで行いたい場合は、Argo Rollouts や Flagger のような、カナリアリリースと自動判定の仕組みを持つツールを検討します。

ロールバックで戻らないもの

kubectl rollout undo が戻すのは Deployment の Pod テンプレートだけです。次のものは戻らないため、障害の原因がこれらにある場合はロールバックしても直りません。

• ConfigMap と Secret の中身。 Pod テンプレートが参照する名前は戻りますが、ConfigMap 自体を書き換えていた場合、中身は新しいままです。設定を変えるたびに名前にハッシュやバージョンを付けて新しい ConfigMap を作る運用（Kustomize の configMapGenerator など）にしておくと、ロールバックで設定も戻せます。
• データベースのスキーマやデータ。 マイグレーションで変更したテーブル構造は戻りません。古いバージョンのアプリが新しいスキーマで動くかを事前に確認し、戻せないマイグレーションの前にはバックアップを取ります。
• PersistentVolume 上のファイル。 WordPress を Kubernetes で動かしている場合のアップロードファイルなどがこれに当たります。
• Service や Ingress、HPA など、Deployment 以外のリソース。

また、イメージを latest のような上書きされるタグで指定していると、古いリビジョンに戻しても同じタグが新しいイメージを指しているため、実際には戻らないことがあります。デプロイにはバージョンやコミット ID のタグ、またはダイジェスト指定を使ってください。

Helm や GitOps を使っている場合

Helm

Helm でインストールしたアプリは、Helm のリリース履歴で戻します。Helm は Deployment 以外のリソース（ConfigMap、Service など）もまとめて戻せる点が kubectl rollout undo との違いです。

helm history my-release -n production
helm rollback my-release 3 -n production

Helm 管理下の Deployment を kubectl rollout undo で戻すと、Helm が記録している状態と実際の状態がずれ、次回の helm upgrade で予期しない差分が出ることがあります。Helm を使っているなら Helm で戻すのが原則です。

Argo CD などの GitOps

Git リポジトリの内容をクラスターに同期する GitOps 構成で、自動同期や自己修復を有効にしている場合、kubectl で手動ロールバックしても、すぐに Git の状態へ上書きされます。この場合は、問題のコミットを git revert してリポジトリ側で戻すのが基本です。ツール側にもロールバック機能がありますが、自動同期との併用に制約があるなど、動作はバージョンによって異なるため、使っているツールのドキュメントを確認してください（2026年10月現在）。

GitOps 以外の構成でも、kubectl rollout undo で戻した後は、マニフェストを管理しているリポジトリを同じ状態に更新しておかないと、次のデプロイで不具合のあるバージョンが再び適用されます。

まとめ

• ロールバックは kubectl rollout history で確認、kubectl rollout undo で実行、kubectl rollout status で完了確認、の順に行います。
• リビジョンは Pod テンプレートの変更でのみ作られ、既定で10件まで残ります。
• Deployment は失敗しても自動では戻りません。readinessProbe と maxUnavailable: 0 で被害を抑えます。
• ConfigMap の中身、データベース、永続ボリュームのデータはロールバックで戻りません。
• Helm 管理下なら helm rollback、GitOps なら git revert で戻し、マニフェストの管理元と状態をそろえます。

• Kubernetes の Deployment の使い方
• Kubernetes のヘルスチェック（liveness / readiness probe）の設定