AWS EKS节点组创建失败：实例无法加入集群

问题描述 #

尝试为AWS EKS集群添加节点组时，始终失败，报错如下：

NodeCreationFailure: Instances failed to join the kubernetes cluster

• CloudTrail中AWS::EKS::Cluster、AWS::EKS::Nodegroup、AWS::EC2::Instance资源无错误记录
• CloudWatch已开启的EKS日志（api、audit、authenticator、controllerManager、scheduler）未发现异常
• 执行AWSSupport-TroubleshootEKSWorkerNode运行手册时提示集群不存在，但集群实际状态健康
• 已完成以下排查仍未解决：
  1. 节点IAM角色权限符合文档要求，已添加至aws-auth配置映射
  2. CloudFormation模板通过ClusterName: !Ref EksCluster绑定集群，名称完全匹配
  3. EC2实例已添加kubernetes.io/cluster/my-cluster = owned标签，自动伸缩组及实例状态检查正常
  4. EKS集群EndpointPrivateAccess = true、EndpointPublicAccess = false，EC2实例位于同可用区私有子网，子网配置NAT网关路由
  5. 部署节点的AWS区域STS端点已启用
  6. VPC DHCP选项集配置domain-name:<region>.compute.internal和domain-name-servers:AmazonProvidedDNS
  7. 节点所在私有子网具备互联网出站访问权限

额外排查与解决方案 #

1. 检查节点kubelet日志 #

问题大概率出在节点本地，登录EC2实例（通过Session Manager或私有网络SSH），查看kubelet运行日志：

journalctl -u kubelet -f

重点关注是否存在API服务器连接失败、身份令牌获取失败、DNS解析异常等信息，这些会直接导致节点无法加入集群。

2. 验证EKS私有端点的DNS解析 #

在节点上执行解析测试，确认能正确解析集群私有端点：

nslookup my-cluster.<region>.eks.amazonaws.com

如果解析失败，检查VPC的两个关键DNS配置：

• enableDnsSupport是否设为true（允许VPC内部DNS解析）
• enableDnsHostnames是否设为true（允许EC2实例获取私有DNS hostname）

3. 校验安全组互通规则 #

节点安全组与集群控制平面安全组需满足以下规则：

• 节点安全组：出站规则允许TCP 443流量到集群控制平面安全组
• 集群控制平面安全组：入站规则允许TCP 443流量来自节点安全组
  缺少任一规则都会导致kubelet无法连接EKS API服务器。

4. 确认aws-auth ConfigMap格式正确性 #

即使已添加角色，也要检查ConfigMap的格式是否完全正确，无拼写错误：

kubectl get configmap aws-auth -n kube-system -o yaml

确保mapRoles配置如下（替换占位符为实际信息）：

mapRoles:
- rolearn: arn:aws:iam::<你的AWS账号ID>:role/<节点IAM角色名>
  username: system:node:{{EC2PrivateDNSName}}
  groups:
    - system:bootstrappers
    - system:nodes

若有错误，更新ConfigMap后重启节点kubelet：

systemctl restart kubelet

5. 检查节点IAM角色信任关系 #

确认节点IAM角色的信任策略允许EC2服务承担该角色：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "ec2.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

信任策略配置错误会导致节点无法获取IAM凭证，进而无法通过集群身份认证。

6. 测试STS端点访问 #

在节点上执行STS调用，验证能否正常获取身份信息：

aws sts get-caller-identity

如果返回节点IAM角色的信息，说明STS访问正常；若报错，检查NAT网关是否正常转发流量，或是否配置了STS的VPC端点（私有网络场景下推荐配置）。

7. 确认节点AMI兼容性 #

确保节点组使用的是对应EKS版本的官方优化AMI，非兼容AMI会导致kubelet版本与集群控制平面不匹配，无法正常加入集群。

8. 复查CloudFormation节点组参数 #

再次确认节点组的CloudFormation参数：

• Subnets是否为正确的私有子网ID
• NodeRole是否为节点IAM角色的完整ARN
• ClusterName是否与目标集群名称完全一致（大小写敏感）

内容的提问来源于stack exchange，提问作者David Gard