配置GitLab Terraform后端后执行terraform apply遇API 404，状态保存失败

问题描述 #

按照文档配置GitLab托管的Terraform状态后端后，执行terraform apply时收到GitLab API返回的404错误，日志如下：

2022-11-28T20:50:47.082+0200 [DEBUG] POST https://gitlab.com/api/v4/projects/<REDACTED PROJECT ID>/terraform/state/?ID=xxx-xxx-xx-xxx-xx-xxx
╷
│ Error: Failed to save state
│
│ Error saving state: HTTP error: 404

│ Error: Failed to persist state to backend

可能遗漏的配置/操作步骤 #

1. 状态后端路径格式错误 #

GitLab Terraform状态API的正确路径应为/projects/<PROJECT_ID>/terraform/state/<STATE_NAME>，而非带?ID=参数的格式。检查你的Terraform后端配置：

• 确认backend "gitlab"块中的address、lock_address、unlock_address字段，需直接将状态名称拼接在路径末尾，而非通过URL参数传递。
• 正确配置示例：

  backend "gitlab" {
    address = "https://gitlab.com/api/v4/projects/<PROJECT_ID>/terraform/state/my-terraform-state"
    lock_address = "https://gitlab.com/api/v4/projects/<PROJECT_ID>/terraform/state/my-terraform-state/lock"
    unlock_address = "https://gitlab.com/api/v4/projects/<PROJECT_ID>/terraform/state/my-terraform-state/lock"
    username = "<GITLAB_USERNAME>"
    password = "<GITLAB_PERSONAL_ACCESS_TOKEN>"
    lock_method = "POST"
    unlock_method = "DELETE"
  }
  

2. 项目ID或状态名称无效 #

• 确认<REDACTED PROJECT ID>是项目的数字ID，而非项目路径（如username/project-name）。若使用项目路径，需进行URL编码（如username%2Fproject-name），推荐直接用数字ID避免编码问题。
• 检查状态名称是否包含特殊字符，GitLab对状态名称仅支持小写字母、数字、连字符或下划线，特殊字符会导致路径识别失败。

3. 个人访问令牌（PAT）权限不足 #

• 确保使用的PAT拥有api、read_repository、write_repository权限，GitLab托管状态需要这些权限完成状态文件的读写操作。
• 检查PAT是否过期或被撤销。

4. 未执行后端初始化 #

首次使用该后端时，必须先执行terraform init完成后端初始化，确保Terraform正确识别并连接GitLab状态存储。跳过此步骤直接执行apply会导致路径匹配错误。

5. GitLab项目状态异常 #

• 确认项目未被归档或删除，GitLab免费版、标准版均默认支持Terraform状态管理，无需额外启用，但项目状态异常会导致API端点不可用。
• 若使用自托管GitLab实例，检查实例API路径是否正确，是否有反向代理或防火墙拦截了请求。

内容的提问来源于stack exchange，提问作者raphael.oester