Terraform Plan执行5分钟超时问题排查请求

云原生阿岚

2026-7-17

排查建议

以下是针对Terraform Plan阶段状态刷新超时问题的具体排查步骤：

1. 版本兼容性验证

本地使用计划升级的Terraform版本（如0.12.x最新版或0.13+）复现terraform plan操作，确认是否仍存在超时问题。0.12.6属于较旧版本，可能存在AWS Provider状态轮询逻辑的已知bug。
同步升级对应AWS Provider版本：Terraform 0.12.6兼容的AWS Provider最新稳定版为v2.70.0左右，更新provider版本后重新测试，旧版本provider可能存在资源状态查询的超时逻辑缺陷。

逐步注释Terraform脚本中的模块（先注释Helm Release模块，再注释EKS，最后保留Neptune），分别执行terraform plan，定位触发超时的具体模块。由于每次超时的资源不固定，需多次测试确认是否存在特定模块的共性问题。
针对单个可疑资源，单独执行状态查询：使用terraform state show <resource-id>（如terraform state show aws_neptune_parameter_group.main），观察是否能正常返回状态，耗时多久。

网络与延迟测试：在Github Action的plan步骤前添加网络诊断命令，测试AWS服务的响应速度：
```
curl -w "%{time_total}s\n" -v https://neptune.<your-region>.amazonaws.com
aws eks describe-cluster --name <your-cluster-name> --query 'cluster.status'
```
确认是否存在网络延迟过高的情况。
资源限制检查：Github Action默认runner的CPU/内存资源可能不足，导致Terraform进程在批量刷新状态时被限流。尝试使用GitHub-hosted的Large Runner或自托管runner，提升资源配置后重新测试。
IAM权限验证：状态刷新需要只读权限（如neptune:DescribeDBClusters、eks:DescribeClusters、eks:ListNodegroups等），检查Github Action使用的IAM角色是否包含完整的只读权限集，避免因权限不足导致的状态查询阻塞。

远程状态检查：若使用S3等远程状态存储，拉取本地状态文件执行terraform state list，确认状态文件无损坏或异常条目；同时检查状态锁是否被异常占用，必要时手动释放锁。
手动设置资源超时：针对可疑资源添加timeouts块，延长状态轮询超时时间，例如：
```
resource "aws_eks_cluster" "main" {
  # 其他配置
  timeouts {
    create = "15m"
    update = "15m"
    delete = "15m"
  }
}
```
注意：plan阶段的状态刷新超时本质是provider对资源当前状态的轮询超时，延长超时参数可排查是否为资源状态变更缓慢导致的问题。

手动验证EKS集群访问：在Github Action中添加步骤，获取kubeconfig并测试K8s API访问：
```
aws eks update-kubeconfig --name <cluster-name> --region <region>
kubectl get namespaces --timeout=5m
```
确认K8s API是否能正常响应，避免因kubeconfig获取失败或K8s集群未就绪导致的Helm状态刷新阻塞。
升级Helm Provider版本：确保使用与Terraform 0.12.6兼容的最新Helm Provider版本，旧版本可能存在K8s资源状态查询的兼容性问题。

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