[やってみた] EKS のバージョンロールバックができるようになったので試してみた

こんにちは。製造ビジネステクノロジー部所属の hongkii です。

Kubernetes のコントロールプレーンは、上流でロールバックがサポートされていません。そのため EKS でも、一度上げたら下げられないのがこれまでの前提でした。

ところが 2026 年 7 月のアップデートで、インプレースアップグレードが完了してから 7 日以内であれば、ひとつ前のマイナーバージョンに戻せるようになりました。

https://aws.amazon.com/jp/blogs/news/upgrade-amazon-eks-clusters-with-confidence-using-kubernetes-version-rollbacks/

そこで、Terraform で運用しているクラスターを 1.35 から 1.36 に上げ、そこから 1.35 に戻すところまで実際に試してみました。

アップグレードは terraform apply 一回で終わりましたが、ロールバックは同じようにはいきませんでした。

先に結論

どのバージョンにでも下げられるわけではありません。次の条件が付きます。

• インプレースアップグレードが 完了してから 7 日以内
• 戻せるのは 1 つ前のマイナーバージョンまで
• 現在のバージョンに インプレースアップグレードで到達している こと
• クラスターが ACTIVE で、ほかの更新が動いていないこと
• 戻るのは コントロールプレーンだけ。マネージドノードグループとアドオンは自分で戻す

3 つめは戻り先ではなく現在地の条件で、作成時と同じバージョンに戻すこと自体は問題ありません。今回の検証がまさにそれです。

etcd のデータ、Pod や Deployment などのワークロード、PersistentVolume はロールバックの対象外です。つまり、そのまま保持されます。

そして今回いちばん伝えたいのはここです。

• アップグレードは 1 回の apply で済むのに、ロールバックは CLI で 3 段階に分ける ことになる
• ドキュメントが要求する順序と Terraform の依存グラフが逆向きになっている
• アップグレード時にノードを N-1 に残しておくと、戻すときにワークロードを一切触らずに済む

これまでのバージョンアップは片道だった

EKS では長らく、一度上げたバージョンを戻す手段がありませんでした。

これまで EKS のバージョンを上げるときは、いつもサンドボックス環境から始めていました。本番と同じ構成のクラスターを用意し、ワークロードも同じように載せて、そこで先にアップグレードして動作を確認する。問題がなければ同じ手順を本番に適用する、という流れです。

ただ、この進め方はアップグレードそのものより、その前後に時間を取られます。本番に近い環境を組むところ、ワークロードを載せて一通り動作を確認するところ、終わったあとに環境を片付けるところ。バージョンをひとつ上げるだけなのに、毎回そこから始めることになります。似たような進め方をしている方も多いのではないでしょうか。

AWS の発表ブログでも、この前提が次のように説明されています。

オープンソースの Kubernetes はコントロールプレーンのロールバックをサポートしていないため、一度アップグレードしたら後戻りはできません。

その結果どうなっていたか、についても書かれています。

組織はベイク期間、スタッガーグループ、自動サインオフ、数か月にわたるアップグレードサイクルなど、精巧な補償メカニズムを構築する必要に迫られています。

実際、アップグレードで問題が出たときの備えは次のどちらかになっていました。

• 新しいバージョンのクラスターを別に作って、ワークロードを移す（Blue/Green）
• サンドボックス環境で入念に検証してから本番に適用する

Blue/Green はクラスターが二重になるのでコストがかかりますし、API エンドポイントも OIDC プロバイダーも変わるため、周辺の設定を一通り作り直すことになります。

そして、私が取っていたサンドボックスでの事前検証も万能ではありません。廃止された API を使っているマニフェストや、バージョン間の挙動差に依存していたコントローラーは、実際のトラフィックとワークロードが乗ってはじめて表面化することがあります。

戻れないという前提があると、バージョンアップの計画そのものが重くなります。作業ウィンドウを長めに取り、関係者を集め、切り戻し手順を別途用意する。そこまでやっても「上げてみないとわからない」部分が残ります。

今回のロールバックは、この前提を変えるものです。

検証環境

Terraform で作った 1.35 のクラスターを使いました。

小さめの構成です。この記事に出てくる所要時間はこの環境での実測値なので、ほかの環境でそのまま当てはまるものではありません。

Pod が入れ替わったかどうかを見るために、Pod 名と起動時刻を画面に出しています。

アップグレードは Terraform 一回で済む

アドオンのバージョンを aws_eks_addon_version データソースから引くようにしておくと、変数ひとつでクラスターもノードもアドオンも動きます。

今回はバージョンを固定せず、各 Kubernetes バージョンで EKS が既定としているバージョンをそのまま使う構成にしました。

data "aws_eks_addon_version" "kube_proxy" {
  addon_name         = "kube-proxy"
  kubernetes_version = var.kubernetes_version
}

resource "aws_eks_addon" "kube_proxy" {
  cluster_name  = aws_eks_cluster.main.name
  addon_name    = "kube-proxy"
  addon_version = data.aws_eks_addon_version.kube_proxy.version
}

kubernetes_version を 1.35 から 1.36 に変えて terraform apply を実行しました。

Apply complete! Resources: 0 added, 4 changed, 0 destroyed.

全体で 17 分ほど、うちコントロールプレーンが 7 分ほどでした。

今回はアップグレードとロールバックで計 4 回コントロールプレーンを動かしましたが、この環境ではいずれも 7 分から 8 分の範囲でした。

アドオンは 4 つのうち 2 つだけ動きました。kube-proxy と coredns は 1.35 と 1.36 でデフォルトバージョンが違い、vpc-cni と aws-ebs-csi-driver は同じだったためです。

どのアドオンが動くかはバージョンの組み合わせ次第です。あとで出てくる「ロールバック前にアドオンを戻す」手順も、動いたアドオンだけが対象になります。

ロールバックは同じようにはいかない

問題が見つかったので戻す、という想定で kubernetes_version を 1.35 に戻して terraform apply を実行しました。

plan は通ります。

Plan: 0 to add, 5 to change, 0 to destroy.

  ~ aws_eks_addon.coredns
      ~ addon_version = "v1.14.3-eksbuild.14" -> "v1.13.2-eksbuild.21"
  ~ aws_eks_addon.kube_proxy
      ~ addon_version = "v1.36.0-eksbuild.17" -> "v1.35.3-eksbuild.21"
  ~ aws_eks_cluster.main
      ~ version = "1.36" -> "1.35"
  ~ aws_eks_node_group.main
      ~ version = "1.36" -> "1.35"

バージョンに関係する差分は 4 つで、残る 1 つは OIDC プロバイダーの thumbprint_list という無関係な差分です。Terraform は「5 つまとめて戻せます」と言っています。しかし apply は 1 分半ほどで止まりました。

aws_eks_cluster.main: Modifying... [id=my-cluster]
aws_eks_cluster.main: Still modifying... [id=my-cluster, 01m30s elapsed]

Error: waiting for EKS Cluster (my-cluster) version update: unexpected state
'Failed', wanted target 'Successful'. last error: : Unknown: Rollback readiness
issues detected. Call the EKS ListInsights API to view rollback blocking issues
detected by EKS. Pass the force flag to override rollback readiness errors and
proceed with rollback.

動いたのは aws_eks_cluster.main の 1 つだけ です。ノードグループもアドオンも変更されていません。

plan の並び順はリソース名の順で、apply が処理する順ではありません。一覧ではアドオンが先に出ていますが、実際に最初に動いたのはクラスターでした。

エラーの文言が「Rollback readiness issues」になっています。AWS 側はこれをロールバックとして扱っていて、事前チェックで止めています。単にバージョンを下げられなかったわけではありません。

何がブロックしていたのか

エラーが ListInsights を見ろと言っているので、そのまま従いました。本来はアップグレードの前に確認しておくものですが、今回は止められてから見にいく流れになりました。

aws eks list-insights \
  --cluster-name my-cluster \
  --filter '{"categories": ["ROLLBACK_READINESS"]}'

ERROR が 3 件出ていました。

この 3 件は、ドキュメントの手順がロールバックの前にやれと言っていることに対応しています。

4. If your worker nodes are running the same Kubernetes version as the control plane, roll back the worker nodes first.
5. If you have add-ons running versions incompatible with the previous Kubernetes version, downgrade them to a compatible version.
6. Initiate the control plane rollback.

kubelet の 1 件が 4 に、kube-proxy とアドオンの 2 件が 5 に当たります。この 2 つを片付けてから、6 のコントロールプレーンを実行するという順序です。Terraform の依存グラフは逆向きになっています。

図にするとこうなります。上下で同じ 3 つの工程が、逆の順番で並びます。

ドキュメントが最後に置いているコントロールプレーンから、Terraform は始めます。さきほどのエラーは、この 1 つ目で止まったものです。

aws_eks_node_group が cluster_name でクラスターを参照している以上、Terraform はクラスターを先に処理します。参照を保ったままこの順序を入れ替える方法はありません。

同じ時刻に UPGRADE_READINESS のほうも見てみました。

理由の文言はほぼ同じなのに、判定が逆になっています。

アップグレードの観点では「一致している」ことが正常で、ロールバックの観点では「一致している」ことが問題になります。コントロールプレーンを下げた瞬間に kubelet のほうが新しくなってしまうからです。

--force で押し切れるのか

エラーメッセージが force flag に触れているので、先に整理しておきます。CLI には --force があり、インサイトのチェックを飛ばせます。

aws eks update-cluster-version \
  --name my-cluster \
  --kubernetes-version 1.35 \
  --force

ただしドキュメントは、これが飛ばすのはインサイトのチェックだけだと書いています。

The --force flag only bypasses insight checks. It doesn't bypass prerequisite validations such as the 7-day window, creation version check, or sequential rollback check.

7 日を過ぎている、そもそもアップグレードしていない、といった前提条件は --force では通りません。有効になっている EKS の機能が前のバージョンで使えない場合も同様です。

そして ERROR を無視して進めた結果については、こう書かれています。

Amazon EKS can't guarantee the safety of the rollback when insight checks are bypassed. You accept full responsibility for any issues that arise.

今回は --force を使わず、ドキュメント通りの順序で進めました。

ドキュメント通りの順序で戻す

順序を守って CLI で実行し直しました。

まずノードグループです。

aws eks update-nodegroup-version \
  --cluster-name my-cluster \
  --nodegroup-name my-nodegroup \
  --kubernetes-version 1.35

このコマンドはすぐにプロンプトが戻ってきます。実際の入れ替えはこの後ろで進むので、完了を待ってから次に進みます。

aws eks wait nodegroup-active \
  --cluster-name my-cluster \
  --nodegroup-name my-nodegroup

ノードが 1 台ずつ入れ替わるので Pod も動きます。2 台で 9 分ほどかかりました。

次にアドオンを戻します。戻す先のバージョンは、対象の Kubernetes バージョンでのデフォルトを引いてきます。

aws eks describe-addon-versions \
  --addon-name kube-proxy \
  --kubernetes-version 1.35 \
  --query 'addons[0].addonVersions[?compatibilities[?defaultVersion==`true`]].addonVersion' \
  --output text

出てきたバージョンを指定して戻します。

aws eks update-addon \
  --cluster-name my-cluster \
  --addon-name kube-proxy \
  --addon-version v1.35.3-eksbuild.21 \
  --resolve-conflicts OVERWRITE

aws eks wait addon-active \
  --cluster-name my-cluster \
  --addon-name kube-proxy

coredns も同じ手順で戻しました。vpc-cni と aws-ebs-csi-driver は元から動いていないので触りません。

最後にコントロールプレーンです。

aws eks update-cluster-version \
  --name my-cluster \
  --kubernetes-version 1.35

今度は通りました。

{
    "update": {
        "id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
        "status": "InProgress",
        "type": "VersionRollback"
    }
}

type が VersionRollback になっています。通常のアップグレードは VersionUpdate なので、履歴を見れば区別が付きます。

aws eks list-updates --name my-cluster
aws eks describe-update --name my-cluster --update-id <id> \
  --query 'update.{type:type,status:status,created:createdAt}'

ここまでの履歴です。右端は、あとから補足として書き足したものです。

18:25:56  Successful  VersionUpdate      1.35 -> 1.36
18:48:59  Failed      VersionRollback    terraform apply で止まったもの
19:03:25  Successful  VersionRollback    ドキュメント通りの順序で実行

先ほど失敗した terraform apply も VersionRollback として記録されています。AWS 側はあの apply をロールバックの試行として扱っていた、ということがここでも確認できます。

進捗はレスポンスの id を使って確認します。

aws eks describe-update \
  --name my-cluster \
  --update-id a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d \
  --query 'update.status'

InProgress から Successful に変わるまで 8 分ほどでした。ロールバック全体では 17 分ほどです。

ロールバック中も Service は切れなかった

ノードの入れ替わりに合わせて Pod も動きます。kubectl get pods --watch の記録です。

18:56:01  demo-app-...-bwspp   Running
18:56:01  demo-app-...-bwspp   Terminating
18:56:02  demo-app-...-79rcz   Pending
18:56:02  demo-app-...-79rcz   ContainerCreating
18:56:07  demo-app-...-79rcz   Running

退避から新しい Pod が Ready になるまで 6 秒ほどでした。

同時に、Service の Ready なエンドポイント数も 1 秒間隔で記録していました。

18:56:02  ready endpoints: 1
18:56:09  ready endpoints: 2
18:59:03  ready endpoints: 1
18:59:10  ready endpoints: 2

0 になったことは一度もありません。ノードが 1 台ずつ入れ替わり、PodDisruptionBudget が効いて常に 1 つは残っていました。個々の Pod は落ちますが、Service としては切れていません。

ノードを N-1 に残しておくと戻すのが楽になる

ベストプラクティスのドキュメントにこう書かれています。

Separate control plane and data plane upgrades (non-Auto Mode clusters). ... consider upgrading the control plane first and allowing a bake period before upgrading worker nodes. While nodes remain on N-1, the kubelet version skew insight stays in PASSING status. This keeps the rollback path clear without needing to roll back nodes first.

コントロールプレーンだけ先に上げ、ノードは N-1 に置いたまま様子を見る、という進め方です。これを試してみました。

Terraform 側では、ノードグループのバージョンをクラスターのバージョンから切り離しておく必要があります。

resource "aws_eks_node_group" "main" {
  cluster_name = aws_eks_cluster.main.name
  version      = coalesce(var.node_group_kubernetes_version, var.kubernetes_version)
}

node_group_kubernetes_version に 1.35 を入れ、kubernetes_version だけ 1.36 にして apply しました。

Apply complete! Resources: 0 added, 3 changed, 0 destroyed.

変更は 3 つで、ノードグループが plan から消えています。所要時間は 8 分ほどで、ほぼコントロールプレーンの時間だけになりました。

ノードも一緒に上げたときは 17 分ほどだったので、ノードグループの工程がまるごと落ちた形です。台数が増えるほどこの差は開きます。

この状態でインサイトを確認しました。

ERROR が 3 件から 2 件に減りました。理由も変わっています。

All node kubelet versions are at least one version behind the cluster control plane version.

ノードを N-1 に置いておくだけで、kubelet の項目は最初から解消されているわけです。

そしてロールバックです。アドオンを戻してからコントロールプレーンを戻すだけで、ノードグループには一切触りません。

aws eks update-addon --cluster-name my-cluster --addon-name kube-proxy \
  --addon-version v1.35.3-eksbuild.21 --resolve-conflicts OVERWRITE
aws eks wait addon-active --cluster-name my-cluster --addon-name kube-proxy

aws eks update-cluster-version --name my-cluster --kubernetes-version 1.35

コントロールプレーンのロールバックは 8 分ほどで完了しました。

この間、エンドポイント数の記録には変化がありませんでした。アップグレードとロールバックを合わせて 16 分間、ずっと 2 のままです。

Pod の起動時刻も変わっていません。確認用の Pod には、API サーバーのバージョンと自分の起動時刻を表示させています。

▲ コントロールプレーンを上げる前。control plane は v1.35.6

▲ 1.36 に上げた後。control plane の行だけが変わり、Pod 名と started at はそのまま

▲ ロールバック後。control plane が v1.35.6 に戻る

3 枚を並べると、変わっているのは 1 行だけです。

アップグレード前   control plane v1.35.6   pod ...-79rcz   started at 09:56:07 UTC
アップグレード後   control plane v1.36.2   pod ...-79rcz   started at 09:56:07 UTC
ロールバック後     control plane v1.35.6   pod ...-79rcz   started at 09:56:07 UTC

同じ Pod が、アップグレードとロールバックの両方を経ても再作成されていません。コントロールプレーンだけが往復して、ワークロードは何も知らないまま動き続けていました。

Terraform の state はどうなるか

CLI で戻したので、Terraform の state は 1.36 のままです。コードを先に 1.35 へ戻しておいた状態で terraform plan を実行すると、こうなりました。

Note: Objects have changed outside of Terraform

  # aws_eks_cluster.main has changed
  ~ version = "1.36" -> "1.35"

Changes to Outputs:
  ~ cluster_version = "1.36" -> "1.35"

You can apply this plan to save these new output values to the Terraform state,
without changing any real infrastructure.

Plan: の行が出ていません。リソースの変更は 0 件で、出力値だけが差分です。実インフラには触らず、state を実際の状態に合わせるだけで済みます。

ただし terraform plan -detailed-exitcode は差分ありの 2 を返します。CI でこの終了コードを見ている場合は注意が必要です。

Provider 側の対応状況

Provider 側のドキュメントは version 引数について今もこう書いています。

version - (Optional) Desired Kubernetes master version. ... Downgrades are not supported by EKS.

ロールバックを想定した記述にはなっていません。では Provider の対応を待てばいいのかというと、ロールバック対応を求める issue は 2026 年 7 月 2 日に立ってから、この記事を書いている時点まで open のままです。

https://github.com/hashicorp/terraform-provider-aws/issues/48751

ただし、さきほど apply が止まった原因は Provider 側ではなく EKS の事前チェックです。Provider が対応したとしても、ドキュメントが要求する順序が変わるわけではありません。

一方で aws_eks_cluster には force_update_version があり、説明は「upgrade-blocking readiness checks を上書きする」となっています。

CLI の --force に相当しそうな引数ですが、ロールバック時のインサイトにも効くのかは今回試していません。試す場合は --force と同じ注意が必要です。

気をつける点

残りの 7 日はどこにも表示されない

ロールバックできるのはアップグレードが完了してから 7 日以内ですが、その残り時間を返す API はありません。describe-cluster に該当する項目はなく、describe-update が返すのも id status type params createdAt errors までです。完了時刻にあたる項目はありません。

数えるときは、さきほどの describe-update で見た createdAt を使うことになります。直近の VersionUpdate の createdAt に 7 日を足したところが期限の目安です。

createdAt は更新を受け付けた時刻なので、実際の完了時刻より少し早い値です。この環境ではコントロールプレーンの更新が 7 分から 8 分でしたから、7 日に対する差としては小さく、createdAt で数えておけば安全側に倒れます。

インサイトはリアルタイムではない

ノードとアドオンを戻した直後にインサイトを確認したところ、ERROR がそのまま残っていました。それでもロールバックは通りました。

ドキュメントにこう書かれています。

Amazon EKS refreshes insights every 24 hours.
Amazon EKS automatically refreshes insights when you initiate a rollback to make sure that checks are run against the latest cluster state.

ListInsights が返すのは最後に評価した時点の値です。実際にブロックするかどうかは、ロールバックを実行する時点で EKS が再評価して決めます。

手動で更新することもできます。

aws eks start-insights-refresh --cluster-name my-cluster

今回も、ノードを N-1 に残してアップグレードした直後は ROLLBACK_READINESS が 0 件でしたが、これを実行して 90 秒待つと 5 件表示されるようになりました。インサイトの出力だけを見てロールバックの可否を判断するのは危険です。

ロールバック完了と API サーバーへの反映にはずれがある

describe-update が Successful を返し、describe-cluster も 1.35 を返した後のことです。クラスター内から /version を叩くと、まだ v1.36.2 が返ってきていました。

数分後に kubectl version で確認すると v1.35.6 になっていました。

API 上の完了と、実際に API サーバーが新しいバージョンで応答し始めるタイミングには差があります。ロールバック直後に自動テストを走らせる場合は、バージョンを見て待つ処理を入れたほうが安全です。

延長サポートのバージョンに戻すときは追加費用が発生する

標準サポートのバージョンから延長サポートのバージョンに戻すと、延長サポートの料金が再開します。ドキュメントにこう書かれています。

If you roll back from a version under standard support to a version under extended support, your cluster begins incurring extended support charges.

さらに、延長サポートのバージョンに戻すには、先にクラスターのアップグレードポリシーを EXTENDED に変えておく必要があります。今回は 1.35 も 1.36 も標準サポート内だったので、この条件には当たりませんでした。

Fargate は対象外

ドキュメントにあるとおり、Fargate のワーカーノードはロールバックできません。コントロールプレーンのロールバック自体は可能ですが、コントロールプレーンと同じバージョンで動いている Fargate Pod があると kubelet version skew のインサイトが ERROR になります。

ロールバック前にその Pod を削除しておくか、--force で押し切ることになります。

ロールバックしても、動作確認は自分でやる必要がある

ドキュメントは責任分界をはっきり書いています。

Amazon EKS is responsible for safely reverting the control plane components.
You are responsible for making sure that your applications, configurations, and dependencies are compatible with the previous version.

コントロールプレーンが戻っても、その上で動いているものが前のバージョンで問題なく動くかは別の話です。とくにアップグレード後に新しいバージョンでしか使えない API でリソースを作っていた場合、それはロールバック前に消しておく必要があります。

アドオンのデフォルトバージョンは動く

aws_eks_addon_version データソースでデフォルトバージョンを引く構成にしていますが、このデフォルト自体が時間とともに変わります。

1 週間前と今回で aws-ebs-csi-driver のデフォルトが v1.64.0-eksbuild.1 から v1.65.0-eksbuild.1 に上がっていました。

クラスターのバージョンを変えていなくても、apply のタイミングでアドオンだけ動くことがあります。バージョンを固定したい場合は addon_version を直接書く必要があります。

今回試していないこと

この記事の内容は、マネージドノードグループを使ったクラスターで確かめたものです。次の範囲は試していません。

• EKS Auto Mode のクラスター。Auto Mode ではノードのロールバックを EKS が自動で行うため、ここで書いた「ノードを先に戻す」手順そのものが変わります
• self-managed ノードと Fargate
• force_update_version でロールバックのインサイトを飛ばせるかどうか
• アップグレードから 7 日を過ぎた場合の挙動

所要時間もノード 2 台の構成での実測です。

まとめ

アップグレードは terraform apply 一回で終わりました。アドオンのバージョンをクラスターのバージョンから引くようにしておけば、変数ひとつでまとめて上がります。

一方でロールバックは一回では終わりません。ドキュメントはノードグループ、アドオン、コントロールプレーンの順序を要求しますが、Terraform の依存グラフはその逆です。

順序を守らずに apply すると、EKS の事前チェックで止められて最初のリソースで終わります。

そしてアップグレードの進め方によって、戻しやすさが変わります。コントロールプレーンだけ先に上げてノードを N-1 に残しておくと、ロールバック時にノードグループを触る必要がなくなります。

今回の検証では所要時間が半分になり、Pod の再作成が 0 回になりました。

本番のワークロードを抱えているなら、この差は小さくありません。ノードを 1 日置いておくだけで、いざ戻すときに Pod を 1 つも動かさずに済みます。

ロールバックは「アップグレードを取り消すボタン」ではありません。コントロールプレーンだけが戻り、ノードもアドオンもワークロードも自分の責任範囲です。それでも、戻る手段があるとわかっているだけで、バージョンアップの計画はかなり軽くなります。

これからバージョンアップを控えている方の参考になれば幸いです。

参考資料

• Roll back a cluster to a previous Kubernetes version
• Best Practices for Cluster Version Rollback
• Kubernetes バージョンロールバックを使用して自信を持って Amazon EKS クラスターをアップグレードする