EKS aws cluster_error ai_generated true

Node not joining the EKS cluster: nodes are NotReady

ID: aws/aws-eks-node-not-joining

Also available as: JSON · Markdown
78%Fix Rate
82%Confidence
90Evidence
2023-01-01First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
2 active — — —

Root Cause

EKS worker nodes fail to register with the control plane due to IAM, networking, or aws-auth ConfigMap issues.

generic

Workarounds

  1. 85% success Verify aws-auth ConfigMap includes the node IAM role ARN 
    kubectl get configmap aws-auth -n kube-system -o yaml and ensure the node role ARN is listed under mapRoles

    Sources: https://docs.aws.amazon.com/eks/latest/userguide/add-user-role.html

  2. 80% success Check node security group allows communication with the control plane 
    Ensure node security group allows outbound 443 to the cluster endpoint and inbound from the cluster security group

    Sources: https://docs.aws.amazon.com/eks/latest/userguide/sec-group-reqs.html

Dead Ends

Common approaches that don't work:

  1. Terminate and re-launch nodes without fixing the root cause 90% fail

    New nodes will have the same misconfiguration and fail to join identically

  2. Upgrade the EKS control plane version to fix node joining 70% fail

    Version upgrades can make things worse if node AMI is incompatible with the new control plane version

Error Chain

Leads to:
Preceded by:
Frequently confused with: