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

既存のクラスターを新しい 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 クライアントライブラリは、この再接続プロセスを透過的に実行します。

ステップ 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 を削除します。次に、コントロールプレーンを更新します。残りの Pods は、再デプロイ後に新しいバージョンに更新されます。

  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: アップグレードに関する考慮事項を確認する

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

  • Kubernetes 1.24 およびそれ以降では、デフォルトのコンテナランタイムとして containerd が使用されます。containerd ランタイムに切り替える予定で、すでに Fluentd が Container Insights 用に構成されている場合は、クラスターを更新する前に Fluentd を Fluent Bit に移行する必要があります。Fluentd パーサーは JSON 形式のログメッセージのみを解析するように構成されています。dockerd とは異なり、containerd コンテナランタイムには JSON 形式ではないログメッセージがあります。Fluent Bit に移行しないと、構成された Fluentd’s パーサーの一部が 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」を参照してください。

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

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

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

クラスターの更新 - eksctl

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

eksctl version

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

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

eksctl upgrade cluster --name my-cluster --version 1.30 --approve

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

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

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

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

  2. 更新する Amazon EKS クラスター名を選択し、[クラスターバージョンの更新] を選択します。

  3. [Kubernetes バージョン] で、バージョンを選択してクラスターを更新し、[更新] を選択します。

  4. [クラスター名] にクラスター名を入力し、[確認] を選択します。

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

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

クラスターの更新 - AWS CLI

  1. 次の AWS CLI コマンドを使用して、Amazon EKS クラスターを更新します。example values は実際に使用する値に置き換えます。1.30 を、Amazon EKS がサポートするクラスターの更新後のバージョン番号に置き換えてください。サポートされているバージョン番号のリストについては、「EKS の Kubernetes バージョンライフサイクルを理解する」を参照してください。

    aws eks update-cluster-version --region region-code --name my-cluster --kubernetes-version 1.30

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

    {
    "update": {
        "id": "b5f0ba18-9a87-4450-b5a0-825e6e84496f",
        "status": "InProgress",
        "type": "VersionUpdate",
        "params": [
            {
                "type": "Version",
                "value": "1.30"
            },
            {
                "type": "PlatformVersion",
                "value": "eks.1"
            }
        ],
[...]
        "errors": []
    }

  2. クラスター更新のステータスをモニタリングするには、次のコマンドを使用します。前のコマンドから返されたクラスター名と更新 ID を使用します。Successful ステータスが表示されると、更新は完了です。この更新は完了までに数分かかることがあります。

    aws eks describe-update --region region-code --name my-cluster --update-id b5f0ba18-9a87-4450-b5a0-825e6e84496f

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

    {
    "update": {
        "id": "b5f0ba18-9a87-4450-b5a0-825e6e84496f",
        "status": "Successful",
        "type": "VersionUpdate",
        "params": [
            {
                "type": "Version",
                "value": "1.30"
            },
            {
                "type": "PlatformVersion",
                "value": "eks.1"
            }
        ],
[...]
        "errors": []
    }

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

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

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

  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 イメージタグを、前のステップで書き留めたバージョンに設定します。必要に応じて、1.30.n` を独自の値に置き換えます。

      kubectl -n kube-system set image deployment.apps/cluster-autoscaler cluster-autoscaler=registry.k8s.io/autoscaling/cluster-autoscaler:v1.30.n

  3. (GPU ノードを含むクラスターのみ) クラスターに GPU 対応のノードグループ (p3.2xlarge など) がある場合は、クラスターの Kubernetes 用 NVIDIA デバイスプラグイン 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 バージョンを使用する必要があります。例えば、1.29 kubectl クライアントは Kubernetes、1.28、1.29 および 1.30 クラスターで動作します。現在インストールされているバージョンは、次のコマンドで確認できます。

    kubectl version --client

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

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