Terraform AWS EKS 模块中自管理节点组加入集群问题解析

在使用 Terraform AWS EKS 模块部署自管理节点组时，许多用户遇到了节点无法加入集群的问题，特别是当使用非 Amazon Linux 2 的 AMI 时。本文将深入分析这一问题的根源，并提供完整的解决方案。

问题现象

用户在使用自管理节点组部署 EKS 集群时，通常会遇到以下症状：

1. 节点组创建成功但节点无法加入集群
2. CoreDNS 插件状态显示为 "DEGRADED"
3. 集群附加组件部署超时
4. 控制台显示节点处于 "NotReady" 状态

根本原因分析

经过社区讨论和验证，发现问题主要源于以下几个方面：

1. AMI 类型不匹配：在 Terraform AWS EKS 模块的 20.x 版本中，自管理节点组默认使用 AL2_x86_64 作为 AMI 类型，即使指定了不同的平台类型。

2. 平台类型与 AMI 类型优先级：模块内部逻辑中，ami_type 参数的优先级高于 platform 参数，导致即使用户设置了 platform = "al2023"，实际仍会使用默认的 AL2 类型。

3. 用户数据配置：对于非 AL2 的 AMI（如 AL2023 或 Bottlerocket），需要特定的用户数据格式才能正确加入集群。

解决方案

1. 明确指定 AMI 类型

对于不同的操作系统类型，必须显式设置 ami_type 参数：

self_managed_node_groups = {
  al2023_node = {
    ami_type = "AL2023_x86_64_STANDARD"
    # 其他配置...
  }
  
  bottlerocket_node = {
    ami_type = "BOTTLEROCKET_x86_64"
    # 其他配置...
  }
  
  custom_node = {
    ami_type = "CUSTOM"
    ami_id   = "ami-1234567890abcdef0"
    # 其他配置...
  }
}

2. 正确配置用户数据

对于 AL2023 节点，需要使用 nodeadm 格式的用户数据：

cloudinit_pre_nodeadm = [
  {
    content_type = "application/node.eks.aws"
    content      = <<-EOT
      ---
      apiVersion: node.eks.aws/v1alpha1
      kind: NodeConfig
      spec:
        cluster: my-cluster
        apiServerEndpoint: https://xxxx.yl4.us-west-2.eks.amazonaws.com
        certificateAuthority: xxxxx
        kubelet:
          config:
            shutdownGracePeriod: 30s
            featureGates:
              DisableKubeletCloudCredentialProviders: true
    EOT
  }
]

3. 安全组配置

确保节点组能够与控制平面通信：

vpc_security_group_ids = [
  module.eks.cluster_primary_security_group_id,
  module.eks.cluster_security_group_id,
]

最佳实践

1. 始终明确指定 AMI 类型：不要依赖默认值，特别是使用非 AL2 的 AMI 时。

2. 验证 VPC 配置：确保子网正确配置了标签，且路由表允许节点与控制平面通信。

3. 监控节点引导过程：通过 EC2 实例的控制台日志检查节点加入过程中的错误。

4. 逐步测试：先部署最小规模的节点组验证配置，再扩展到生产规模。

5. 使用最新模块版本：确保使用修复了相关问题的模块版本（20.14.0 或更高）。

自定义 AMI 注意事项

当使用自定义 AMI（如 CIS 加固的 AMI）时，需要额外注意：

1. AMI 必须包含必要的 EKS 组件和依赖项
2. 可能需要调整用户数据以适应自定义 AMI 的特殊要求
3. 确保 AMI 与 EKS 控制平面版本兼容
4. 测试 AMI 的所有功能，包括日志收集、监控等

通过遵循这些指导原则，可以避免自管理节点组加入集群时的常见问题，确保 EKS 集群的健康运行。