AWS EKS Worker Nodes Not Joining the Cluster: Complete Fix Guide

# Check if nodes appear at all
kubectl get nodes
 
# If nodes show but are NotReady
kubectl describe node <node-name>
# Look for: Conditions → Ready: False, and Events section
 
# Check node group status in AWS console
aws eks describe-nodegroup \
  --cluster-name my-cluster \
  --nodegroup-name my-nodegroup \
  --query 'nodegroup.status'
 
# Check EC2 instances
aws ec2 describe-instances \
  --filters "Name=tag:eks:cluster-name,Values=my-cluster" \
  --query 'Reservations[].Instances[].{ID:InstanceId,State:State.Name,Status:NetworkInterfaces[0].Status}'

# Check node role
aws iam list-attached-role-policies \
  --role-name my-eks-node-role \
  --query 'AttachedPolicies[].PolicyName'

# Required policies for EKS worker nodes
aws iam attach-role-policy \
  --role-name my-eks-node-role \
  --policy-arn arn:aws:iam::aws:policy/AmazonEKSWorkerNodePolicy
 
aws iam attach-role-policy \
  --role-name my-eks-node-role \
  --policy-arn arn:aws:iam::aws:policy/AmazonEKS_CNI_Policy
 
aws iam attach-role-policy \
  --role-name my-eks-node-role \
  --policy-arn arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly

# Check aws-auth ConfigMap
kubectl get configmap aws-auth -n kube-system -o yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: aws-auth
  namespace: kube-system
data:
  mapRoles: |
    - rolearn: arn:aws:iam::123456789012:role/my-eks-node-role
      username: system:node:{{EC2PrivateDNSName}}
      groups:
        - system:bootstrappers
        - system:nodes

kubectl apply -f aws-auth.yaml

# Connect via SSM (no SSH key needed)
aws ssm start-session --target <instance-id>
 
# Test API server connectivity
curl -k https://<api-server-endpoint>:443
# Should return: 403 Forbidden (not a timeout)

resource "aws_security_group_rule" "node_to_control_plane" {
  type                     = "egress"
  from_port                = 443
  to_port                  = 443
  protocol                 = "tcp"
  source_security_group_id = aws_security_group.eks_control_plane.id
  security_group_id        = aws_security_group.eks_nodes.id
}

# Check endpoint access config
aws eks describe-cluster --name my-cluster \
  --query 'cluster.resourcesVpcConfig.{public:endpointPublicAccess,private:endpointPrivateAccess}'
# {"public": true, "private": false}

aws eks update-cluster-config \
  --name my-cluster \
  --resources-vpc-config endpointPrivateAccess=true,endpointPublicAccess=true

resource "aws_nat_gateway" "nat" {
  allocation_id = aws_eip.nat.id
  subnet_id     = aws_subnet.public.id
}
 
resource "aws_route" "private_nat_route" {
  route_table_id         = aws_route_table.private.id
  destination_cidr_block = "0.0.0.0/0"
  nat_gateway_id         = aws_nat_gateway.nat.id
}

# On the node (via SSM)
sudo journalctl -u kubelet --since "10 minutes ago"
sudo cat /var/log/cloud-init-output.log
sudo cat /var/log/user-data.log    # if using custom launch template

# Get the correct AMI for your EKS version and region
aws ssm get-parameter \
  --name /aws/service/eks/optimized-ami/1.30/amazon-linux-2/recommended/image_id \
  --region ap-south-1 \
  --query Parameter.Value \
  --output text
# ami-0abc123def456

nodeGroups:
  - name: workers
    instanceType: t3.medium
    amiFamily: AmazonLinux2    # Let eksctl pick the right AMI automatically

kubectl describe node <node-name> | grep "max-pods"
kubectl describe node <node-name> | grep -A5 "Allocatable"

kubectl set env daemonset aws-node \
  -n kube-system \
  ENABLE_PREFIX_DELEGATION=true

# On the node
sudo timedatectl status
sudo chronyc sources
sudo chronyc tracking
 
# Force sync
sudo chronyc makestep

# 1. Does the node appear?
kubectl get nodes
 
# 2. Check node group status
aws eks describe-nodegroup --cluster-name <name> --nodegroup-name <name>
 
# 3. Check EC2 instance state
aws ec2 describe-instance-status --instance-ids <id>
 
# 4. SSH/SSM into node and check kubelet
sudo systemctl status kubelet
sudo journalctl -u kubelet -n 100
 
# 5. Check API server connectivity from node
curl -k https://<api-endpoint>:443
 
# 6. Verify IAM role policies
aws iam list-attached-role-policies --role-name <node-role>
 
# 7. Check aws-auth ConfigMap
kubectl get configmap aws-auth -n kube-system -o yaml
 
# 8. Check security groups allow port 443 outbound
aws ec2 describe-security-groups --group-ids <sg-id>