Amazon EKS での、Amazon VPC CNI アドオンに関する問題をトラブルシューティングする方法を教えてください。

解決策

注: AWS コマンドラインインターフェイス (AWS CLI) コマンドの実行中にエラーが発生した場合は、「AWS CLI で発生したエラーのトラブルシューティング」を参照してください。また、AWS CLI の最新バージョンを使用していることを確認してください。

Amazon VPC CNI アドオンが初期化されなかったことが原因で、ワーカーノードの準備が整っていない場合、次の例のようなエラーメッセージが表示されます。

「container runtime network not ready: NetworkReady=false reason:NetworkPluginNotReady message:Network plugin returns error: cni plugin not initialized」

この問題が起こっていないかを確認するには、次のコマンドを実行します。

kubectl describe node node_name

注: node_name を実際のノード名に置き換えます。出力に cni plugin no initialized というエラーメッセージが表示される場合があります。

この問題をトラブルシューティングするには、次の手順を実行します。

Amazon VPC CNI アドオンがインストールされていることを確認する

クラスター内で aws-node ポッドが欠けている場合、コンテナログに次の例のようなエラーメッセージが表示されます。

「cni config load failed: no network config found in /etc/cni/net.d: cni plugin not initialized: failed to load cni config」

この問題を解決するには、Amazon VCP CNI アドオンをインストールします。

IAM アクセス許可に問題がないか確認する

Amazon VPC CNI アドオンを使用する場合は、AWS Identity and Access Management (IAM) マネージドポリシー AmazonEKS_CNI_Policy を使用します。または、カスタムポリシーを使用する場合は、そのポリシーに次のアクセス許可が含まれていることを確認してください。

 "ec2:AssignPrivateIpAddresses",
 "ec2:AttachNetworkInterface",
 "ec2:CreateNetworkInterface",
 "ec2:DeleteNetworkInterface",
 "ec2:DescribeInstances",
 "ec2:DescribeTags",
 "ec2:DescribeNetworkInterfaces",
 "ec2:DescribeInstanceTypes",
 "ec2:DescribeSubnets",
 "ec2:DetachNetworkInterface",
 "ec2:ModifyNetworkInterfaceAttribute",
 "ec2:UnassignPrivateIpAddresses"
 "ec2:CreateTags"

不足している IAM アクセス許可を特定するには、ホストディレクトリ /var/log/aws-routed-eni/ipamd.log 内の L-IPAM daemon (IPAMD) ログを確認します。Amazon VPC CNI アドオンに必要な IAM アクセス許可がない場合は、次の例のようなエラーメッセージが表示されます。

{"level":"error","ts":"2023-11-18T01:08:34.083Z","caller":"aws-k8s-agent/main.go:28","msg":"Initialization failure: ipamd init: failed to retrieve attached ENIs info: UnauthorizedOperation: You are not authorized to perform this operation.User: arn:aws:sts::XXXXXXXXXXXXXXXXXXXX:assumed-role/rolename is not authorized to perform: ec2:DescribeNetworkInterfaces because no identity-based policy allows the ec2:DescribeNetworkInterfaces action\n\tstatus code: 403, request id: request id"}

上記のエラーメッセージの例は、アドオンには ec2:DescribeNetworkInterfaces というアクセス許可が必要であることを示しています。

ワーカーノードに直接アクセスできない場合は、ワーカーノードの aws-node ポッドを確認してください。ワーカーノード上の aws-node ポッドを特定するには、次のコマンドを実行します。

kubectl describe node node_name

注: node_name を実際のノード名に置き換えます。出力の Non-terminated Pods セクションで aws-node ポッド名を確認します。

次に、以下のコマンドを実行して aws-node ポッドの詳細を表示します。

kubectl describe pod pod-name -n kube-system

注: pod-name を aws-node ポッドの名前に置き換えます。

出力で、Event を参照し、不足しているアクセス許可に関する情報を確認します。

出力例

Type Reason Age From Message
---- ------ ---- ---- -------
Warning MissingIAMPermissions 105s (x2 over 105s) aws-node Unauthorized operation: failed to call ec2:DescribeNetworkInterfaces due to missing permissions. Please refer https://github.com/aws/amazon-vpc-cni-k8s/blob/master/docs/iam-policy.md to attach relevant policy to IAM role in the event section you can able to see the error message also you can check the AWS cloud trail event for the particular instance by filtering the cloudtrail with username and provide the instanceID there.

AWS CloudTrail を使用して特定のイベントが発生していないかを確認することもできます。たとえば、DescribeNetworkInterfaces API コールのユーザー名とインスタンス ID を参照し、実行されたかどうかを判断します。

ネットワークの問題を確認する

Amazon VPC CNI アドオンは、実行時に API サーバーエンドポイントと Amazon Elastic Compute Cloud (Amazon EC2) エンドポイントに到達する必要があります。どちらかの接続に失敗すると、アドオンは初期化できず、ノードは NotReady ステータスに移行します。

特定のエラーメッセージを確認するには、/var/log/aws-routed-eni/ipamd.log ホストディレクトリの IPAMD ログを確認します。kube-proxy と coreDNS ポッドがエラーを発生させずに実行できることを確認してください。

アドオンコンポーネントのバージョンを確認する

コアコンポーネントを最新バージョンに更新することをおすすめします。アドオンのバージョンが Kubernetes クラスターのバージョンと一致しない場合、そのアドオンは初期化できません。アドオンバージョンが Kubernetes クラスタバージョンと互換性があることを確認してください。

Amazon VPC CNI アドオンでのエラーのトラブルシューティング

アドオンのエラーを特定するには、SSH を使用し、アドオンが IP アドレスの割り当てに失敗したワーカーノードに接続します。次に、/var/log/aws-routed-eni/ipamd.log ファイルの IPAMD ログにエラーメッセージがないかどうかを確認します。

Failed to assign ip エラー

Failed to assign ip エラーは、Amazon VPC CNI アドオンがワーカーノードにスケジュールされているポッドに IP アドレスを割り当てられない場合に発生します。CloudTrail イベント履歴ページで AssignPrivateIpAddresses イベントが発生していないかを確認しても、このエラーを特定できます。

割り当てられたサブネットに使用可能な IP アドレスがないかどうかを確認するには、次の AWS CLI コマンド describe-subnets を実行します。

aws ec2 describe-subnets --filters "Name=vpc-id,Values= VPCID" | jq '.Subnets[] | .SubnetId + "=" + "\(.AvailableIpAddressCount)"'

注: VPCID を実際の VPC ID に置き換えます。

環境変数 WARM_ENI_TARGET、WARM_IP_TARGET、または MINIMUM_IP_TARGET に設定した値が低すぎる場合も、Failed to assign ip エラーが発生する場合があります。サブネットの CIDR 範囲が十分に広く、ユースケースに十分な IP アドレスが割り当てられていることを確認してください。詳細については、GitHub のウェブサイトで WARM_ENI_TARGET、WARM_IP_TARGET、および MINIMUM_IP_TARGET を参照してください。

環境変数の値を確認する場合は、次のコマンドを実行するとポッドの詳細が表示されます。

kubectl describe pod pod-name -n kube-system

注: pod-name を aws-node ポッドの名前に置き換えます。

aws-node DaemonSet 内の環境変数を更新します。

env:
  - name: WARM_ENI_TARGET
    value: "1"
  - name: WARM_IP_TARGET
    value: "5"
  - name: MINIMUM_IP_TARGET
    value: "25"

または、次のコマンドを実行して環境変数を更新します。

kubectl set env ds aws-node -n kube-system WARM_ENI_TARGET=1 WARM_IP_TARGET=5 MINIMUM_IP_TARGET=25

プレフィックス委任モードを使用しており、専用のポッドサブネット範囲を使用していない場合、サブネットの断片化によりアドオンでエラーが発生する可能性があります。アドオンは、ネットワークインターフェイスに /28 (IPv4) および /80 (IPv6) の連続したプレフィックス範囲を割り当てる必要があります。プレフィックス委任の詳細については、GitHub のウェブサイトで ENABLE_PREFIX_DELEGATION を参照してください。

サブネットの断片化を直接確認することはできません。代わりに、サブネットの CIDR 範囲にまだ使用可能な IP アドレスが 17 個以上あるかどうかを確認してください。十分な IP アドレスがあるにもかかわらず、Failed to assign ip エラーが頻繁に返される場合は通常、サブネットの断片化が要因です。この問題をトラブルシューティングするには、プレフィックス委任付きのカスタムネットワークを使用してポッド専用のサブネットを確立することをおすすめします。詳細については、GitHub のウェブサイトで AWS_VPC_K8S_CNI_CUSTOM_NETWORK_CFG を参照してください。

Failed to get pod ENI config エラー

AWS_VPC_K8S_CNI_CUSTOM_NETWORK_CFG を使用してカスタムネットワークを有効化したものの、ENIConfig リソースを作成しなかった場合、次の例に類似したエラーメッセージが表示されます。

「{"level":"error","ts":"","caller":"ipamd/ipamd.go:798","msg":"Failed to get pod ENI config"}」

ENIConfig リソースがクラスターに存在するかどうかを確認するには、次のコマンドを実行します。

kubectl get eniconfig -o yaml

ENIConfig カスタムリソースが存在しない場合は、作成します。カスタムネットワークの詳細については、GitHub のウェブサイトで AWS_VPC_K8S_CNI_CUSTOM_NETWORK_CFG を参照してください。

Failed to watch エラー

YAML ファイルの記述形式に誤りがある場合、次の例に類似したエラーメッセージが表示されることがあります。

「Failed to watch *v1alpha1.ENIConfig: failed to list *v1alpha1.ENIConfig:json: cannot unmarshal string into Go struct field ENIConfigSpec.items.spec.securityGroups of type []string」

この問題は通常、JSON データと Go データ型の定義が一致しない場合に発生します。上記のエラーメッセージの例は、securityGroups フィールドに問題があることを示しています。

この問題をトラブルシューティングするには、次のコマンドを実行して JSON データを確認します。

kubectl describe ENIConfig

コマンドの出力で、エラーメッセージで特定された問題に応じて構文を確認します。たとえば、JSON の **securityGroups ** フィールドが単一の文字列ではなく、文字列の配列であることを確認してください。

出力例

cat >$az_1.yaml <<EOF
apiVersion: crd.k8s.amazonaws.com/v1alpha1
kind: ENIConfig
metadata:
  name: us-west-2a
spec:
  securityGroups:
    - sg-0123456789abcdef0
  subnet: subnet-0123456789abcdef0
EOF