Amazon VPC CNI plugin for Kubernetes Amazon EKS アドオンの使用 - Amazon EKS
Amazon EKS アドオンの作成Amazon EKS アドオンの更新セルフマネージド型アドオンを更新する

Amazon VPC CNI plugin for Kubernetes Amazon EKS アドオンの使用

Amazon VPC CNI plugin for Kubernetes アドオンは Amazon EKS クラスター内の各 Amazon EC2 ノードにデプロイされます。アドオンは Elastic Network Interface を作成し、Amazon EC2 ノードにアタッチします。またアドオンは、VPC のプライベートIPv4 または IPv6 アドレスを各 Pod およびサービスに割り当てます。

アドオンのバージョンはクラスター内の各 Fargate ノードにデプロイされますが、Fargate ノードでは更新しません。Amazon EKS クラスターでは他の互換性のある CNI プラグインも使用できますが、これは Amazon EKS でサポートされている唯一の CNI プラグインです。

次の表は、各 Kubernetes バージョンの Amazon EKS アドオンタイプの利用可能な最新バージョンを示しています。

Kubernetes バージョン 1.29 1.28 1.27 1.26 1.25 1.24 1.23
Amazon EKS タイプの VPC CNI バージョン v1.17.1-eksbuild.1 v1.17.1-eksbuild.1 v1.17.1-eksbuild.1 v1.17.1-eksbuild.1 v1.17.1-eksbuild.1 v1.17.1-eksbuild.1 v1.17.1-eksbuild.1
重要

このアドオンを自己管理している場合、表のバージョンは、利用可能なセルフマネージドバージョンと同じではない可能性があります。このアドオンのセルフマネージドタイプの更新の詳細については、「セルフマネージド型アドオンを更新する」を参照してください。

前提条件

  • 既存の Amazon EKS クラスター。デプロイするには、「Amazon EKS の使用開始」を参照してください。

  • クラスター用の既存 AWS Identity and Access Management IAM OpenID Connect (OIDC) プロバイダー。既に存在しているかどうかを確認する、または作成するには「クラスター用の IAM OIDC プロバイダーの作成」を参照してください。

  • AmazonEKS_CNI_Policy IAM ポリシー (クラスターが IPv4 ファミリーを使用している場合)、または IPv6 ポリシー (クラスターが IPv6 ファミリーを使用している場合) がアタッチされた IAM ロール。詳細については、「サービスアカウントの IAM ロールを使用する Amazon VPC CNI plugin for Kubernetes の設定」を参照してください。

  • ‭Amazon VPC CNI plugin for Kubernetes のバージョン ‭1.7.0‬ 以降の CNI プラグインを使用しており、カスタム‬ Pod セキュリティポリシーを使用する場合は、「‭デフォルトの Amazon EKS Pod セキュリティポリシーを削除するポッドのセキュリティポリシー」を参照してください。

  • 重要

    Amazon VPC CNI plugin for Kubernetes バージョン v1.16.0 から v1.16.1 では、Kubernetes バージョン 1.23 以前との互換性を削除されています。VPC CNI バージョン v1.16.2 では、 Kubernetes バージョン 1.23 以前、および CNI 仕様 v0.4.0 との互換性が復元されています。

    Amazon VPC CNI plugin for Kubernetes バージョン v1.16.0 から v1.16.1 では CNI 仕様バージョン v1.0.0 が実装されています。CNI 仕様 v1.0.0 は、Kubernetes バージョン v1.24 以降を実行する EKS クラスターでサポートされています。VPC CNI バージョン v1.16.0 から v1.16.1 および CNI 仕様 v1.0.0 は、Kubernetes バージョン v1.23 以前ではサポートされていません。CNI 仕様の v1.0.0 の詳細については、「Container Network Interface (CNI) 仕様」を参照してください

考慮事項

  • バージョンは major-version.minor-version.patch-version-eksbuild.build-number として指定されます。

  • 各機能のバージョン互換性を確認

    Amazon VPC CNI plugin for Kubernetes の各リリースの一部の機能には、特定の Kubernetes バージョンが必要です。異なる Amazon EKS の機能を使用する際、アドオンの特定のバージョンが必要な場合については、機能に関するドキュメントに記載されています。以前のバージョンを実行する特定の理由がある場合を除いて、最新のバージョンを実行することをお勧めします。

Amazon EKS アドオンの作成

Amazon EKS タイプのアドオンを作成します。

  1. クラスターにインストールされているアドオンのバージョンを確認します。

    kubectl describe daemonset aws-node --namespace kube-system | grep amazon-k8s-cni: | cut -d : -f 3

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

    v1.12.6-eksbuild.2

  2. クラスターにインストールされているアドオンのタイプを確認します。クラスターを作成するために使用したツールによっては、現在クラスターに Amazon EKS アドオンタイプがインストールされていない場合があります。my-cluster の部分は、自分のクラスター名に置き換えます。

    $ aws eks describe-addon --cluster-name my-cluster --addon-name vpc-cni --query addon.addonVersion --output text

    バージョン番号が返された場合、Amazon EKS タイプのアドオンがクラスターにインストールされているため、このステップの残りのステップを完了する必要はありません。エラーが返された場合、クラスターに Amazon EKS タイプのアドオンがインストールされていません。インストールするには、この手順の残りのステップを完了します。

  3. 現在インストールされているアドオンの設定を保存します。

    kubectl get daemonset aws-node -n kube-system -o yaml > aws-k8s-cni-old.yaml

  4. AWS CLI を使用してアドオンを作成します。AWS Management Console または eksctl を使用してアドオンを作成する場合は、「アドオンの作成」を参照して、アドオン名の vpc-cni を指定します。デバイスに沿ったコマンドをコピーします。必要に応じてコマンドに次の変更を加え、変更したコマンドを実行します。

    • my-cluster を自分のクラスター名に置き換えます。

    • v1.17.1-eksbuild.1 を、クラスターバージョンの最新バージョンの表に記載されている最新バージョンに置き換えます。

    • 111122223333 を、アカウント ID に置き換えます。また、AmazonEKSVPCCNIRole を、作成した既存の IAM ロールの名前に置き換えます。ロールを指定するには、クラスター用に IAM OpenID Connect (OIDC) プロバイダーが必要です。クラスター用に持っているかどうかを確認、あるいは作成するには、「クラスター用の IAM OIDC プロバイダーの作成」を参照してください。

    aws eks create-addon --cluster-name my-cluster --addon-name vpc-cni --addon-version v1.17.1-eksbuild.1 \
    --service-account-role-arn arn:aws:iam::111122223333:role/AmazonEKSVPCCNIRole

    Amazon EKS アドオンのデフォルト設定と競合するカスタム設定を現在のアドオンに適用した場合、作成が失敗する可能性があります。作成が失敗した場合、エラーが表示されます。これは、問題の解決に役立てることができます。または、前のコマンドに --resolve-conflicts OVERWRITE を追加することもできます。これにより、アドオンは既存のカスタム設定を上書きできます。アドオンを作成したら、カスタム設定で更新できます。

  5. クラスターの Kubernetes バージョン用のアドオンの最新バージョンがクラスターに追加されたことを確認します。my-cluster を自分のクラスター名に置き換えます。

    aws eks describe-addon --cluster-name my-cluster --addon-name vpc-cni --query addon.addonVersion --output text

    アドオンの作成が完了するまでに数秒かかる場合があります。

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

    v1.17.1-eksbuild.1

  6. 元のアドオンに対してカスタム設定を行った場合は、Amazon EKS アドオンを作成する前に、前のステップで保存した設定を使用して、カスタム設定で Amazon EKS アドオンを更新します。

  7. (オプション)cni-metrics-helper をクラスタにインストールします。 メトリクスヘルパーは、ネットワークインターフェイスと IP アドレス情報を収集し、クラスターレベルでメトリクスを集計し、メトリクスを Amazon CloudWatch に発行するために使用できるツールです。詳細については、GitHub の CNI を参照してください。

Amazon EKS アドオンの更新

Amazon EKS タイプのアドオンを更新します。Amazon EKS タイプのアドオンをクラスターに追加していない場合は、この手順を完了する代わりに、アドオンを追加するか、「セルフマネージド型アドオンを更新する」を参照してください。

  1. クラスターにインストールされているアドオンのバージョンを確認します。my-cluster をクラスター名に置き換えます。

    aws eks describe-addon --cluster-name my-cluster --addon-name vpc-cni --query "addon.addonVersion" --output text

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

    v1.12.6-eksbuild.2

    返されたバージョンが、最新バージョンの表にあるクラスターの Kubernetes バージョンのバージョンと同じである場合は、既に最新バージョンがクラスターにインストールされているため、この手順の残りを完了する必要はありません。出力にバージョン番号ではなくエラーが表示される場合は、Amazon EKS タイプのアドオンがクラスターにインストールされていません。この手順でアドオンを更新する前に、アドオンを作成する必要があります。

  2. 現在インストールされているアドオンの設定を保存します。

    kubectl get daemonset aws-node -n kube-system -o yaml > aws-k8s-cni-old.yaml

  3. AWS CLI を使用してアドオンを更新します。AWS Management Console または eksctl を使用してアドオンを更新する場合は、「アドオンの更新」を参照してください。デバイスに沿ったコマンドをコピーします。必要に応じてコマンドに次の変更を加え、変更したコマンドを実行します。

    • my-cluster を自分のクラスター名に置き換えます。

    • v1.17.1-eksbuild.1 を、クラスターバージョンの最新バージョンの表に記載されている最新バージョンに置き換えます。

    • 111122223333 を、アカウント ID に置き換えます。また、AmazonEKSVPCCNIRole を、作成した既存の IAM ロールの名前に置き換えます。ロールを指定するには、クラスター用に IAM OpenID Connect (OIDC) プロバイダーが必要です。クラスター用に持っているかどうかを確認、あるいは作成するには、「クラスター用の IAM OIDC プロバイダーの作成」を参照してください。

    • --resolve-conflicts PRESERVE オプションはアドオンの既存の設定値を保存します。アドオン設定にカスタム値を設定していて、このオプションを使用しない場合、Amazon EKS は値をデフォルト値で上書きします。このオプションを使用する場合、実稼働クラスターのアドオンを更新する前に、非稼動クラスターのフィールドおよび値変更をテストすることをお勧めします。この値を OVERWRITE に変更する場合、すべての設定が Amazon EKS のデフォルト値に変更されます。いずれかの設定にカスタム値を設定した場合、Amazon EKS のデフォルト値で上書きされる可能性があります。この値を none に変更した場合、Amazon EKS は設定の値を一切変更しませんが、更新が失敗する可能性があります。更新に失敗した場合、競合の解決に役立つエラーメッセージが返されます。

    • 構成設定を更新しない場合は、コマンドから --configuration-values '{"env":{"AWS_VPC_K8S_CNI_EXTERNALSNAT":"true"}}' を削除します。構成設定を更新する場合は、"env":{"AWS_VPC_K8S_CNI_EXTERNALSNAT":"true"} を、希望する設定に置き換えます。この例では、AWS_VPC_K8S_CNI_EXTERNALSNAT 環境変数は true に設定されています。指定する値は、設定スキーマに対して有効である必要があります。設定スキーマがわからない場合は、aws eks describe-addon-configuration --addon-name vpc-cni --addon-version v1.17.1-eksbuild.1 を実行します。その際に、v1.17.1-eksbuild.1 は、設定を表示する対象のアドオンのバージョン番号に置き換えてください。出力でスキーマが返されます。既存のカスタム設定があり、それをすべて削除してすべての設定の値を Amazon EKS のデフォルトに戻したい場合は、コマンドから "env":{"AWS_VPC_K8S_CNI_EXTERNALSNAT":"true"} を削除して、{} が空になるようにします。各設定の説明については、GitHub の「CNI 設定変数」を参照してください。

      aws eks update-addon --cluster-name my-cluster --addon-name vpc-cni --addon-version v1.17.1-eksbuild.1 \
    --service-account-role-arn arn:aws:iam::111122223333:role/AmazonEKSVPCCNIRole \
    --resolve-conflicts PRESERVE --configuration-values '{"env":{"AWS_VPC_K8S_CNI_EXTERNALSNAT":"true"}}'

      更新が完了するまでに数秒かかる場合があります。

  4. アドオンのバージョンが更新されたことを確認します。my-cluster を自分のクラスター名に置き換えます。

    aws eks describe-addon --cluster-name my-cluster --addon-name vpc-cni

    更新が完了するまでに数秒かかる場合があります。

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

    {
    "addon": {
        "addonName": "vpc-cni",
        "clusterName": "my-cluster",
        "status": "ACTIVE",
        "addonVersion": "v1.17.1-eksbuild.1",
        "health": {
            "issues": []
        },
        "addonArn": "arn:aws:eks:region:111122223333:addon/my-cluster/vpc-cni/74c33d2f-b4dc-8718-56e7-9fdfa65d14a9",
        "createdAt": "2023-04-12T18:25:19.319000+00:00",
        "modifiedAt": "2023-04-12T18:40:28.683000+00:00",
        "serviceAccountRoleArn": "arn:aws:iam::111122223333:role/AmazonEKSVPCCNIRole",
        "tags": {},
        "configurationValues": "{\"env\":{\"AWS_VPC_K8S_CNI_EXTERNALSNAT\":\"true\"}}"
    }
}

セルフマネージド型アドオンを更新する

重要

セルフマネージド型のアドオンを使用する代わりに、Amazon EKS タイプのアドオンをクラスターに追加することをお勧めします。タイプの違いがよくわからない場合は、「Amazon EKS アドオン」を参照してください。Amazon EKS アドオンをクラスターに追加する方法については、「アドオンの作成」を参照してください。Amazon EKS アドオンを使用できない場合は、その理由に関する問題をコンテナロードマップ GitHub リポジトリに送信することをお勧めします。

  1. Amazon EKS タイプのアドオンがクラスターにインストールされていないことを確認します。my-cluster の部分は、自分のクラスター名に置き換えます。

    aws eks describe-addon --cluster-name my-cluster --addon-name vpc-cni --query addon.addonVersion --output text

    エラーメッセージが返された場合、クラスターに Amazon EKS タイプのアドオンがインストールされていません。アドオンを自己管理するには、この手順の残りのステップを完了してアドオンを更新します。バージョン番号が返された場合、クラスターに Amazon EKS タイプのアドオンがインストールされています。更新するには、この手順を使用するのではなく、「アドオンの更新」の手順を使用してください。アドオンタイプの違いがよくわからない場合は、「Amazon EKS アドオン」を参照してください。

  2. クラスターに現在インストールされているコンテナイメージのバージョンを確認します。

    kubectl describe daemonset aws-node --namespace kube-system | grep amazon-k8s-cni: | cut -d : -f 3

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

    v1.12.6-eksbuild.2

    出力にビルド番号が含まれていない場合があります。

  3. 現在の設定をバックアップして、バージョンを更新した後も同じ設定を構成できるようにします。

    kubectl get daemonset aws-node -n kube-system -o yaml > aws-k8s-cni-old.yaml

  4. 利用可能なバージョンを確認し、更新するバージョンの変更について理解するには、GitHub の releases を参照してください。新しいバージョンが GitHub で利用できる場合でも、利用可能な最新バージョンの表に記載されている同じ major.minor.patch バージョンに更新することをお勧めします。表に記載されているビルドバージョンは、GitHub に記載されているセルフマネージドバージョンでは指定されていません。次のオプションのいずれかでタスクを完了して、バージョンを更新します。

    • アドオンのカスタム設定がない場合は、更新先のリリースの GitHub の To apply this release: の見出しの下にあるコマンドを実行します。

    • カスタム設定がある場合は、次のコマンドを実行してマニフェストファイルをダウンロードします。https://raw.githubusercontent.com/aws/amazon-vpc-cni-k8s/v1.17.1/config/master/aws-k8s-cni.yaml を、更新先の GitHub 上のリリースの URL に変更します。

      curl -O https://raw.githubusercontent.com/aws/amazon-vpc-cni-k8s/v1.17.1/config/master/aws-k8s-cni.yaml

      必要に応じて、前のステップで作成したバックアップのカスタム設定でマニフェストを変更し、変更したマニフェストをクラスターに適用します。ノードがイメージの取得元のプライベート Amazon EKS Amazon ECR リポジトリにアクセスできない場合 (マニフェストの image: で始まる行を参照)、イメージをダウンロードして自分のリポジトリにコピーし、リポジトリからイメージを取得するようにマニフェストを変更する必要があります。詳細については、「あるリポジトリから別のリポジトリにコンテナイメージをコピーする」を参照してください。

      kubectl apply -f aws-k8s-cni.yaml

  5. 新しいバージョンがクラスターにインストールされたことを確認します。

    kubectl describe daemonset aws-node --namespace kube-system | grep amazon-k8s-cni: | cut -d : -f 3

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

    v1.17.1

  6. (オプション)cni-metrics-helper をクラスタにインストールします。 メトリクスヘルパーは、ネットワークインターフェイスと IP アドレス情報を収集し、クラスターレベルでメトリクスを集計し、メトリクスを Amazon CloudWatch に発行するために使用できるツールです。詳細については、GitHub の CNI を参照してください。