Terraform AWS EKS 模块：解决节点无法加入集群的网络问题

问题背景

在使用 Terraform AWS EKS 模块部署 Kubernetes 集群时，一个常见但容易被忽视的问题是节点实例无法成功加入集群。这个问题通常表现为节点启动后无法完成初始化，在检查系统日志时会发现节点无法访问 AWS EC2 API 端点。

问题现象分析

从日志中可以观察到几个关键现象：

1. 节点初始化时尝试调用 EC2 DescribeInstances API 失败
2. 请求超时，重试3次后放弃
3. 手动在节点上执行 aws ec2 describe-instances 命令也会挂起
4. 节点无法获取自身的实例信息，导致无法完成加入集群的流程

根本原因

经过深入排查，发现问题的根源在于 VPC 端点配置与安全组的联动问题：

1. VPC 中配置了 EC2 接口端点（Interface Endpoint）
2. 但节点所在的安全组未被添加到该端点的安全组允许列表中
3. 由于某些原因（可能是之前的配置变更），这个端点成为了默认路由
4. 导致节点尝试通过端点访问 EC2 API 时被阻断

解决方案

要解决这个问题，可以采取以下步骤：

1. 检查 VPC 端点配置：

   • 确认 VPC 中是否存在 EC2 接口端点
   • 检查端点的安全组配置

2. 更新安全组规则：

   • 将节点实例的安全组添加到 EC2 端点的允许列表中
   • 或者为端点创建专用的安全组规则

3. 验证网络连通性：

   • 在节点上测试到 EC2 API 端点的连接
   • 确认能够成功调用 DescribeInstances 等 API

4. 重新部署节点：

   • 在修复网络配置后，重新创建节点组
   • 观察节点初始化日志确认问题已解决

最佳实践建议

为了避免类似问题，建议在部署 EKS 集群时：

1. 明确网络规划：

   • 提前规划好 VPC 端点使用策略
   • 明确哪些服务需要通过端点访问

2. 安全组管理：

   • 为不同组件（控制平面、节点、端点）设计清晰的安全组规则
   • 建立安全组之间的允许关系矩阵

3. 测试验证：

   • 部署后立即验证节点初始化情况
   • 建立自动化测试验证网络连通性

4. 文档记录：

   • 记录所有网络端点配置及其关联的安全组
   • 为后续维护提供清晰的网络拓扑图

总结

在 AWS EKS 环境中，网络配置是确保集群正常运行的基础。VPC 端点的错误配置可能导致节点无法访问必要的 AWS 服务 API，进而无法加入集群。通过系统性地检查网络连接、安全组规则和端点配置，可以有效地解决这类问题。建议在部署前充分测试网络配置，并建立完善的监控机制，以便快速发现和解决网络连通性问题。