**このページの改善にご協力ください** このユーザーガイドに貢献するには、すべてのページの右側のペインにある「**GitHub でこのページを編集する**」リンクを選択してください。 # 以前の Kubernetes バージョンにクラスターをロールバックする Amazon EKS バージョンロールバックを使用すると、インプレースアップグレードの実行後に、クラスターの Kubernetes コントロールプレーンを以前のマイナーバージョンに戻すことができます。アップグレード後に、アプリケーションの非互換性、廃止された API の使用、予期しない動作などの問題が発生した場合は、ロールバックしてクラスターを既知の正常な状態に復元できます。 ロールバック中、Amazon EKS は Kubernetes API サーバーとコントロールプレーンのコンポーネントを以前のバージョンに戻すと同時に、すべての etcd データ、顧客ワークロード、および永続ボリュームを保持します。 ## ロールバックされるもの 以下のコンポーネントがロールバックされます: + Kubernetes API サーバーバージョン + コントロールプレーンコンポーネントとその設定 + プラットフォームバージョン (以前の Kubernetes バージョンの最新のプラットフォームバージョンに戻ります) + **EKS Auto Mode ワーカーノード**。EKS Auto Mode を実行しているクラスターでは、Amazon EKS はコントロールプレーンを元に戻す前に Auto Mode ワーカーノードのロールバックを自動的に管理します。詳細については、「[EKS Auto Mode クラスターをロールバックする](rollback-automode.md)」を参照してください。 ## ロールバックされないもの 以下のコンポーネントはロールバックされません: + **etcd データ**。クラスターの状態、リソース、設定はすべて保持されます。 + **顧客ワークロード**。ポッド、デプロイ、サービスは引き続き実行されます。 + **EKS アドオン**。アドオンバージョンは変更されません。これらを個別に管理します。 + **永続的なボリュームとデータ**。すべての顧客データはそのまま残ります。 + **セルフマネージドノードとハイブリッドノード**。これらをロールバックするのはユーザーの責任です。 + **マネージドノードグループ** `UpdateNodegroupVersion` API を使用して、これらを個別にロールバックする必要があります。 ## 前提条件 クラスターをロールバックする前に、以下の条件をすべて満たす必要があります: | 要件 | 詳細 | | --- | --- | | **7 日間のウィンドウ** | ロールバックは、アップグレードの完了から 7 日以内に開始する必要があります。7 日を過ぎると、ロールバックは使用できなくなります。 | | **アップグレードされたクラスター** | クラスターは、インプレースアップグレードを通じて現在のバージョンにアップグレードされている必要があります。現在のバージョンで作成されたクラスターはロールバックできません。 | | **単一バージョンのみ** | ロールバックできるのは 1 つのマイナーバージョン (N から N-1) のみです。1.31 から 1.32 にアップグレードしてから 1.33 にアップグレードした場合、1.32 のみにロールバックでき、1.31 にはロールバックできません。 | | **サポートされるバージョン** | バージョンロールバックは、[現在サポートされている Amazon EKS バージョン](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html#kubernetes-release-calendar)で使用できます。 | | **延長サポートポリシー** | サポートが拡張されているバージョンにロールバックするには、まずクラスターのアップグレードポリシーを `EXTENDED` に変更する必要があります。 | | **延長サポート終了時の自動アップグレードなし** | 延長サポートの終了時にクラスターが自動的にアップグレードされた場合、以前のバージョンにロールバックすることはできません。クラスターが標準サポートの終了時に自動的にアップグレードされた場合は、ロールバックできますが、まずアップグレードポリシーを `EXTENDED` に変更する必要があります。 | | **クラスターステータス** | クラスターは `ACTIVE` ステータスである必要があります。別の更新の進行中にロールバックを開始することはできません。 | | **EKS 機能の互換性** | クラスターで有効になっている EKS 機能が以前のバージョンでサポートされていない場合、ロールバックリクエストは失敗します。このチェックを `--force` でバイパスすることはできません。 | 上記の要件に加えて、特定の条件では、`--force` フラグを使用してもロールバックが不可能になります。これらの条件には、クラスターが現在のバージョンで作成されたか、アップグレードから 7 日よりも経過しているか、クラスターが既に新しいバージョンに再度アップグレードされているか、下位互換性のない EKS 機能が現在のバージョン境界で有効になっていることが含まれます。 ## 概要 Amazon EKS クラスターのロールバックプロセスの概要は以下のとおりです: 1. ロールバックの準備状況インサイトを確認して、ロールバックに影響する可能性のある問題を特定します。 1. ブロックの問題 (ERROR ステータスのインサイト) を解決するか、`--force` を使用してインサイトチェックをバイパスします。 1. アプリケーション、カスタムコントローラー、およびサードパーティーツールが以前の Kubernetes バージョンと互換性があることを確認します。 1. ワーカーノードがコントロールプレーンと同じ Kubernetes バージョンを実行している場合は、まずワーカーノードをロールバックします。 1. 以前の Kubernetes バージョンと互換性のないバージョンを実行しているアドオンがある場合は、互換性のあるバージョンにダウングレードします。 1. コントロールプレーンのロールバックを開始します。 1. ロールバックの進行状況をモニタリングします。 **重要** EKS Auto Mode を実行しているクラスターでは、ステップ 4 は自動的に処理されます。ロールバックを開始すると、Amazon EKS はコントロールプレーンの前に Auto Mode ノードをロールバックします。詳細については、「[EKS Auto Mode クラスターをロールバックする](rollback-automode.md)」を参照してください。 ## ステップ 1: ロールバックの準備状況インサイトを確認する Amazon EKS は、ポイントインタイムロールバック準備状況チェックに対してクラスターを自動的に評価し、クラスターインサイトを通じて問題を `ROLLBACK_READINESS` カテゴリに表示します。これらのインサイトは、アップグレードの実行後に表示され、7 日間のロールバック資格ウィンドウ中も引き続き利用できます。 ### ロールバックの準備状況インサイトの表示 **AWS コンソール:** 1. [Amazon EKS コンソール](https://console.aws.amazon.com/eks/home#/clusters) を開きます。 1. クラスターを選択します。 1. **[アップグレードインサイト]** タブを選択します。ロールバックの準備状況インサイトは、アップグレード後に表示されます。 1. ERROR または WARNING ステータスのインサイトを確認します。 **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 ``` ### インサイトの更新 Amazon EKS では、24 時間ごとにインサイトが更新されます。Amazon EKS コンソールで **[更新]** ボタンを選択するか、CLI を使用して、問題を解決した後に手動で更新をトリガーできます。 ``` aws eks start-insights-refresh \ --cluster-name my-cluster \ --region us-west-2 ``` **注記** Amazon EKS は、ロールバックを開始するとインサイトを自動的に更新し、最新のクラスター状態に対してチェックが実行されることを確認します。 ### インサイトステータスの動作 次の表に、各インサイトステータスの意味とロールバックへの影響を示します。 | ステータス | 意味 | ロールバックへの影響 | | --- | --- | --- | | **PASSING** | このチェックで問題が検出されませんでした | ロールバックが許可されました | | **WARNING** | 潜在的な問題が検出されましたが、ブロックはされていません | ロールバックが許可されました (アドバイザリのみ) | | **ERROR** | ブロックの問題が検出されました | 解決されるまでロールバックがブロックされます。または、`--force` を使用してバイパスします | | **UNKNOWN** | ステータスを判断できません | 解決されるまでロールバックがブロックされます。または、`--force` を使用してバイパスします | **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` を使用すると、すべてのインサイトチェック (ERROR、WARNING、UNKNOWN) がバイパスされ、ロールバックが直接続行されます。Amazon EKS は、インサイトチェックがバイパスされたときにロールバックの安全性を保証できません。発生した問題については、ユーザーが全責任を負うものとします。 `--force` フラグはインサイトチェックのみをバイパスします。7 日間のウィンドウ、作成バージョンチェック、シーケンシャルロールバックチェックなどの前提条件の検証はバイパスされません。Auto Mode クラスターでは、`--force` は中断コントロールを上書きしません。NodePool の中断予算、PDB、および do-not-disrupt 注釈は引き続き適用されます。 ## ステップ 2: ワーカーノードを準備する コントロールプレーンをロールバックする前に、ワーカーノードがターゲットバージョンと互換性があることを確認してください。Kubernetes バージョンスキューポリシーでは、ワーカーノードがコントロールプレーンより新しいバージョンを実行できないことが必要です。 ### EKS 自動モード 対処は必要ありません。ロールバックを開始すると、Amazon EKS はコントロールプレーンの前に自動モードノードを自動的にロールバックします。詳細については、「[EKS Auto Mode クラスターをロールバックする](rollback-automode.md)」を参照してください。 ### マネージドノードグループ (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 コンソールを使用してクラスターをロールバックする 1. [Amazon EKS コンソール](https://console.aws.amazon.com/eks/home#/clusters) を開きます。 1. クラスターを選択します。 1. **[アクション]** ドロップダウンメニューを選択します。 1. **ロールバッククラスターバージョン**を選択します。 1. インサイトの警告を含むロールバックの概要を確認します。 1. **ロールバックバージョン**を選択します。 ロールバックは完了までに数分かかることがあります。Auto Mode クラスターの場合、ノードのロールバックフェーズに時間がかかる場合があります。詳細については、「[EKS Auto Mode クラスターをロールバックする](rollback-automode.md)」を参照してください。 ### 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": [] } } ``` **注記** Amazon EKS は、インサイトデータが古い場合、ロールバックを実行する前にインサイトの更新を実行します。 ## ステップ 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 コンソール:** 1. [Amazon EKS コンソール](https://console.aws.amazon.com/eks/home#/clusters) を開きます。 1. クラスターを選択します。 1. **[更新履歴]** タブを選択します。 1. ロールバックに関連付けられた更新 ID を見つけて、現在のステータスを表示します。 ### ステータスの遷移 標準クラスターの場合 (自動モードなし): ``` InProgress → Successful InProgress → Failed ``` Auto Mode クラスターでは、ノードがロールバックしている間はクラスターのステータスは `ACTIVE` のまま維持され、コントロールプレーンのロールバックが開始された場合にのみ `UPDATING` に変わります。`describe-update` を使用して、全体的なロールバックの進行状況を追跡します。詳細については、「[EKS Auto Mode クラスターをロールバックする](rollback-automode.md)」を参照してください。 `Successful` ステータスが表示されると、ロールバックは完了です。 ## 考慮事項と警告 ### インサイトはベストエフォートかつポイントインタイムです クラスターインサイトは、ロールバックがトリガーされた時点で評価されます。インサイトがチェックされた後であるが、ロールバックが完了する前にクラスターに変更を加えた場合 (新しい API を使用したリソースの作成など)、これらの変更は最初のインサイトチェックではキャプチャされず、ロールバックの完了後に問題が発生する可能性があります。 ### etcd データの保持 Amazon EKS はロールバック中に etcd データを保持します。`--force` フラグを使用してバイパスされた互換性のないリソースは保持され、ガベージコレクションされません。 ### 延長サポート料金 標準サポートのバージョンから延長サポートのバージョンにロールバックすると、クラスターで延長サポート料金が発生します。例えば、1.30 (延長サポート) から 1.31 (標準サポート) にアップグレードしてから 1.30 にロールバックすると、延長サポート料金が再開されます。 ### ロールバックの責任共有モデル Amazon EKS は、Kubernetes コントロールプレーンを希望のバージョンにロールバックします。責任共有モデルの一環として、ユーザーはアプリケーションの以前のバージョンとの互換性を検証する責任があります。 + Amazon EKS は、コントロールプレーンコンポーネントを安全に元に戻す責任があります。 + ユーザーは、アプリケーション、設定、および依存関係が以前のバージョンと互換性があることを確認する責任があります。 + ユーザーは、バージョン間の非互換性を確認し、クラスターへの影響を評価し、問題を軽減する必要があります。 ### CloudFormation スタックのロールバック動作 AWS CloudFormation スタックの更新が失敗し、スタックのロールバックがトリガーされた場合、より低い Kubernetes バージョンを指定する以前のテンプレートバージョンに戻しても、クラスターバージョンのロールバックはトリガーされません。バージョンのロールバックは、`UpdateClusterVersion` API、CLI、またはコンソールを使用して明示的に開始する必要があります。 ## ロールバックとアドオン Amazon EKS は、クラスターバージョンのロールバック中にアドオンバージョンを自動的にロールバックしません。アドオンバージョンは個別に管理する必要があります。 コントロールプレーンをロールバックする前に: 1. ロールバックの準備状況インサイトを使用して、ターゲットバージョンとのアドオンの互換性を確認します。 1. アドオンバージョンが以前の Kubernetes バージョンと互換性がない場合は、まずそれをダウングレードします。 ``` aws eks update-addon \ --cluster-name my-cluster \ --addon-name vpc-cni \ --addon-version v1.22.4-eksbuild.3 \ --region us-west-2 ``` 1. コントロールプレーンのロールバックが完了したら、すべてのアドオンが正しく機能していることを確認します。 **注記** ロールバックの準備状況インサイトは、EKS マネージドアドオンバージョンのみをチェックします。セルフマネージドアドオンでは、ユーザーはロールバックする前にターゲットバージョンとの互換性を検証する責任があります。 ## 関連リソース + [EKS Auto Mode クラスターをロールバックする](rollback-automode.md) + [既存のクラスターを新しい Kubernetes バージョンに更新する](update-cluster.md) + [Kubernetes バージョンアップグレードの準備およびクラスターインサイトでの設定ミスのトラブルシューティング](cluster-insights.md) + [Amazon EKS での Kubernetes バージョンのライフサイクルを理解する](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html) + [マネージドノードグループを更新する](https://docs.aws.amazon.com/eks/latest/userguide/update-managed-node-group.html) + [クラスターのアップグレードのベストプラクティス](https://docs.aws.amazon.com/eks/latest/best-practices/cluster-upgrades.html)