Gitlab CI部署Terraform时state文件POST上传失败原因排查

核心错误特征 #

从日志可以看到，上传state请求返回500服务端错误，Terraform默认3次重试全部失败，最终触发报错。该错误为服务端侧偶发异常，和你的流水线基础配置没有直接关联。

可能成因 #

• Gitlab服务端已知缺陷：低版本Gitlab的Terraform state管理模块存在大量已知bug，比如大体积state上传处理异常、并发写入冲突未正确兜底，都会触发API返回500错误
• Gitlab服务端资源瓶颈：Gitlab实例的存储IO不足、API网关限流/超时、存放state的对象存储服务可用性波动，都会导致上传请求失败
• 网络链路波动：Gitlab Runner与Gitlab实例之间的网络丢包、延迟抖动，刚好出现在state上传阶段，3次重试窗口内没有恢复就会触发报错
• CI_JOB_TOKEN权限时效问题：如果apply执行时间过长，刚好在资源创建完成后CI_JOB_TOKEN过期，也会导致上传请求被拒绝，不过该场景出现概率较低

修复建议 #

临时规避方案 #

不要直接重跑apply作业，你已经配置了失败时自动上传errored.tfstate文件，重新执行作业时新增步骤：

terraform state push errored.tfstate

先把本地生成的正确状态同步到远端后端，再执行apply操作，可完全避免资源重复创建。

长期优化方案 #

• 升级Gitlab到最新稳定版，修复Terraform backend相关的已知问题
• 调整Terraform后端重试配置，增大重试次数到5-10次，拉长重试间隔，提升波动场景下的成功率
• 拆分大体积state到多个独立的Terraform项目，降低单次state上传的体积，减少超时概率
• 排查Gitlab Runner到Gitlab实例的网络链路，解决丢包、高延迟问题
• 开启Gitlab Terraform state版本管理功能，异常情况下可快速回滚到历史正常状态

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