How to fix EKS CNI plugin error in Kubernetes

KubernetesINTERMEDIATEHIGH

The EKS CNI (Container Network Interface) plugin fails to initialize on worker nodes, preventing pods from getting IP addresses and cluster nodes from becoming ready. This typically results from incompatible add-on versions, missing IAM permissions, network connectivity issues, or incorrect network configuration.

What this error means

AWS EKS uses the Amazon VPC CNI plugin to assign IP addresses from your VPC to Kubernetes pods. This plugin runs as a DaemonSet (aws-node) on every worker node. When the CNI plugin fails to initialize, the kubelet cannot configure networking for containers, leaving nodes in NotReady status and preventing any pods from running. The error manifests when the plugin cannot load its configuration, reach the AWS API to allocate IP addresses, or when the add-on version does not match your Kubernetes cluster version. This is a fundamental networking issue that blocks cluster operations.

How to fix "EKS CNI plugin error"

1Check EKS add-on version compatibility

First, verify that your VPC CNI add-on version matches your Kubernetes cluster version. Go to the AWS Management Console and check the installed add-ons:

bash

# Check installed EKS add-ons via CLI
aws eks describe-addon --cluster-name <cluster-name> --addon-name vpc-cni

Ensure the add-on version is compatible. If updating the add-on, use the conflict resolution method "Override" to force the update:

2Verify IAM permissions on worker node role

The worker node IAM role must include the AmazonEKS_CNI_Policy. Attach this managed policy if missing:

bash

# Get the node IAM role
NODE_IAM_ROLE=$(aws ec2 describe-instances --instance-ids <instance-id> --query 'Reservations[0].Instances[0].IamInstanceProfile.Arn' --output text | cut -d'/' -f2)

# Attach the CNI policy
aws iam attach-role-policy --role-name $NODE_IAM_ROLE --policy-arn arn:aws:iam::aws:policy/AmazonEKS_CNI_Policy

If you created the cluster with Terraform or CloudFormation, ensure the node IAM role includes this policy in the configuration.

3Check network connectivity to AWS APIs

Worker nodes must reach both the EKS API server endpoint and the EC2 API endpoint. SSH into a node and verify connectivity:

bash

# SSH into the worker node (requires EC2 permissions)
ssh -i <key-pair> ec2-user@<node-ip>

# Test connectivity to EKS API server
curl -I https://<cluster-api-endpoint>:443

# Test connectivity to EC2 API
curl -I https://ec2.amazonaws.com/

# Check security groups allow outbound 443
aws ec2 describe-security-groups --group-ids <sg-id>

Ensure your network ACLs and security groups allow outbound HTTPS (port 443) traffic.

4Verify CNI configuration files and aws-node pod status

Check if the CNI plugin configuration is properly loaded on the worker node:

bash

# SSH into the worker node
ssh -i <key-pair> ec2-user@<node-ip>

# Check if CNI config directory exists and has files
ls -la /etc/cni/net.d/

# Check aws-node pod logs for errors
kubectl logs -n kube-system -l k8s-app=aws-node --tail=100

# Check plugin logs for IP assignment errors
sudo cat /var/log/aws-routed-eni/ipamd.log | tail -50
sudo cat /var/log/aws-routed-eni/plugin.log | tail -50

If logs show "Failed to reach IMDS" or "Failed to reach API", it indicates network access issues.

5Ensure sufficient IP addresses in your subnet

EKS CNI allocates secondary IP addresses from your subnet. Verify you have enough available IPs:

bash

# Check available IPs in subnet
aws ec2 describe-subnets --subnet-ids <subnet-id> --query 'Subnets[0].AvailableIpAddressCount'

# Calculate required IPs: (number of ENIs per node) * (secondary IPs per ENI - 1)
# Each node typically needs 10-100+ available IPs depending on pod density

If IP space is exhausted, either:
- Add additional subnets to your EKS cluster
- Use prefix delegation to allocate entire /28 blocks instead of individual IPs
- Increase your VPC CIDR block and add new subnets

6Update kubelet configuration if using custom launch template

If your worker nodes use a custom EC2 launch template, verify it does not override kubelet networking configuration:

bash

# Check the user data script in your launch template
aws ec2 describe-launch-template-versions --launch-template-id <template-id> --versions All

The user data must not:
- Set --cni-bin-dir or --cni-conf-dir flags
- Start kubelet before the CNI plugin is ready
- Remove or modify /etc/cni/net.d/ files

If the launch template is causing issues, consider removing it and letting AWS use the default configuration. Then replace affected nodes:

7Drain and replace affected nodes

Once you've addressed the root cause, drain and terminate the problematic nodes so new ones can join with the corrected configuration:

bash

# Drain the node to evict all pods
kubectl drain <node-name> --ignore-daemonsets --delete-emptydir-data

# Terminate the node (if using Auto Scaling Group)
aws autoscaling terminate-instance-in-auto-scaling-group --instance-id <instance-id> --should-decrement-desired-capacity

# The ASG will automatically launch a replacement node
# Wait for it to join and become Ready
kubectl get nodes -w

Verify the new node successfully initialized CNI:

How to fix EKS CNI plugin error in Kubernetes

What this error means

Typical symptoms

Common causes

How to fix "EKS CNI plugin error"

Advanced notes

Related errors

Official resources & further reading