IaC 之 OpenTofu

测试环境和生产环境到底差在哪？资源少的时候，问一圈同事，翻翻控制台，大概还能找到答案。当网络、数据库、IAM 和 Kubernetes 集群分散在几个平台，随着时间的流逝，这个答案就很难获取了，更不用说再搭一套相同的环境了。

基础设施即代码 (Infrastructure as Code, IaC) 就是针对这个问题的一种解法：把资源及其关系写进文件，让变更能审查、能复现。Terraform 多年来是常见选择，围绕 HCL 配置语言、Provider 和 Module 积累了大量现成组件。

2023 年 Terraform 更换许可证后，OpenTofu 以现有代码为基础出现。它保留了熟悉的配置和命令流程，此后走向了另一条不归路。

一、许可证变了，为什么会催生一个新项目

为什么许可证会牵动整个生态

Terraform 周围还有云厂商和社区维护的 Provider、团队编写的 Module，以及提供审批、远程运行和审计的平台。核心工具的使用条件改变后，依赖它构建产品的人就得重新评估。

2023 年 8 月 10 日，HashiCorp 宣布将未来版本的 Terraform 等产品改用 BSL 1.1。此前 Terraform 使用的是开源许可证 MPL 2.0 (Mozilla Public License 2.0)。BSL 仍允许查看源代码，也允许许多使用场景，但限制了竞争性使用。按 HashiCorp 的授权条款，这些版本在发布四年后改为 MPL 2.0。

HashiCorp 希望限制竞争产品使用其核心代码。许可 FAQ 区分了企业内部使用和提供竞争性产品。只用 Terraform 管理自家云资源的团队，通常无需因此急着迁移。

托管 IaC 平台、嵌入或二次分发 Terraform 的公司则要判断产品是否落在限制范围内；需要开发新功能时，还得再去研究下是否受限。社区贡献者关心的是另一个问题：提交的代码以后由谁决定许可证。

OpenTofu 是怎样来的

许可证变更后，社区先发表公开宣言，希望 Terraform 继续采用开源许可证。未能达成后，开发者基于仍受 MPL 2.0 许可的代码建立 Fork：2023 年 8 月宣布项目，9 月公开仓库，后来交由 Linux 基金会托管。

共同的代码基础让许多 .tf 文件、Provider 和 Module 可以沿用。但在此之后两边各自更新，差异也就慢慢变大了。

二、OpenTofu 管的到底是什么

OpenTofu 读入配置后，由 Provider 查询云上的资源，结合 State 算出要改什么。人看过 Plan，再由它按依赖关系调用 API。常用命令依次是 tofu init、tofu plan、tofu apply，需要销毁时用 tofu destroy。

Plan 描述的是基础设施变更，不保证业务可用，因为 API 可能拒绝请求，数据库参数即使改成功，应用也可能连不上。

执行过程涉及四个对象：

State 尤其容易被误解成缓存。它保存配置地址与云端资源 ID 的对应关系；映射关系丢了，VPC 并不受影响，但是在下一次 Plan 时可能会要求再建一个。Git 能找回 HCL，找不回后来手工导入的资源 ID。因此 State 需要备份、加锁并限制读取权限。

从一个很小的 AWS 例子看执行过程

下面的配置创建一个 AWS VPC，并输出它的 ID。Provider 和 S3 Backend 都从运行环境的 AWS 凭据链获取身份，配置里不写密钥。

terraform {
  required_version = ">= 1.12.0, < 1.13.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 6.0"
    }
  }

  backend "s3" {
    bucket       = "example-infra-state"
    key          = "network/dev/terraform.tfstate"
    region       = "ap-southeast-1"
    use_lockfile = true
    encrypt      = true
  }
}

provider "aws" {
  region = var.aws_region
}

variable "aws_region" {
  type    = string
  default = "ap-southeast-1"
}

variable "environment" {
  type = string

  validation {
    condition     = contains(["dev", "staging", "prod"], var.environment)
    error_message = "environment must be dev, staging or prod."
  }
}

resource "aws_vpc" "main" {
  cidr_block           = "10.42.0.0/16"
  enable_dns_hostnames = true

  tags = {
    Name        = "app-${var.environment}"
    Environment = var.environment
    ManagedBy   = "opentofu"
  }
}

output "vpc_id" {
  value = aws_vpc.main.id
}

配置里还叫 terraform 块，State 路径里也有 terraform.tfstate。这些名称是兼容旧配置留下的，不妨碍用 tofu 执行。按下面的顺序运行：

export TF_VAR_environment=dev
tofu init
tofu fmt -check
tofu validate
tofu plan -out=dev.tfplan
tofu apply dev.tfplan

init 下载依赖并连接 Backend，validate 检查配置，plan 列出变更，apply 执行保存的计划。把 .terraform.lock.hcl 提交到仓库，本地和 CI 才会使用相同的 Provider 包。

看到 Plan 要求替换 VPC 时，先查触发替换的字段。-auto-approve 只跳过确认提示，不会替你判断计划是否安全。示例中的 use_lockfile 用于锁 State，encrypt = true 启用 S3 服务端加密。

三、工作中会在哪些地方用到它

多云部署：流程可以统一，资源不能照搬

OpenTofu 能通过不同 Provider 统一管理 AWS、Azure、GCP 和 Kubernetes，但同一套工具不等于同一份配置。各家的网络、身份、数据库和计费方式都不同，改个资源名称建不出等价环境。

假设主业务在 AWS，分析平台在 GCP，DNS 交给 Cloudflare。网络、数据库和 DNS 可以各有自己的 Root Module、State 和权限。某个 Provider 暂时不可用时，其他部分仍可独立变更。

复用的是业务接口，不必强求底层参数一致。应用可能只需要数据库地址；凭据应走密钥服务。RDS 与 Cloud SQL 的备份、高可用设置各留在自己的模块里，比把所有参数塞进一串 cloud == "aws" 判断更容易维护。

能在另一家云创建资源也不等于有了灾备。数据复制、DNS 切换、身份和网络互通、备用区域的配额，都得单独验证。OpenTofu 不知道也不会关心业务中最近一笔订单有没有复制过去。

Kubernetes Provider 也可以管理集群资源。应用交付若已由 Flux 持续协调，就要按资源和字段划清所有权：例如 OpenTofu 创建集群和 Namespace，Flux 管 Deployment 与 Service。两边同时修改同一个对象的标签，仍会互相覆盖。OpenTofu 的 plan/apply 是一次运行，Flux 会持续协调，详见 Flux CD 实践。

测试环境可以复制到什么程度

临时测试环境适合用同一批 Module 创建：每个项目传自己的参数，得到独立的网络、计算实例和数据库。验收结束后销毁，比你照着文档逐项点删除更靠谱。

难复制的是数据和外部依赖。生产数据要脱敏，备份恢复需要时间；域名、证书和回调地址也可能由多个环境共用。destroy 能列出受管资源，却不知道哪些数据还要保留。

workspace 让同一套配置使用不同 State，适合差异不大的环境。生产和测试若权限、审批、拓扑都不同，分别建立 Root Module 会更清楚，底层 Module 仍可复用。

漂移检测：先知道发生了什么，再决定谁改回去

有人在控制台放宽了安全组端口，下次 tofu plan 通常能看到差异。定时对已部署的配置运行 Plan，再把结果交给维护者检查，就是最简单的漂移检测。-detailed-exitcode 可以区分无变化、出错和有变更。

Plan 有差异未必是控制台改动：代码可能尚未部署，Provider 升级也可能改变计划结果。HPA 管的副本数等字段，可以明确交给别的控制器，必要时只对这些字段使用 ignore_changes。忽略整个资源会连意外改动一起藏掉。

发现漂移后，先弄清是谁改的、为什么改，再决定保留还是改回去。事故期间临时调整的路由，可能正维持着刚恢复的服务。

报告要写清目标账户、State Key 和用于比较的 Commit。假设代码周五合并、周六才部署，周五夜里的差异只是待部署变更。反过来，手工修改若恰好与 HCL 一致，Plan 也可能毫无动静；这时要靠云审计日志查是谁先改了资源。

告警至少列出变更的资源及动作，尤其标出替换和删除。凭据过期导致的检测失败也要报警，不能算作没有漂移。

导入存量资源：先接管，再重构

接手已有的 VPC 或数据库时，可以用 import 块或 tofu import 将云端对象关联到配置地址。导入只建立映射，不会替你写出高可读性的 HCL。手动设置过的字段还得逐个核对。

先从低风险资源试起：固定 Provider 版本、备份 State、写配置、导入，再看 Plan。若它要重建整个数据库，先查资源地址和不可变字段，不要用 -target 或 ignore_changes 掩盖没看懂的差异。

例如导入数据库前，先记下云端 ID、账户、区域和规格，确定最终的配置地址。导入后重点看存储类型、备份窗口、删除保护和网络规则。控制台创建时使用的默认值，未必和 Provider 当前的默认值相同，Plan 上一行小差异也可能触发重启。

第一次 Apply 最好留出维护窗口。即便 Plan 显示原位更新，参数变化仍可能中断服务。和业务负责人确认变更、监控与恢复办法，稳定后再批量接管同类资源。

四、一个能长期维护的项目怎样组织

起步时，一个目录、一份 State 就够了。环境多起来，再抽出共享 Module，由各环境的 Root Module 传入参数：

infra/
├── modules/
│   ├── network/
│   └── service/
├── environments/
│   ├── dev/
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   └── outputs.tf
│   └── prod/
│       ├── main.tf
│       ├── variables.tf
│       └── outputs.tf
└── README.md

modules/network 定义 VPC、子网和必要的输出；environments/dev 与 environments/prod 分别填写区域、CIDR、标签、Backend Key 和模块版本。生产账号和 Provider 配置留在 Root Module。OpenTofu 的模块与 Provider 文档也按这种方式组织：子 Module 声明需要什么 Provider，调用者决定用哪个账户、哪个区域。

module "network" {
  source = "../../modules/network"

  environment = "prod"
  cidr_block  = "10.80.0.0/16"
}

module "service" {
  source = "../../modules/service"

  environment = "prod"
  subnet_ids  = module.network.private_subnet_ids
}

模块文档应写清输入、输出和资源归属。网络模块输出 private_subnet_ids，业务模块就不用靠标签猜子网。外部 Module 要固定版本：Registry Module 用 version，Git Module 用标签或 Commit，本地 Module 则跟随当前仓库提交。

Module 不是越多越好。只封装一个安全组端口、却要层层传参数的模块，排障时反而麻烦。适合抽出的，是有稳定接口、会复用或必须一起维护的资源。拆 Module 也不会拆 State，那要由 Root Module 和 Backend 决定。

State 应该怎么拆

一份 State 对应一轮 Plan/Apply。把网络、生产数据库和几十个应用放进去，应用维护者可能读到数据库的敏感属性，任何一个 Provider 出问题都可能拖住整轮计划。

拆得太细也麻烦：每份 State 都需要 Backend、锁、备份和运行入口。跨 State 读取 terraform_remote_state 看似方便，却意味着下游能读取上游整份 State，其中可能有敏感内容。只需少数非敏感 ID 时，可以发布到参数存储、DNS 或内部服务目录。

划分时先看生命周期和权限：组织级身份、网络、数据层、应用层往往不该共用一份 State。共享 Module 说明怎么建，Root Module 决定由谁在什么环境建。

五、从 Terraform 迁移：兼容性到底到哪一步

OpenTofu 的迁移文档指出，多数现有配置无需修改。这个结论适合拿来启动试验，不能代替试验：.tf 文件能解析，不代表 Plan 相同，更不代表原来的运行平台也能照搬。

迁移对象至少有五层：

尤其要查第三方 Provider。有些维护者同时测试两个 CLI，有些没有。列出实际使用的版本和来源，再对重要资源比较 Plan。

一个保守的迁移顺序

挑一份边界清楚、近期没有生产变更的 Root Module。记录 Terraform 版本、锁文件、Backend 和当前 Plan，再备份 State。S3 开启版本控制还不够，至少试一次能否找到并读出指定的旧版本。

固定 OpenTofu 版本后，在冻结的配置上初始化并运行 Plan。先核对 State Key、Workspace、云账户和区域；读错 State 时，计划可能把现有资源全当成待创建对象。

# 迁移前，使用原工具确认基线
terraform version
terraform init
terraform plan
terraform state pull > state-before-tofu.json

# 对已冻结的同一目录试运行 OpenTofu
tofu version
tofu init -reconfigure
tofu providers
tofu validate
tofu plan -detailed-exitcode

state-before-tofu.json 可能含有密码，不能提交到 Git 或普通 CI Artifact。实际备份应放到受控的加密存储。-reconfigure 只是重新确认 Backend 配置，不负责迁移 State。切换时暂停旧流水线，保证同一份 State 只有一个写入者。

Plan 没有意外差异，再做一项小变更，Apply 后重跑 Plan。确认闭环走通，才切换其余环境。已经用 OpenTofu 写过 State 后，单纯换回 Terraform 二进制不一定能回滚，要把备份与切换期间的云端变更一起核对。

迁移 PR 只改工具和流水线，记录锁文件变化。资源重命名、Provider 升级和新功能留到后续变更，否则一份有几十项差异的 Plan 很难判断问题来自哪里。

每迁完一份 State，就记录当前负责写入的工具和流水线，别让旧任务在切换后又跑起来。

多个 Root Module 相互读取时，顺序很要紧

假设 database 通过 terraform_remote_state 读取 network 的子网 ID。如果先让 network 写入新格式或加密的 State，仍由 Terraform 运行的 database 可能读不到。OpenTofu 的跨配置迁移指南建议先迁依赖方，再迁被依赖方。这样新的读取方先验证旧 State，最后再切换上游写入者。

目录名看不出全部依赖，迁移前要查 State 的实际读写方。迁移期间保持双方都能理解的配置与 State 格式，所有消费者切换后，再启用加密和 .tofu 文件等功能。

六、OpenTofu 比 Terraform 多了什么

Fork 之后，两边一直在更新。下面几项是 OpenTofu 后来加入的能力，各有用途和维护负担。

State Encryption：保护存储介质被读取的场景

State 可能保存密码和连接串。把输出标为 sensitive，只会减少 CLI 展示，原值仍可能在 State 里。OpenTofu 从 1.7 起支持原生 State 与 Plan Encryption：内容写入本地文件或 Backend 前就已加密。

S3 服务端加密与此保护的环节不同：有权限读取 S3 对象的客户端仍能得到明文；启用 OpenTofu 原生加密后，Backend 保存的是密文。但这也意味着恢复 State 必须找得到密钥，密钥丢失可能让备份无法使用。

下面用 Passphrase 展示配置形式。实际生产环境通常更适合由受管 KMS 提供密钥，并按 State 划分权限。

variable "state_passphrase" {
  type      = string
  sensitive = true
  ephemeral = true
}

terraform {
  encryption {
    key_provider "pbkdf2" "state" {
      passphrase = var.state_passphrase
    }

    method "aes_gcm" "state" {
      keys = key_provider.pbkdf2.state
    }

    state {
      method   = method.aes_gcm.state
      enforced = true
    }

    plan {
      method   = method.aes_gcm.state
      enforced = true
    }
  }
}

Passphrase 应由运行环境注入，不写入 HCL、Git 或日志。sensitive 控制展示，ephemeral 避免这个输入进入 State 或 Plan；运行时身份和取密钥的路径仍需保护。

已有明文 State 不能直接套用这份示例配置。官方文档给出了用 method "unencrypted" 和 fallback 过渡的步骤：先备份旧 State，让新配置暂时能读取明文，写出密文后确认各读取方都能解密，最后去掉 fallback 并启用 enforced。迁移期间暂停其他写入者；若下游通过 terraform_remote_state 读取，也要同步迁移。

恢复演练要同时验证 State 备份和解密权限。备用 Runner 即使拿到了历史版本，若事故时无法调用 KMS，备份仍然用不上。

轮换密钥时，旧方法要留到历史 State 不再需要它。记录每把旧密钥保护了哪些版本，何时可以退役；太早删除，历史备份可能再也打不开。

若把 Plan 存到 CI Artifact，也要检查其保留期及是否加密。自动化平台读取 tofu show -json 后得到的是解密内容，不能随手写入日志。

原生加密主要降低 State 文件泄露时的风险。有 Apply 权限的人仍可能从输出、Provider 日志或云 API 取得敏感信息，Backend 的权限、版本控制和备份不能省。

早期变量求值：减少环境配置重复

Backend 地址和 Module 来源要在初始化时确定，以前很多地方只能写静态值。OpenTofu 1.8 的早期变量求值允许这些位置引用符合限制的变量和 Local 值。

例如多个环境使用同一个私有模块仓库，可把版本号集中到一个 Local：

locals {
  module_ref = "v2.4.1"
}

module "network" {
  source = "git::https://github.com/example/infra-modules.git//network?ref=${local.module_ref}"

  cidr_block = var.cidr_block
}

module_ref 必须在 tofu init 时就能算出，不能依赖资源 ID 或 State 输出。变量能用不代表来源应该动态漂移，生产应固定标签或 Commit。

同名 .tofu 与 .tf 文件并存时，OpenTofu 会优先读取 .tofu，Terraform 仍读 .tf。这能让同一 Module 分别适配两边，也意味着两份实现都要测试。只迁移执行工具时，没有必要马上分叉文件。

其他几项值得留意的变化

OpenTofu 1.9 支持 Provider for_each，配置多区域 Provider 时可以少写重复块。不过，多个区域若共用一份 State，仍要一起 Plan 和等待最慢的 API，语法变短并不会缩小变更范围。

1.11 加入 enabled 元参数，用来控制资源或 Module 是否存在。它省去了某些 count = var.enabled ? 1 : 0 写法，但关闭开关仍会产生删除计划。同版本的 Ephemeral Resource 和只写属性，则要看具体 Provider 是否支持，普通 data 源读取 Secret，不会自动避开 State。

1.12 允许 prevent_destroy 根据变量决定，方便让生产数据库默认禁止删除、临时环境显式关闭保护。但如果把资源块整个删掉，规则也可能随之消失，云侧删除保护、备份和审批仍是另一层保障。

七、把 tofu apply 放进流水线，先设计控制权

生产 Apply 放进 CI，至少能留下执行时间、代码版本和身份。CI 拿到的云权限也会直接影响事故范围，因此设计流水线时要先确定身份和审批边界。

外部 PR 可以做不需要云凭据的格式检查和 Validate。真实 Plan 要访问 State 与云 API，只应在可信分支和受限身份下运行。HCL 可以触发 Provider 下载、数据源请求和本地程序，不能因为只是 Plan 就不关注权限。

GitHub Actions 的最小骨架

下面只展示作业边界，云端角色及 OIDC (OpenID Connect) 信任策略需要另行配置。生产 Job 经 GitHub Environment 审批后获取短期身份，示例将 OpenTofu 版本固定为 1.12.6。

name: Infrastructure

on:
  pull_request:
    paths: ['infra/**', .github/workflows/infra.yml]
  push:
    branches: [main]
    paths: ['infra/**', .github/workflows/infra.yml]
  workflow_dispatch:

permissions:
  contents: read
  id-token: write

concurrency:
  group: infra-prod
  cancel-in-progress: false

jobs:
  check:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: infra/environments/prod
    steps:
      - uses: actions/checkout@v4
      - uses: opentofu/setup-opentofu@v1
        with:
          tofu_version: 1.12.6
      - run: tofu fmt -check -recursive
      - run: tofu init -backend=false
      - run: tofu validate

  apply:
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    needs: check
    runs-on: ubuntu-latest
    environment: production
    defaults:
      run:
        working-directory: infra/environments/prod
    steps:
      - uses: actions/checkout@v4
      - uses: opentofu/setup-opentofu@v1
        with:
          tofu_version: 1.12.6
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ vars.AWS_ROLE_ARN }}
          aws-region: ap-southeast-1
      - run: tofu init -input=false
      - run: tofu plan -input=false -out=apply.tfplan
      - run: tofu apply -input=false apply.tfplan

check 不连接 Backend，所以 PR 上不会显示真实资源差异。若必须在 PR 中看 Plan，需要另建只接受可信来源的作业，并给它足够读取 State 与资源的权限，生产写权限留给受保护的 Apply 作业。

示例的审批发生在 Plan 之前，适合审批「谁能启动生产作业」，不等于审查了资源变更。若审批人需要看具体动作，生产 Plan 应先生成摘要，待审查后再 Apply。

PR Plan 与合并后的生产 Plan 可能不同。审批后若重新计算，出现新差异就要重新审；若保存已审的计划直接执行，则要保护计划文件并检查是否过期。摘要可以按创建、更新、替换、删除排列，把数据库等高风险资源排在前面。

看 Plan 时，+ 是创建，~ 是原位更新，-/+ 是替换，- 是删除。数据库出现 -/+，需要先弄清停机和备份安排。Apply 成功后还要测数据库连接、DNS 和服务健康，基础设施执行成功，不等于业务已经可用。

concurrency 只能串行化这组 GitHub 作业，本地命令或其他 CI 仍可访问 State，所以 Backend 锁也必须启用。

GitLab CI 也按同一原则拆开

GitLab 用 resource_group 串行部署 Job，用受保护分支和环境限制生产发布。分层仍是：Merge Request 做无凭据检查，可信分支生成 Plan，受保护环境执行 Apply。共享 Runner 时还要确认项目之间不会互读凭据或缓存的计划文件。

配置 OIDC 后，实际从无权限分支试一次换取角色：它应该失败。只看策略文件，容易漏掉宽泛的仓库或分支匹配条件。

Plan 的退出码怎样处理

tofu plan -detailed-exitcode 返回 0 表示无变化，1 表示出错，2 表示有变更。CI 默认把非零码视为失败，脚本需要单独处理 2：

set +e
tofu plan -input=false -detailed-exitcode -no-color
plan_exit=$?
set -e

case "$plan_exit" in
  0) echo "No infrastructure changes" ;;
  2) echo "Infrastructure changes detected" ;;
  *) exit "$plan_exit" ;;
esac

PR 评论里该放什么

PR 评论只需展示资源动作和关键字段，完整的 tofu show -json 可能含敏感值，不应贴进评论或公开 Artifact。策略引擎可以读取它，检查公网暴露、备份和删除动作，但要限制结果流向。

生产作业要留下 Commit SHA、工具与 Provider 版本、State Key、计划摘要、执行身份和 Apply 结果。这样才能把审查内容与实际执行对上，同时避免记录完整 State 或密钥。

八、State 锁、备份与事故处理

两个人同时操作一份 State，可能都计划创建同一资源，还可能用过期数据写回结果。锁用来阻止并发写入；是否支持、如何实现取决于 Backend。

S3 Backend 可以使用原生锁文件或 DynamoDB 锁。示例中的 use_lockfile = true 会在 State 旁建立锁对象，运行身份需要相应权限。新项目通常用原生锁文件就够了，已有 DynamoDB 锁不必为此单独迁移。

版本控制能找回旧 State，却不能让云资源也跟着时光倒流。若旧版本之后又建了资源，直接回滚 State 会丢失这些映射。

锁一直占用时，先查持有者、时间和 CI 任务。确认原任务已停止，才考虑 tofu force-unlock，如果它还在写 State，强制解锁会制造真正的并发写入。

若锁冲突常态化，要看是不是太多不相关资源共用 State，或每个 PR 都对生产 Backend 跑长时间 Plan。调整 State 边界可能比不断增加重试更有效，但拆分本身需要单独迁移。

一次可用的备份不止是 JSON 文件：还需要解密密钥、读取身份、当时的配置和 Provider 锁文件。可以在隔离环境取出一个历史版本，确认能读出资源地址和输出，这比只检查桶里有多少版本更能说明问题。

真要恢复生产，先停所有写入者并保留事故后的当前 State。对照旧版本与云端资源，再决定回滚文件，还是用 import、state mv 修复具体映射。

执行失败后，本地还可能留下含敏感内容的恢复文件或 Plan。检查 Runner 的磁盘清理和 Artifact 规则，排障时别把完整 State 贴到日志或聊天窗口。

九、从 Registry 下载组件时要看什么

OpenTofu 的公共 Registry 能解析 source = "hashicorp/aws" 这样的地址。写起来方便，但引入组件时仍要知道发布者、来源和维护状况。

Provider 和 Module 不是同一种发布物

Provider 是可执行插件，能接触凭据并访问云 API；Module 是一组 HCL 配置。两者风险不同，都不由 OpenTofu 核心项目替第三方维护者背书。使用前要查对应版本的 Provider 文档。

先核对完整 Source 地址、维护仓库、许可证和版本历史。两个名字相似的组件可能来自不同发布者，Provider 还要看校验信息及目标架构有没有构建包。

.terraform.lock.hcl 记录选中的 Provider 和包校验信息，锁不住指向 Git 分支的 Module。公共 Module 用版本约束，Git Module 固定 Commit 或受保护的标签。Provider 和 Module 分开升级，出现 Plan 差异时才容易定位。

私有 Registry 怎样维护

内部 Module 可能固化了账户、网络和标签约定，不适合公开。团队可用支持 Module Registry 协议的私有服务，也可先从受限 Git 仓库发布。

例如内部模块可以约定：

module "service" {
  source  = "registry.example.internal/platform/service/aws"
  version = "2.4.1"

  name        = "billing"
  environment = "prod"
}

调用者只传服务名和环境，模块内部统一标签和网络规则。发布新版本时尤其要检查资源地址；地址变了，云端对象还在，Plan 也可能要删旧建新。这类改动应提供 moved 块或明确的迁移说明。

私有 Registry 还要管 CI 访问、Token 轮换和旧版本保留。若使用内部 Provider 镜像，也要保留来源与校验信息，不能只留下一个来历不明的二进制包。

和 Terraform Registry 的关系

省略主机名的 Provider 地址，由 OpenTofu 的默认 Registry registry.opentofu.org 解析；完整写出 registry.terraform.io 则另当别论。迁移时看 tofu providers 和 tofu init 的实际输出，确认下载来源。

同一个 Provider 在不同 Registry 的元数据或校验和可能不同步。对关键组件，在隔离环境记录初始化时选中的版本和校验和，再检查 Plan。

十、团队多了以后怎样分工

团队扩大后，要明确谁能改网络、谁负责数据库、谁有权恢复 State，并在账户、仓库和流水线中设置相应权限。

先分清谁有权限

开发、测试、生产使用不同云账户时，CI 身份也应只进入对应环境。这样即使有人把 environment 变量填错，云 IAM 仍能拦住一部分操作，生产身份不宜长期放在个人电脑上。

读取 Backend 与访问云资源涉及两套权限。若都交给同一个管理员角色，能跑 Plan 的人也可能拿到生产写权限。拆开 Plan、Apply、State 管理和解密权限后，要用真实 Plan 验证，因为数据源也会调用云 API。

共享网络、DNS 和身份资源可以由平台流水线写入；应用团队通过 Module 参数提出需求。State 边界、云身份和代码所有权最好大致对齐，否则审批人很难判断一次变更实际会碰到谁的资源。

把策略检查放在适当位置

静态 HCL 检查适合拦明文密钥和未固定的版本，不需要云凭据。Plan 级策略能看资源动作，适合检查公网暴露、加密和备份。云端组织策略则约束绕过 OpenTofu 的控制台操作。

规则要按环境表达清楚。测试环境可以有较短的日志保留期，生产环境可能要求更长，把差异和审批例外写进策略，比让使用者绕过规则更可控。

用 OPA 检查 tofu show -json 时，要拿真实 Plan 测试。属性若暂时未知，策略得明确是阻断、要求审批，还是 Apply 后审计。策略本身也要版本化，否则同一份配置隔天可能得到不同结论。

三类密钥分开处理

OpenTofu 运行所需的云身份与 State 解密密钥，尽量使用短期凭据。它为资源设置的数据库初始密码，可能被 Provider 写入 State，标为 sensitive 也未必能避免。应用运行时的 Secret 则通常无需经过 OpenTofu，应用可直接从密钥服务获取。

把三类密钥都塞进 terraform.tfvars，很容易在 Git、Plan、State 和 CI 日志留下副本。必须由 OpenTofu 设置的密码，先查 Provider 是否支持只写属性；不支持，就按 State 含敏感数据来设计权限和备份。

三类密钥的轮换也不同：State 加密密钥要兼顾历史版本，数据库密码要考虑应用连接，云身份则要保证运行中的任务能结束，分别安排窗口和回滚方法。

成本要进入审查，而不是月底看账单

一个 module 块背后可能建了三副本数据库、NAT 网关和长期日志存储。模块文档应写出默认规格与主要计费项，让创建者在 PR 阶段就能看见成本来源。估算工具有帮助，但算不准真实流量和折扣。

环境和团队标签有助于分摊费用，但不是每种资源都支持。共享服务尤其不能简单按环境数量平摊。

临时环境要有负责人和到期时间。PR 关闭后的清理 Job 可能失败，数据库和 NAT 网关仍在计费。定期按标签列出过期资源，再确认删除；到期标签不应直接触发无条件销毁，排障中的环境可能需要延期。

每月把估算与账单对一次。差距大时，应改模块默认规格或成本说明，否则 PR 里的估算很快就没人信了。

OpenTofu 测试该测什么

tofu fmt 检查格式，tofu validate 检查配置是否合法。tofu test 配合 Provider Mock，可以验证标签、删除保护等确定性规则。但这些检查都不能证明云端权限和配额足够。

关键模块还应在隔离账户实际创建、检查、销毁一次，并给测试账户设置成本与清理约束。昂贵资源难以频繁创建，至少保留真实 Plan 样本，比较升级前后的差异。

发布共享模块前，除了测新环境，还要对已有环境看升级 Plan。资源地址改了就提供 moved 块；需要手工迁移则写清步骤和回滚办法。空环境能 Apply，不代表旧环境不会重建 VPC。

十一、几个常见故障，按证据排查

tofu init 下载失败

报错发生在 init，也要分清卡在 Backend、Provider 还是 Module。前者多查凭据、区域和桶策略；Provider 下载查 Registry、版本、架构和校验和；Module 下载查 Git 凭据、标签或私有 Registry Token。

不要一报错就删 .terraform.lock.hcl。校验和不匹配，核对下载来源；版本约束无解，检查各 Module 的 required_providers。随手加 -upgrade 可能把生产 Provider 换成未验证的版本。

Plan 突然要重建大量资源

大批资源突然要重建，最先核对 Backend Bucket、Key、Workspace 以及 Provider 指向的账户和区域。确认读对 State、连对云，再查 Module 名称、资源地址、for_each Key 和 Provider 版本。

例如把 aws_subnet.main[0] 改成 aws_subnet.main["a"]，云上子网没变，配置地址却变了。若确实是同一个对象，用 moved 块说明迁移；模块对外功能没变，也不代表内部资源地址没变。

锁被占用，没人承认在运行

看锁信息里的持有者、操作类型和时间，再对照 CI 任务。云 API 慢或 Runner 失联，都可能让锁晚些释放。原任务若已结束而 State 仍不可写，应查 Backend 权限和锁对象状态，不要连续强制解锁。

确实需要 force-unlock 时，先确认前一个写入者已经停止，并记下 State Key、锁 ID 和操作人。

State 能读，Plan 却无法解密

启用加密后无法解密 State，核对 Key Provider 配置、KMS 权限和密钥版本。Passphrase 改了、KMS Key 被禁用或 CI 漏传变量，都可能造成这种错误。不要把尝试过的密钥写进调试日志。

若刚迁移明文 State，还要查下游的 terraform_remote_state 是否拿到了新密钥。调整解密配置前，备份当前 State 并暂停并行 Apply。

Apply 部分成功，重试又报资源已存在

先对照 State 里的记录与云端对象 ID。API 创建成功、写 State 前进程崩溃，可能需要导入；State 已记录但云端暂时读不到，也可能只需等待。对象若已经存有业务数据，不能靠删除云资源或 state rm 来清掉报错。

一次性业务动作更棘手，例如创建管理员账号或执行数据库初始化。把这些动作塞进 local-exec，Plan 无法准确预告副作用，失败后也难以安全重试。它们更适合交给专门的迁移或工作流工具。

Destroy 结束后账单还在增长

检查共享资源、快照、备份、EIP 和日志存储。OpenTofu 只删除当前 State 管理的对象；人工创建或由其他 State 管理的资源，不在本次 Destroy 里。

删除保护或云端限制可能让销毁只完成一部分，没删成的对象通常仍留在 State 中。state rm 只是放弃管理，云端对象和账单不会消失。

十二、怎样决定现在要不要迁移

许可证是否影响自己的产品？现在是否依赖 HCP Terraform 的远程执行、策略和审计？谁来维护替代流程？这三个问题，比逐项比较新功能更能决定要不要迁移。OpenTofu 的核心代码开源，也能沿用许多 HCL 和 Provider，它不会自动接管原平台的工作。

个人开发者和小团队

新项目若要求核心工具开源，可以从一个低成本环境试 OpenTofu：独立云账户、远程 State、固定版本、PR 上审查 Plan。已有 Terraform 项目运行稳定，就先试迁一份非关键配置。若几个月才建一台虚拟机，维护 State 与流程的成本可能比手工操作还高。

已有大规模 Terraform 基础设施的企业

先盘点 Root Module、State 读写关系、Provider 和运行平台。试点要选真实业务中的一条流程，从 PR 审查走到 Apply、漂移检测和 State 恢复。空目录里跑通 tofu init，说明不了现有团队能否完成迁移。

深度使用 HCP Terraform/Terraform Enterprise 时，工作量大的往往是平台迁移：执行队列、私有 Registry、审批、变量和审计都要找新落点。旧平台中的运行记录也要提前安排保留或导出。

分批切换时，每份 State 都要有唯一写入者，迁完就关闭旧流水线。若要求随时切回 Terraform，必须限制 OpenTofu 专有语法和 State 特性，并持续在两边测试。

自建平台和软件供应商

托管或嵌入 IaC 的产品，要同时评估许可证和多租户执行风险。客户的 State、密钥、Runner、网络和 Provider 缓存必须隔离；用户提交的 HCL 还可能触发下载和本地程序。试点应拿客户实际使用的 State、Module 和 API 流程来验证。

换平台时，数据能带走吗

选型时可以做个反向演练：若半年后要换平台，能否导出 State，找回 Module 和 Provider，取得密钥，在另一台 Runner 上重现 Plan？卡住的地方，就是实际的迁移成本。再问一句谁来值班；开源代码和商业支持各有价值，前提是团队有人能把故障处理完。

十三、升级策略比首次安装更重要

首次 Apply 之后，还要持续升级。CLI、Provider、Module 和 Backend 一起变，Plan 出现差异就很难定位。分别安排变更：先升级 CLI，看同版本 Provider 下的 Plan；再升级 Provider；最后升级共享 Module。State 格式或锁文件若变化，要通知下游读取者。

生产流水线不要用 latest。本地、PR 和生产尽量使用同一个经过验证的 CLI 版本；Provider 在 required_providers 中限定范围，并提交记录实际版本的 .terraform.lock.hcl。锁文件变化也要审查。

升级前读发布说明，尤其留意默认值、废弃参数和资源 ID 处理的变化。关键模块应在隔离账户比较升级前后的 Plan。若使用 State 副本，它可能含敏感数据，也绝不能让测试作业拿着副本去写生产 Backend。

升级后若突然计划替换资源，先别用 -target 绕过去。比较旧版本 Plan、Provider 行为和云端现状，找出差异来源。一次没有资源变更的升级，也是一项值得确认的结果。

若决定暂缓升级，也记下原因和复查日期。例如新版 Provider 会改写数据库参数，维护者不能几个月后只看见一个旧锁文件，便随手运行 tofu init -upgrade。

运行手册写清 Backend Key、云账户、State 历史版本、解锁审批和密钥恢复联系人。这些团队内部的信息，半年后接班的人没法靠搜索引擎找回来。

测试和生产环境差在哪？配置进 Git、变更有 Plan 后，这个问题至少有了可以核对的答案。OpenTofu 提供工具，State、审批和恢复流程仍要由使用它的人负责。