4. Provider与版本约束策略

在企业模块平台中，版本约束不是“顺手写一下”的附属品，而是决定模块能否被安全复用、能否被批量升级、能否在 CI 中稳定通过的核心契约。一个模块今天在某人笔记本上能 apply，不代表三个月后换一个 Terraform 版本、换一个 Provider 大版本还能正常工作。Provider 与核心版本约束策略要解决三个问题：模块声明自己需要什么版本、平台如何统一锁定这些版本、升级时如何判断兼容与风险。

一、两类版本约束必须分开管理

Terraform 生态里存在两条独立的版本线，混在一起管理是常见错误。

• Terraform 核心版本：由 required_version 声明，决定 HCL 语法、语言特性、CLI 行为、状态格式等。例如 optional() 对象属性、import 块、moved 块都依赖核心版本。
• Provider 版本：由 required_providers 中的 version 声明，决定云资源字段、行为、默认值、弃用项。例如 AWS Provider 5.x 与 4.x 在大量资源参数上存在差异。

两者升级节奏不同：核心版本通常按 Terraform 官方发布节奏推进，Provider 版本则跟随云厂商 API 快速迭代。因此企业平台应分别维护“核心版本基线”和“Provider 版本基线”，而不是合成一个笼统的“版本要求”。

二、模块内如何写版本约束

模块的 versions.tf 是版本契约的唯一入口。推荐把核心版本与 Provider 版本集中声明，避免散落在各文件。

terraform {
  required_version = ">= 1.6.0, < 2.0.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.40"
    }
    random = {
      source  = "hashicorp/random"
      version = "~> 3.6"
    }
  }
}

这里有几个关键约定。第一，required_version 使用下界加主版本上界，例如 >= 1.6.0, < 2.0.0，既允许小版本升级获得修复，又阻止跨主版本带来的破坏性变更。第二，Provider 使用 ~> 悲观约束，~> 5.40 等价于 >= 5.40.0, < 6.0.0，允许 5.x 内的补丁与次版本，但不跨 6.0。第三，模块本身不应写死精确版本（如 = 5.40.1），精确锁定应交给根模块的 lock 文件或平台层，否则模块复用性会急剧下降。

三、企业级版本基线与兼容性矩阵

平台团队需要维护一张兼容性矩阵，明确“哪些 Terraform 核心版本 + 哪些 Provider 版本组合是被支持的”。矩阵不是越宽越好，而是要覆盖真实使用场景，并让 CI 能验证。

矩阵中的每一行都应能被 CI 实际执行。例如对 B1 和 B2 分别跑 terraform init -upgrade 与 terraform validate，确认模块在两条基线下都能通过。B3 用于提前发现破坏性变更，B4 只保留记录，不再接受新提交。

四、版本升级的判断路径

升级不能靠“先升了再说”。下面这张图给出平台推荐的判断路径：从变更类型出发，判断影响面，再决定升级方式与验证手段。

五、锁定文件与平台统一策略

模块声明兼容范围后，真正决定“这次到底用哪个版本”的是 .terraform.lock.hcl。企业平台应把 lock 文件纳入版本控制，并在 CI 中固定使用 terraform init -lockfile=readonly，防止流水线悄悄升级 Provider。对于多平台构建（linux_amd64、darwin_arm64 等），lock 文件需要包含对应平台的哈希，可通过 terraform providers lock -platform=linux_amd64 -platform=darwin_arm64 生成。

平台层还可以通过私有 Registry 或模块仓库统一分发“基线版本”。例如在根模块中引用平台提供的 versions_override.tf，或在 CI 模板中注入 TF_VAR_provider_version，让所有环境从同一矩阵取值，避免各团队各自为政。

六、兼容性矩阵的维护节奏

矩阵不是一次性文档，而是需要持续维护的资产。建议按以下节奏推进：

1. 每月检查 Terraform 与主要 Provider 的发布说明，标记是否有安全修复或破坏性变更。
2. 每季度评估是否将“观察”基线提升为“推荐”，并淘汰一个旧基线。
3. 每次升级在 CI 中同时跑新旧两条基线，确认模块在过渡期内双向可用。
4. 每次破坏性变更在矩阵中记录迁移说明、影响模块清单和回滚方式。

把版本约束写进模块、把基线写进矩阵、把验证写进 CI，三者形成闭环后，Provider 与核心版本升级就从“每次提心吊胆”变成“按流程执行、有据可查”的常规工程活动。这也是企业模块平台能否长期稳定运行的关键基础之一。