EKS节点加入集群所需bootstrap脚本配置规范与问题排查

现有配置的明确错误 #

• Launch Template的User Data配置完全不生效：当前配置user_data = base64encode("linux_user_data.tpl")的逻辑是对字符串linux_user_data.tpl做Base64编码，并没有读取模板文件的实际内容，节点启动时拿到的User Data就是这串文件名文本，根本不会执行集群加入逻辑。
• 三个版本的bootstrap脚本均存在语法/参数错误：
  • 版本1：脚本内的${pre_bootstrap_user_data ~}、${cluster_service_ipv4_cidr}等变量没有经过模板渲染替换为实际值，脚本运行时会直接因为变量未定义报错退出。
  • 版本2：仅传入集群名称，缺少API Server地址、集群CA证书两个核心鉴权参数，自定义AMI场景下节点无法自动发现集群控制面地址，无法建立连接。
  • 版本3：遗漏bootstrap脚本必填的集群名称位置参数，脚本启动直接报参数错误退出；且直接在tpl模板文件内写${aws_eks_cluster.eks.endpoint}这类Terraform资源引用语法无效，模板文件本身不会解析Terraform资源属性，必须通过模板渲染传入参数。
• 额外前置校验项：由于你配置的ami_type = "CUSTOM"，必须保证自定义AMI基于对应EKS版本的官方优化AMI制作，自带/etc/eks/bootstrap.sh脚本和匹配版本的kubelet、kubectl、CNI组件，否则脚本本身不存在也会导致加入失败。

bootstrap脚本必填参数 #

自定义AMI场景下，/etc/eks/bootstrap.sh必须传入三个核心参数，缺任何一个都会导致节点加入失败：

• 第一位置参数：EKS集群的实际名称
• --apiserver-endpoint：EKS集群API Server的公网/私网访问地址，对应Terraform资源属性aws_eks_cluster.eks.endpoint
• --b64-cluster-ca：EKS集群Base64编码的CA根证书，对应Terraform资源属性aws_eks_cluster.eks.certificate_authority[0].data
  其余参数比如服务网段、kubelet自定义参数、容器运行时配置等属于可选项，无特殊需求不需要额外传入。

修正后的可运行配置 #

1. 首先修改linux_user_data.tpl模板文件内容，使用标准模板变量占位符，不要直接写Terraform资源引用：

#!/bin/bash
set -o xtrace
/etc/eks/bootstrap.sh ${cluster_name} \
  --apiserver-endpoint ${cluster_endpoint} \
  --b64-cluster-ca ${cluster_ca_data}

2. 在Terraform配置中新增模板渲染数据源，修正Launch Template的User Data加载逻辑：

# 渲染节点启动脚本
data "template_file" "eks_node_userdata" {
  template = file("${path.module}/linux_user_data.tpl")
  vars = {
    cluster_name     = aws_eks_cluster.eks.name
    cluster_endpoint = aws_eks_cluster.eks.endpoint
    cluster_ca_data  = aws_eks_cluster.eks.certificate_authority[0].data
  }
}

resource "aws_launch_template" "node" {
  image_id      = var.image_id
  instance_type = var.instance_type
  key_name      = var.key_name
  name          = var.name
  # 传入渲染后的脚本内容并做Base64编码
  user_data     = base64encode(data.template_file.eks_node_userdata.rendered)

  block_device_mappings {
    device_name = "/dev/sda1"
    ebs {
      volume_size = 20
    }
  }
}

上线前校验项 #

• 确认节点IAM角色正确绑定AmazonEKSWorkerNodePolicy、AmazonEKS_CNI_Policy、AmazonEC2ContainerRegistryReadOnly三个托管策略，无自定义权限裁剪。
• 确认节点所在私有子网的路由、安全组放通节点到EKS API Server的443端口访问，节点与EKS控制面安全组之间允许双向通信。
• 确认自定义AMI的EKS组件版本与集群版本差不超过1个小版本，避免kubelet版本不兼容导致注册失败。

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