このページの改善にご協力ください

このユーザーガイドに貢献するには、すべてのページの右側のペインにある「GitHub でこのページを編集する」リンクを選択してください。

以前の Kubernetes バージョンにクラスターをロールバックする

Amazon EKS バージョンロールバックを使用すると、インプレースアップグレードの実行後に、クラスターの Kubernetes コントロールプレーンを以前のマイナーバージョンに戻すことができます。アップグレード後に、アプリケーションの非互換性、廃止された API の使用、予期しない動作などの問題が発生した場合は、ロールバックしてクラスターを既知の正常な状態に復元できます。

ロールバック中、Amazon EKS は Kubernetes API サーバーとコントロールプレーンのコンポーネントを以前のバージョンに戻すと同時に、すべての etcd データ、顧客ワークロード、および永続ボリュームを保持します。

ロールバックされるもの

以下のコンポーネントがロールバックされます:

ロールバックされないもの

以下のコンポーネントはロールバックされません:

前提条件

クラスターをロールバックする前に、以下の条件をすべて満たす必要があります:

上記の要件に加えて、特定の条件では、--force フラグを使用してもロールバックが不可能になります。これらの条件には、クラスターが現在のバージョンで作成されたか、アップグレードから 7 日よりも経過しているか、クラスターが既に新しいバージョンに再度アップグレードされているか、下位互換性のない EKS 機能が現在のバージョン境界で有効になっていることが含まれます。

概要

Amazon EKS クラスターのロールバックプロセスの概要は以下のとおりです:

ステップ 1: ロールバックの準備状況インサイトを確認する

Amazon EKS は、ポイントインタイムロールバック準備状況チェックに対してクラスターを自動的に評価し、クラスターインサイトを通じて問題を ROLLBACK_READINESS カテゴリに表示します。これらのインサイトは、アップグレードの実行後に表示され、7 日間のロールバック資格ウィンドウ中も引き続き利用できます。

ロールバックの準備状況インサイトの表示

AWS コンソール:

AWS CLI:

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

特定のインサイトの詳細を取得するには:

aws eks describe-insight \
  --cluster-name my-cluster \
  --region us-west-2 \
  --id <insight-id>

インサイトの更新

Amazon EKS では、24 時間ごとにインサイトが更新されます。Amazon EKS コンソールで [更新] ボタンを選択するか、CLI を使用して、問題を解決した後に手動で更新をトリガーできます。

aws eks start-insights-refresh \
  --cluster-name my-cluster \
  --region us-west-2

インサイトステータスの動作

次の表に、各インサイトステータスの意味とロールバックへの影響を示します。

ERROR または UNKNOWN ステータスのインサイトはロールバックをブロックします。PASSING または WARNING ステータスのインサイトは、ロールバックを妨げません。

ロールバック準備状況チェック

Amazon EKS は、ロールバックの準備状況インサイトの一部として一連のチェックを実行します。これらのチェックでは、API の使用の互換性 (フィールドレベルの変更検出を含む)、クラスターの状態、kubelet バージョンスキュー、kube-proxy バージョンスキュー、およびアドオンバージョンの互換性を評価します。EKS Auto Mode を実行しているクラスターでは、追加のチェックは NodePool 中断予算、do-not-disrupt 注釈、PodDisruptionBudget 設定を評価します。

--force フラグの使用

ロールバックの準備状況インサイトに ERROR ステータスが表示され、問題を解決せずに続行する場合は、--force フラグを使用してすべてのインサイトチェックをバイパスできます。

aws eks update-cluster-version \
  --name my-cluster \
  --kubernetes-version 1.30 \
  --force \
  --region us-west-2

--force フラグはインサイトチェックのみをバイパスします。7 日間のウィンドウ、作成バージョンチェック、シーケンシャルロールバックチェックなどの前提条件の検証はバイパスされません。Auto Mode クラスターでは、--force は中断コントロールを上書きしません。NodePool の中断予算、PDB、および do-not-disrupt 注釈は引き続き適用されます。

ステップ 2: ワーカーノードを準備する

コントロールプレーンをロールバックする前に、ワーカーノードがターゲットバージョンと互換性があることを確認してください。Kubernetes バージョンスキューポリシーでは、ワーカーノードがコントロールプレーンより新しいバージョンを実行できないことが必要です。

EKS 自動モード

対処は必要ありません。ロールバックを開始すると、Amazon EKS はコントロールプレーンの前に自動モードノードを自動的にロールバックします。詳細については、「EKS Auto Mode クラスターをロールバックする」を参照してください。

マネージドノードグループ (MNG)

コントロールプレーンをロールバックする前に、マネージドノードグループを以前のバージョンにロールバックする必要があります。UpdateNodegroupVersion API を使用します:

aws eks update-nodegroup-version \
  --cluster-name my-cluster \
  --nodegroup-name my-nodegroup \
  --kubernetes-version 1.30 \
  --region us-west-2

ノードグループの更新は、構成された更新設定 (maxUnavailable または maxUnavailablePercentage) と更新戦略 (Rolling または Force) を尊重します。

セルフマネージドノードとハイブリッドノード

セルフマネージドノードとハイブリッドノードのロールバックはユーザーの責任です。コントロールプレーンをロールバックする前に、以前の Kubernetes バージョンを使用するようにノード AMI または設定を更新します。

Fargate

バージョンロールバックは Fargate ワーカーノードではサポートされていません。Fargate を使用するクラスターのコントロールプレーンはロールバックできますが、コントロールプレーンと同じ Kubernetes バージョンを実行している Fargate ポッドは、ERROR ステータスの kubelet バージョンスキューインサイトをトリガーします。

Amazon EKS は、Fargate ポッドを古い kubelet バージョンに自動的にロールバックすることはできません。

回避策: コントロールプレーンと同じ Kubernetes バージョンを実行している Fargate ポッドがある場合は、ロールバックを開始する前にそれらのポッドを削除します。次に、コントロールプレーンをロールバックします。残りのポッドは、再デプロイ時にロールバックバージョンで起動します。

または、--force を使用してインサイトチェックをバイパスします。ただし、kubelet バージョンスキュー違反を続行すると、それらのポッドが置き換えられるまで、Fargate ワークロードに予期しない動作が発生する可能性があります。

ステップ 3: クラスターコントロールプレーンをロールバックする

ロールバックを開始するには、AWS コンソール、AWS CLI、または EKS API を使用します。

AWS コンソールを使用してクラスターをロールバックする

ロールバックは完了までに数分かかることがあります。Auto Mode クラスターの場合、ノードのロールバックフェーズに時間がかかる場合があります。詳細については、「EKS Auto Mode クラスターをロールバックする」を参照してください。

AWS CLI を使用してクラスターをロールバックする

以前の (N-1) Kubernetes バージョンで既存の update-cluster-version コマンドを使用します。

aws eks update-cluster-version \
  --name my-cluster \
  --kubernetes-version 1.30 \
  --region us-west-2

レスポンスの例:

{
    "update": {
        "id": "e4091a28-ea14-48fd-a8c7-975aeb469e8a",
        "status": "InProgress",
        "type": "VersionRollback",
        "params": [
            {
                "type": "Version",
                "value": "1.30"
            },
            {
                "type": "PlatformVersion",
                "value": "eks.16"
            }
        ],
        "createdAt": "2026-05-12T16:56:01.082000-04:00",
        "errors": []
    }
}

ステップ 4: ロールバックの進行状況をモニタリングする

Amazon EKS コンソールまたは AWS CLI を使用して、クラスターロールバックのステータスをモニタリングできます。

AWS CLI:

aws eks describe-update \
  --name my-cluster \
  --region us-west-2 \
  --update-id e4091a28-ea14-48fd-a8c7-975aeb469e8a

AWS コンソール:

ステータスの遷移

標準クラスターの場合 (自動モードなし):

InProgress → Successful
InProgress → Failed

Auto Mode クラスターでは、ノードがロールバックしている間はクラスターのステータスは ACTIVE のまま維持され、コントロールプレーンのロールバックが開始された場合にのみ UPDATING に変わります。describe-update を使用して、全体的なロールバックの進行状況を追跡します。詳細については、「EKS Auto Mode クラスターをロールバックする」を参照してください。

Successful ステータスが表示されると、ロールバックは完了です。

考慮事項と警告

インサイトはベストエフォートかつポイントインタイムです

クラスターインサイトは、ロールバックがトリガーされた時点で評価されます。インサイトがチェックされた後であるが、ロールバックが完了する前にクラスターに変更を加えた場合 (新しい API を使用したリソースの作成など)、これらの変更は最初のインサイトチェックではキャプチャされず、ロールバックの完了後に問題が発生する可能性があります。

etcd データの保持

Amazon EKS はロールバック中に etcd データを保持します。--force フラグを使用してバイパスされた互換性のないリソースは保持され、ガベージコレクションされません。

延長サポート料金

標準サポートのバージョンから延長サポートのバージョンにロールバックすると、クラスターで延長サポート料金が発生します。例えば、1.30 (延長サポート) から 1.31 (標準サポート) にアップグレードしてから 1.30 にロールバックすると、延長サポート料金が再開されます。

ロールバックの責任共有モデル

Amazon EKS は、Kubernetes コントロールプレーンを希望のバージョンにロールバックします。責任共有モデルの一環として、ユーザーはアプリケーションの以前のバージョンとの互換性を検証する責任があります。

CloudFormation スタックのロールバック動作

AWS CloudFormation スタックの更新が失敗し、スタックのロールバックがトリガーされた場合、より低い Kubernetes バージョンを指定する以前のテンプレートバージョンに戻しても、クラスターバージョンのロールバックはトリガーされません。バージョンのロールバックは、UpdateClusterVersion API、CLI、またはコンソールを使用して明示的に開始する必要があります。

ロールバックとアドオン

Amazon EKS は、クラスターバージョンのロールバック中にアドオンバージョンを自動的にロールバックしません。アドオンバージョンは個別に管理する必要があります。

コントロールプレーンをロールバックする前に:

関連リソース