使用Terraform AWS EKS模块在现有VPC中部署节点组的问题解析

问题背景

在使用terraform-aws-modules/eks/aws模块部署Amazon EKS集群时，许多用户遇到了一个常见问题：当尝试在现有VPC中部署EKS托管节点组时，节点无法成功加入Kubernetes集群。这个问题通常表现为节点组创建失败，并显示"NodeCreationFailure: Instances failed to join the kubernetes cluster"的错误信息。

问题现象

用户在两种场景下部署EKS集群：

1. 使用模块内置的VPC模块创建全新VPC和子网
2. 使用现有的VPC和子网资源

第一种场景下集群部署正常，但第二种场景下节点组创建失败。通过检查发现，节点实例虽然能够启动，但无法完成加入集群的过程。

根本原因分析

经过深入调查，发现问题主要源于以下几个关键因素：

1. 用户数据缺失：当使用自定义AMI或现有VPC时，节点实例缺少必要的引导用户数据(bootstrap user data)，这些数据负责配置节点以正确加入EKS集群。

2. 安全组配置不当：节点实例没有正确附加集群的主要安全组，导致网络通信受阻。

3. IAM权限不足：在某些情况下，节点实例角色缺少从ECR拉取必要容器镜像的权限。

解决方案

针对上述问题，可以通过以下配置修正：

eks_managed_node_groups = {
  group1 = {
    ami_type = "AL2_x86_64"
    ami_id   = data.aws_ami.eks_default.image_id

    # 关键配置：启用引导用户数据
    enable_bootstrap_user_data = true

    # 关键配置：附加集群主要安全组
    attach_cluster_primary_security_group = true

    instance_types = ["m5.xlarge"]
    min_size       = 1
    max_size       = 4
    desired_size   = 1
    
    subnet_ids = data.terraform_remote_state.vpc.outputs.private_subnet_ids
  }
}

配置说明

1. enable_bootstrap_user_data：这个参数设置为true时，模块会自动生成必要的用户数据脚本，用于配置节点加入集群所需的kubelet和容器运行时环境。

2. attach_cluster_primary_security_group：确保节点实例附加了集群的主要安全组，这是节点与控制平面通信的必要条件。

3. IAM角色权限：虽然未在示例中直接展示，但确保节点实例角色具有AmazonEKSWorkerNodePolicy、AmazonEC2ContainerRegistryReadOnly和AmazonEKS_CNI_Policy等必要策略。

最佳实践建议

1. 对于生产环境，建议明确指定所有必要的配置参数，避免依赖模块默认值。

2. 在部署前，使用AWS CLI验证启动模板是否有效：

   aws ec2 run-instances --launch-template LaunchTemplateName=your-template-name --dry-run
   

3. 监控CloudTrail日志，可以获取更详细的错误信息，帮助诊断问题。

4. 对于复杂的网络环境，确保NAT网关、路由表和网络ACL配置允许节点与控制平面之间的必要通信。

版本兼容性说明

这个问题在模块v20.x版本中较为常见，而v19版本通常不会出现。用户在升级模块版本时应当注意检查这些配置差异。

通过正确配置上述参数，可以确保EKS托管节点组在现有VPC环境中能够成功创建并加入集群。这种配置方式既保持了灵活性，又能充分利用Terraform模块提供的便利功能。