既存のクラスターを新しい Kubernetes バージョンに更新する - アマゾン EKS
Amazon EKS Auto Mode の考慮事項概要ステップ 1: アップグレードの準備をするステップ 2: アップグレードに関する考慮事項を確認するステップ 3: クラスターコントロールプレーンを更新するステップ 4: クラスターコンポーネントを更新するAmazon EKS クラスターの Kubernetes バージョンをダウングレードする

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

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

既存のクラスターを新しい Kubernetes バージョンに更新する

Amazon EKS で利用可能な新しい Kubernetes バージョンがある場合には、Amazon EKS クラスターを最新バージョンに更新できます。

重要

クラスターをアップグレードすると、以前のバージョンにダウングレードすることはできません。新しい Kubernetes バージョンに更新する前に、「EKS の Kubernetes バージョンライフサイクルを理解する」およびこのトピック内の更新手順を参照することをお勧めします。

新しい Kubernetes バージョンでは、大幅な変更が加えられている場合があります。このため、本稼働用クラスターで更新を行う前に、新しいバージョンの Kubernetes に対するアプリケーションの動作をテストしておくことをお勧めします。この際は、継続的な統合ワークフローを構築し、新しい Kubernetes バージョンに移行する前にアプリケーションの動作をテストします。

更新プロセスに含まれている Amazon EKS が、更新された Kubernetes バージョンを使用しながら新しい API サーバーノードを起動することで、既存のバージョンを置き換えます。Amazon EKS は、これらの新しいノードで、ネットワークトラフィックの標準インフラストラクチャと準備状況に関するヘルスチェックを実行し、想定どおりに動作していることを確認します。ただし、クラスターのアップグレードを開始すると、一時停止または停止することはできません。これらのヘルスチェックのいずれかが失敗すると、Amazon EKS はインフラストラクチャのデプロイを元に戻します。クラスターは前の Kubernetes バージョンのままになります。この際も、実行中のアプリケーションは影響を受けません。また、クラスターが不確定または回復不可能な状態のままになることもありません。Amazon EKS は定期的にすべてのマネージド型クラスターをバックアップします。さらに、必要に応じてクラスターを復元するメカニズムも存在します。Kubernetes インフラストラクチャの管理プロセスは、継続的に評価、改善されています。

クラスターをアップグレードする際、Amazon EKS には、クラスターの作成時に指定したサブネット内に、最大で 5 つの使用可能な IP アドレスが必要となります。Amazon EKS は、指定したサブネットのいずれかに、新しいクラスターの Elastic Network Interface (ネットワークインターフェイス) を作成します。新しいネットワークインターフェイスは、既存のネットワークインターフェイスがあるのとはｂサブネット内に作成される場合があります。ですので、クラスター作成時に指定したサブネットのいずれでも必要なクラスターとの通信が許可されるよう、セキュリティグループルールを設定します。クラスターの作成時に指定したサブネットのいずれかが存在しない、使用できる十分な IP アドレスがない、または必要なクラスターとの通信を許可するセキュリティグループルールがない場合、更新が失敗する可能性があります。

クラスターの API サーバーエンドポイントに常にアクセスできるように、Amazon EKS では高可用性を備えた Kubernetes コントロールプレーンを提供しており、アップデート実行中に API サーバーインスタンスのローリングアップデートを行います。Kubernetes API サーバーエンドポイントをサポートする API サーバーインスタンスの IP アドレスの変更を考慮するために、API サーバークライアントが再接続を適切に管理しているか確認する必要があります。kubectl の最新バージョンと公式にサポートされている Kubernetes クライアントライブラリは、この再接続プロセスを透過的に実行します。

注記

クラスターの更新の詳細については、「EKS Best Practices Guide」の「Best Practices for Cluster Upgrades」を参照してください。このリソースは、アップグレードを計画し、クラスターのアップグレード戦略を理解するのに役立ちます。

Amazon EKS Auto Mode の考慮事項

  • Amazon EKS Auto Mode のコンピューティング機能は、Kubernetes バージョンのノードを制御します。コントロールプレーンをアップグレードすると、EKS Auto Mode はマネージドノードの段階的な更新を開始します。EKS Auto Mode は、ポッドの停止状態の予算を尊重します。

  • コンピューティングの自動スケーリング、ブロックストレージ、ロードバランシング機能など、Amazon EKS Auto Mode の機能を手動でアップグレードする必要はありません。

概要

Amazon EKS クラスターのアップグレードプロセスの概要は以下のとおりです。

  1. クラスターがアップグレードをサポートする状態であることを確認します。これには、クラスターにデプロイされたリソースで使用されている Kubernetes API をチェックし、クラスターに正常性の問題がないことを確認することが含まれます。クラスターのアップグレードの準備状況を評価する際には、Amazon EKS のアップグレードインサイトを使用する必要があります。

  2. コントロールプレーンを次のマイナーバージョンにアップグレードします (1.31 から 1.32 など)。

  3. データプレーン内のノードをコントロールプレーンのノードと一致するようにアップグレードします。

  4. その他にクラスターで実行されているアプリケーション (cluster-autoscaler など) がある場合は、そのアプリケーションをアップグレードします。

  5. Amazon EKS が提供するアドオン (デフォルトで含まれるアドオンなど) をアップグレードします。

  6. クラスターと通信しているクライアントがある場合は、そのクライアントをアップグレードします (kubectl など)。

ステップ 1: アップグレードの準備をする

  1. クラスターコントロールプレーンの Kubernetes バージョンと、ノードの Kubernetes バージョンを比較します。

    • クラスターコントロールプレーンの Kubernetes バージョンを取得します。

      kubectl version

    • ノードの Kubernetes バージョンを取得します。このコマンドでは、セルフマネージド型およびマネージド型の Amazon EC2、Fargate、およびハイブリッドノードがすべて返されます。各 Fargate Pod は、独自のノードとしてリストされます。

      kubectl get nodes

    コントロールプレーンを新しい Kubernetes バージョンに更新する前に、クラスター内のマネージド型ノードと Fargate ノードの双方の Kubernetes マイナーバージョンが、コントロールプレーンのバージョンと同じであることを確認してください。例えば、コントロールプレーンがバージョン 1.29 を実行し、かつノードの 1 つがバージョン 1.28 を実行している場合、コントロールプレーンを 1.30 に更新する前に、ノードをバージョン 1.29 に更新する必要があります。また、コントロールプレーンを更新する前に、セルフマネージド型ノードとハイブリッドノードをコントロールプレーンと同じバージョンに更新することをお勧めします。詳細についてはクラスターのためにマネージドノードグループを更新する、クラスターのためにセルフマネージドノードを更新する、およびクラスターのハイブリッドノードをアップグレードするを参照してください。Fargate ノードのマイナーバージョンがコントロールプレーンのバージョンよりも古い場合、まずノードの示す Pod を削除します。次に、コントロールプレーンを更新します。残りの Pod は、再デプロイ後に新しいバージョンに更新されます。

  2. 最初にクラスターにデプロイした Kubernetes バージョンが Kubernetes 1.25 以降だった場合、このステップをスキップしてください。

    デフォルトでは、Amazon EKS クラスターで Pod セキュリティポリシーのアドミッションコントローラーが有効化されています。クラスターを更新する前に、適切な Pod のセキュリティポリシーが指定されていることを確認してください。これは、潜在的なセキュリティの問題を回避するためのものです。kubectl get psp eks.privileged コマンドを使用して、デフォルトのポリシーを確認できます。

    kubectl get psp eks.privileged

    以下のエラーが表示された場合は、先に進む前に「Amazon EKS のデフォルトの Pod セキュリティポリシー」を参照してください。

    Error from server (NotFound): podsecuritypolicies.extensions "eks.privileged" not found

  3. 最初にクラスターにデプロイした Kubernetes バージョンが Kubernetes 1.18 以降だった場合、このステップをスキップしてください。

    CoreDNS マニフェストから、廃止された単語を削除する必要が生じる場合があります。

    1. CoreDNS マニフェストに、upstream というワードのみの行があるかどうかを確認します。

      kubectl get configmap coredns -n kube-system -o jsonpath='{$.data.Corefile}' | grep upstream

      出力が返されない場合は、マニフェストにこの行は含まれていません。この場合は、次のステップに進みます。upstream というワードが返された場合は、その行を削除します。

    2. ConfigMap ファイルで、ファイルの先頭付近にある、upstream のみを含む行を削除します。このファイル内の他の部分は変更しないでください。行を削除したら、変更を保存します。

      kubectl edit configmap coredns -n kube-system -o yaml

ステップ 2: アップグレードに関する考慮事項を確認する

Amazon EKS クラスターインサイトは、非推奨の Kubernetes API の使用など、Kubernetes バージョンのアップグレードに影響を与える可能性のある問題のリストに照らして、クラスターを自動的にスキャンします。Amazon EKS は、Kubernetes プロジェクトの変更の評価に基づいて、実行するインサイトチェックのリストを定期的に更新します。また、Amazon EKS は、新しいバージョンに伴って Amazon EKS サービスに変更が導入された際にも、インサイトチェックのリストを更新します。詳細については、「クラスターインサイトを使用した Kubernetes バージョンアップグレードの準備」を参照してください。

Kubernetes ドキュメントの「Deprecated API Migration Guide」を確認してください。

  • バージョン 1.23 に更新してクラスターで Amazon EBS ボリュームを使用する場合は、ワークロードの中断を避けるために、クラスターをバージョン 1.23 に更新する前にクラスターに Amazon EBS CSI ドライバーをインストールする必要があります。詳細については、「Amazon EBS で Kubernetes ボリュームを保存する」を参照してください。

  • Kubernetes 1.24 およびそれ以降では、デフォルトのコンテナランタイムとして containerd が使用されます。containerd ランタイムに切り替える予定で、既に Fluentd が Container Insights 用に構成されている場合は、クラスターを更新する前に Fluentd を Fluent Bit に移行する必要があります。Fluentd パーサーは JSON 形式のログメッセージのみを解析するように構成されています。dockerd とは異なり、containerd コンテナランタイムには JSON 形式ではないログメッセージがあります。Fluent Bit に移行しないと、構成された Fluentd パーサーの一部が Fluentd コンテナ内で大量のエラーを生成します。移行の詳細については、「CloudWatch Logs へログを送信する DaemonSet として Fluent Bit を設定する」を参照してください。

    • Amazon EKS は可用性の高いコントロールプレーンを実行しているため、一回に更新できるのはマイナーバージョン 1 つのみです。この要件の詳細については、「Kubernetes Version and Version Skew Support Policy」 (Kubernetes のバージョンおよびバージョンスキューのサポートポリシー) を参照してください。現在のクラスターバージョンが 1.28 であり、1.30 に更新することを仮定します。最初にバージョン 1.28 クラスターをバージョン 1.29 に更新し、次にバージョン 1.29 クラスターをバージョン 1.30 に更新する必要があります。

  • ノード上の Kubernetes kube-apiserver と kubelet 間のバージョンスキューを確認してください。

    • Kubernetes バージョン 1.28 以降、kubelet は kube-apiserver より最大 3 マイナーバージョン古い場合があります。「Kubernetes アップストリームバージョンのスキューポリシー」を参照してください。

    • マネージドノードと Fargate ノードの kubelet が Kubernetes バージョン 1.25 以降の場合は、kubelet バージョンを更新せずに最大 3 バージョン先までクラスターを更新できます。例えば、kubelet がバージョン 1.25 である場合、kubelet のバージョンを 1.25 のままにしていても、Amazon EKS クラスターのバージョンは 1.25 から 1.26、1.27、1.28 に更新できます。

    • マネージドノードと Fargate ノードの kubelet が Kubernetes バージョン 1.24 以前の場合、これは kube-apiserver より 2 マイナーバージョンまでしか古くできません。つまり、kubelet がバージョン 1.24 以前の場合、クラスターを更新できるのは 2 バージョン先までです。例えば、kubelet がバージョン 1.21 の場合、Amazon EKS クラスターのバージョンを 1.21 から 1.22、1.23 に更新できますが、kubelet が 1.21 のままでは、クラスターを 1.24 に更新できません。

  • 更新を開始する前のベストプラクティスとして、ノード上の kubelet がコントロールプレーンと同じ Kubernetes バージョンであることを確認してください。

  • クラスターが 1.8.0 より前のバージョンの Amazon VPC CNI Plugin for Kubernetes で設定されている場合は、クラスターを更新する前に、プラグインを最新バージョンに更新することをお勧めします。プラグインのアップデートについては、「Amazon VPC CNI を使用して Pod に IP を割り当てる」を参照してください。

  • クラスターをバージョン 1.25 以降に更新し、クラスターに AWS Load Balancer Controller をデプロイしている場合は、クラスターのバージョンを 1.25 に更新する前に、コントローラーをバージョン 2.4.7 以降に更新してください。詳細については、「Kubernetes 1.25 リリースノート」を参照してください。

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

重要

Amazon EKS では、特定のクラスターインサイトの問題が発生した際に --force フラグでのクラスターアップグレードが必要となる機能が一時的にロールバックされています。詳細については、GitHub の「Temporary rollback of enforcing upgrade insights on update cluster version」を参照してください。

Amazon EKS は、「最終更新時間」から 24 時間後にクラスターインサイトを更新します。問題に対処した時刻とクラスターインサイトの「最終更新時間」を比較できます。

さらに、非推奨 API の使用に対処した後、インサイトのステータスが更新されるまでに最大 30 日かかる場合があります。アップグレードインサイトは、常に、過去 30 日の期間中の非推奨 API の使用を確認しています。

EKS コントロールプレーンバージョンのアップグレードリクエストは、以下を使用して送信できます。

クラスターの更新 - eksctl

この手順には、eksctl バージョン 0.207.0 以降が必要です。お使いのバージョンは、以下のコマンドを使用して確認できます。

eksctl version

eksctl のインストールと更新の手順については、eksctl ドキュメントの「インストール」を参照してください。

Amazon EKS コントロールプレーンの Kubernetes バージョンを更新します。<cluster-name> をクラスター名に置き換えます。<version-number> は、Amazon EKS がサポートする、クラスターの更新先のバージョン番号に置き換えてください。サポートされているバージョン番号のリストについては、「EKS の Kubernetes バージョンライフサイクルを理解する」を参照してください。

eksctl upgrade cluster --name <cluster-name> --version <version-number> --approve

この更新は完了までに数分かかることがあります。

「ステップ 4: クラスターコンポーネントを更新する」に進みます。

クラスターの更新 - AWS コンソール

  1. Amazon EKS コンソールを開きます。

  2. アップグレードするクラスターに対して [今すぐアップグレード] を選択します。

  3. クラスターの更新先のバージョンを選択し、[アップグレード] を選択します。

  4. この更新は完了までに数分かかることがあります。「ステップ 4: クラスターコンポーネントを更新する」に進みます。

クラスターの更新 - AWS CLI

  1. AWS CLI がインストールされ、ログインしていることを確認します。詳細については、「AWS CLI の最新バージョンのインストールまたは更新」を参照してください。

  2. 次の AWS CLI コマンドを使用して、Amazon EKS クラスターを更新します。アップグレードするクラスターの <cluster-name> と <region-code> を置き換えます。<version-number> は、Amazon EKS がサポートする、クラスターの更新先のバージョン番号に置き換えてください。サポートされているバージョン番号のリストについては、「EKS の Kubernetes バージョンライフサイクルを理解する」を参照してください。

    aws eks update-cluster-version --name <cluster-name> \
  --kubernetes-version <verion-number> --region <region-code>

    出力例は次のとおりです。

    {
    "update": {
        "id": "<update-id>",
        "status": "InProgress",
        "type": "VersionUpdate",
        "params": [
            {
                "type": "Version",
                "value": "<version-number>"
            },
            {
                "type": "PlatformVersion",
                "value": "eks.1"
            }
        ],
[...]
        "errors": []
    }

  3. この更新は完了までに数分かかることがあります。クラスター更新のステータスをモニタリングするには、次のコマンドを使用します。同じ <cluster-name> と <region-code> を使用することに加えて、前のコマンドで返された <update-id> を使用します。

    aws eks describe-update --name <cluster-name> \
   --region <region-code> --update-id <update-id>

    Successful ステータスが表示されると、更新は完了です。

  4. 「ステップ 4: クラスターコンポーネントを更新する」に進みます。

ステップ 4: クラスターコンポーネントを更新する

  1. クラスターの更新が完了したら、更新したクラスターでの Kubernetes と同じマイナーバージョンに、ノードを更新する必要があります。詳細についてはクラスターのためにセルフマネージドノードを更新する、クラスターのためにマネージドノードグループを更新する、およびクラスターのハイブリッドノードをアップグレードするを参照してください。Fargate で起動される新しい Pod であれば、クラスターのバージョンと一致する kubelet バージョンを持っています。それまでに存在していた Fargate Pod は変更されていません。

  2. (オプション) クラスターを更新する前に、そのクラスターに Kubernetes Cluster Autoscaler をデプロイしてある場合は、更新後の Kubernetes のメジャーバージョンとマイナーバージョンに一致するように、Cluster Autoscaler を最新バージョンに更新します。

    1. ウェブブラウザで Cluster Autoscaler のリリースページを開き、クラスターの Kubernetes メジャーバージョンとマイナーバージョンに一致する最新の Cluster Autoscaler バージョンを見つけます。例えば、クラスターの Kubernetes バージョンが 1.30 である場合、1.30 で始まる最新の Cluster Autoscaler リリースを見つけます。次のステップで使用するため、そのリリースのセマンティックバージョン番号 (例: 1.30.n) を書き留めておきます。

    2. 次のコマンドを使用して、Cluster Autoscaler イメージタグを、前のステップで書き留めたバージョンに設定します。必要に応じて、X.XX.X を独自の値に置き換えます。

      kubectl -n kube-system set image deployment.apps/cluster-autoscaler cluster-autoscaler=registry.k8s.io/autoscaling/cluster-autoscaler:vX.XX.X

  3. (GPU ノードを含むクラスターのみ) クラスターに GPU 対応のノードグループ (p3.2xlarge など) がある場合は、クラスターの NVIDIA Device Plugin for Kubernetes DaemonSet を更新する必要があります。次のコマンドを実行する前に、<vX.X.X> を必要となる NVIDIA/k8s-device-plugin バージョンに置き換えます。

    kubectl apply -f https://raw.githubusercontent.com/NVIDIA/k8s-device-plugin/<vX.X.X>/deployments/static/nvidia-device-plugin.yml

  4. Amazon VPC CNI Plugin for Kubernetes、CoreDNS、および kube-proxy アドオンを更新します。サービスアカウントトークンにリストされている最小バージョンに対してアドオンを更新することをお勧めします。

    • Amazon EKS アドオンを使用している場合は、Amazon EKS コンソールで [クラスター] をクリックし、左のナビゲーションペインで更新したクラスター名を選択します。通知がコンソールに表示されます。更新可能なアドオンごとに、新しいバージョンが利用可能であることが通知されます。アドオンを更新するには、[アドオン] タブを選択します。更新があるアドオンが表示されているボックスで [今すぐ更新] を選択し、使用可能なバージョンを選択してから、[更新] を選択します。

    • 別の方法として、AWS CLI または eksctl を使用してアドオンを更新することもできます。詳細については、「Amazon EKS アドオンを更新する」を参照してください。

  5. 必要に応じて、kubectl のバージョンを更新します。Amazon EKS クラスターコントロールプレーンとのマイナーバージョンの相違が 1 つ以内である kubectl バージョンを使用する必要があります。

Amazon EKS クラスターの Kubernetes バージョンをダウングレードする

Amazon EKS クラスターの Kubernetes をダウングレードすることはできません。代わりに、以前の Amazon EKS バージョンで新しいクラスターを作成し、ワークロードを移行します。