终极指南：解决 Terraform AWS EKS Cluster 项目的常见问题与高效解决方案 🛠️

Terraform AWS EKS Cluster 项目是一个用于快速部署和管理 AWS EKS 集群的 Terraform 模块，帮助开发者轻松构建 Kubernetes 环境。本文将详细解答使用过程中可能遇到的各类问题，并提供实用的解决方案，让你的 EKS 集群部署和维护更加顺畅。

Terraform AWS EKS Cluster 项目封面图

🔍 版本迁移中的常见问题与解决方案

从版本 2 或 3 升级到版本 4 时的认证模式错误

在将模块从版本 2 或 3 升级到版本 4 时，若直接将认证模式从 "CONFIG_MAP" 切换到 "API"，可能会遇到 AWS 不支持直接升级的错误。这是因为 AWS 要求必须先过渡到 "API_AND_CONFIG_MAP" 模式，然后才能完全切换到 "API" 模式。

解决方案：

1. 首先在配置中将 authentication_mode 设置为 "API_AND_CONFIG_MAP"，执行 terraform apply 应用更改。
2. 待集群成功更新到 "API_AND_CONFIG_MAP" 模式后，再将 authentication_mode 修改为 "API"，再次执行 terraform apply 完成最终切换。

相关配置可参考 docs/migration-v3-v4.md 文档中的详细说明。

升级后 Security Group 无法删除的超时错误

如果在版本 2 中设置了 create_security_group = true，升级到版本 4 时若未做任何处理，Terraform 会尝试删除该 Security Group，由于该组可能仍与某些资源关联，从而导致超时错误。

解决方案： 可选择以下任一方式解决：

• 手动删除 Security Group 并移除所有对它的引用。
• 将 Security Group 的配置和使用迁移到 EKS 托管的 Security Group。
• 在根模块或单独的组件中使用 security-group 模块 创建新的 Security Group。

具体操作步骤可查看 docs/migration-v3-v4.md 中关于安全组迁移的章节。

🔧 访问控制配置问题

IAM 主体 ARN 路径处理错误

在旧版本中使用 aws-auth ConfigMap 时，需要移除 IAM 主体 ARN 中的路径组件。但在版本 4 中使用新的 AWS API 管理访问控制时，需要提供完整的 ARN，若仍沿用旧的路径移除方式，会导致权限配置错误。

解决方案： 撤销之前对 ARN 路径的手动或程序移除操作，在新配置中提供包含完整路径的 IAM 主体 ARN。例如，对于 ARN arn:aws:iam::111122223333:role/my-team/developers/my-role，无需再移除 my-team/developers/ 部分。

示例配置可参考 docs/migration-v3-v4.md 中关于访问条目迁移的示例代码。

创建 EKS Access Entry 时的 ResourceInUseException 错误

在将集群从 "CONFIG_MAP" 模式升级到 "API_AND_CONFIG_MAP" 模式过程中，EKS 会自动为集群创建者添加一个访问条目。如果此时在配置中也定义了相同 IAM 主体的访问条目，执行 terraform apply 时会出现该错误。

解决方案：

1. 从错误消息中获取访问条目的 ID（如 eg-test-eks-cluster:arn:aws:iam::123456789012:role/eg-test-terraform）和资源地址。
2. 使用 terraform import 命令将自动创建的访问条目导入到 Terraform 状态中，例如：

   terraform import -var-file <configuration-file> 'module.eks_cluster.aws_eks_access_entry.map["arn:aws:iam::123456789012:role/eg-test-terraform"]' 'eg-test-eks-cluster:arn:aws:iam::123456789012:role/eg-test-terraform'
   

3. 导入成功后，再次执行 terraform apply 完成剩余配置。

详细的导入步骤可参考 docs/migration-v3-v4.md 中的相关内容。

✅ 集群部署后验证步骤

升级后验证集群访问权限

升级完成后，务必验证是否仍拥有预期的集群访问权限，可通过以下命令检查：

# 检查是否拥有完全的集群管理员权限
kubectl auth can-i '*' '*'
# 检查基本的节点读取权限
kubectl get nodes

如果安装了 rakkess 工具，还可以运行 rakkess 命令查看更详细的访问权限报告。

📚 总结

Terraform AWS EKS Cluster 项目在使用过程中，尤其是版本升级和访问控制配置方面，可能会遇到各种问题。但只要按照本文提供的解决方案和 docs/migration-v3-v4.md 官方文档进行操作，就能顺利解决这些常见问题。希望本文能帮助你更高效地使用该模块，构建稳定可靠的 EKS 集群。如果遇到其他未涵盖的问题，建议查阅项目的官方文档或提交 issue 寻求帮助。