指定启动模板ID时EKS节点组创建失败求助

报错信息 #

Resource handler returned message: "[Issue(Code=NodeCreationFailure, Message=Instances failed to join the kubernetes cluster, ResourceIds=[i-0ce4d16dfdaba673f])] (Service: null, Status Code: 0, Request ID: null)" (RequestToken: 26cdbc72-af9f-e2cd-3280-fa0e737b8d5f, HandlerErrorCode: GeneralServiceException)

已完成的验证 #

• NAT网关位于公有子网中
• 节点组创建在us-east-1b可用区，与NAT网关同AZ，私有子网路由表已指向NAT网关作为出口
• 启动模板关联的安全组为EKS集群的安全组

启动模板代码 #

AWSTemplateFormatVersion: 2010-09-09
Description: Creates AWSCloudFormationStackSetAdministrationRole which will be used by stacks to provision resources.

Parameters:
  ImageID:
    Type: AWS::EC2::Image::Id
    Description: AWS Image Id of instance type.
    Default: "ami-0a3da8b47de1d87b8"
  accountname:
    Type: String
    Default: "sandboxdemo3"
  InstanceType:
    Type: String
    Default: t3.medium

Resources:
  MyLaunchTemplate:
   Type: AWS::EC2::LaunchTemplate
   Properties:
     LaunchTemplateName: eks-customlaunch-template
     LaunchTemplateData:
       UserData: 
         Fn::Base64: 
           !Sub |
            #!/bin/bash
            echo "Custom user data script"
            yum update -y 
            yum install -y awslogs
            cat > /etc/awslogs/awslogs.conf << EOF
            [general]
            state_file = /var/lib/awslogs/agent-state

            [syslog]
            datetime_format = %b %d %H:%M:%S
            file = /var/log/messages
            buffer_duration = 5000
            log_stream_name = {instance_id}
            initial_position = start_of_file
            log_group_name = /aws/k8/${accountname}-syslog

            [zio]
            datetime_format = %b %d %H:%M:%S
            file = /run/containerd/io.containerd.runtime.v2.task/k8s.io/*/rootfs/var/log/zio-testing.log
            buffer_duration = 5000
            log_stream_name = {instance_id}-${accountname}
            initial_position = start_of_file
            log_group_name = /aws/k8/${accountname}-zio"
            EOF
            systemctl start awslogsd
            systemctl enable awslogsd
       ImageId: !Ref ImageID
       InstanceType: !Ref InstanceType
       BlockDeviceMappings:
         - DeviceName: '/dev/sdh'
           Ebs:
             VolumeSize: 80
       SecurityGroupIds:
         - Fn::ImportValue:
            #  'Fn::Sub': 'eksctl-myeks-${AWS::AccountId}-cluster::ClusterSecurityGroupId'
             'Fn::Sub': 'eksctl-demov6-cluster::ClusterSecurityGroupId'
       TagSpecifications:
         - ResourceType: instance
           Tags:
             - Key: alpha.eksctl.io/cluster-name
               Value: demov6
             - Key: alpha.eksctl.io/nodegroup-name
               Value: demobasev6-2
             - Key: k8s.io/cluster-autoscaler/enabled
               Value: true
            #  - Key: !Sub k8s.io/cluster-autoscaler/myeks-${AWS::AccountId}
            #    Value: owned
            #  - Key: !Sub kubernetes.io/cluster/myeks-${AWS::AccountId}
            #    Value: owned
             - Key: k8s.io/cluster-autoscaler/demov6
               Value: owned
             - Key: kubernetes.io/cluster/demov6
               Value: owned

节点组YAML文件 #

apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig
managedNodeGroups:
- amiFamily: AmazonLinux2
  desiredCapacity: 1
  launchTemplate:
    version: "1"
    id: lt-0a99b80de662a40be
  iam:
    withAddonPolicies:
      albIngress: false
      appMesh: false
      appMeshPreview: false
      autoScaler: true
      awsLoadBalancerController: true
      certManager: false
      cloudWatch: false
      ebs: false
      efs: false
      externalDNS: false
      fsx: false
      imageBuilder: false
      xRay: false
  labels:
    alpha.eksctl.io/cluster-name: demov6
    alpha.eksctl.io/nodegroup-name: demobasev6-2
  maxSize: 4
  minSize: 1
  name: demobasev6-2
  availabilityZones: ["us-east-1b"]
  privateNetworking: true
  releaseVersion: ""
  tags:
    alpha.eksctl.io/nodegroup-name: demobasev6-2
    alpha.eksctl.io/nodegroup-type: managed
  volumeThroughput: 125
  volumeType: gp3
metadata:
  name: demov6
  region: us-east-1
  version: "1.24"

问题排查与解决建议 #

1. 自定义UserData覆盖了EKS初始化逻辑 #

自定义UserData会完全替换EKS默认的节点初始化脚本，导致节点无法执行加入集群的核心步骤。需在自定义脚本开头添加默认初始化脚本调用：

#!/bin/bash
# 保留EKS节点加入集群的核心逻辑
/etc/eks/bootstrap.sh demov6 --kubelet-extra-args "--node-labels=alpha.eksctl.io/cluster-name=demov6,alpha.eksctl.io/nodegroup-name=demobasev6-2"

# 以下是你的自定义脚本内容
echo "Custom user data script"
yum update -y 
yum install -y awslogs
# ... 其余自定义代码

注意将demov6替换为你的集群名称，kubelet标签需与节点组配置保持一致。

2. UserData存在语法错误 #

检查到[zio]段的log_group_name末尾多了一个双引号：

log_group_name = /aws/k8/${accountname}-zio"

该错误会导致awslogs.conf格式失效，中断脚本执行。需删除多余的双引号。

3. 验证节点IAM角色权限 #

确认节点角色拥有以下核心权限（eksctl托管节点组默认会添加，但自定义启动模板需手动确认）：

• AmazonEKSWorkerNodePolicy
• AmazonEC2ContainerRegistryReadOnly
• AmazonEKS_CNI_Policy
  这些权限是节点连接EKS集群的必要条件。

4. 查看节点系统日志定位具体错误 #

通过AWS控制台进入EC2实例详情页，在「监控」选项卡中获取系统日志，重点排查：

• EKS API服务器连接失败信息
• IAM角色权限报错
• bootstrap.sh脚本执行异常日志

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