terraform

Terraform / OpenTofu 运维

使用此技能安全地运行、检查和修复 Terraform 与 OpenTofu 基础设施：了解模块图，验证状态后端和锁定，应用前审查计划，查找并修复漂移，处理远程状态，规划版本升级和重构，并通过证据诊断故障。这是一项针对单个指定工具的工具技能（Terraform 与其直接兼容的 OpenTofu 分支共用一套 Agent 工作流和一个触发条件）。设计决策和 IaC 方法论属于 platform-engineering 及其 references/infrastructure-as-code.md；此技能负责执行。

操作约定

1. 先发现，再假设。 运行任何操作前，先阅读模块布局、提供程序要求、后端块、工作区、terraform.lock.hcl 和 CI 调用方式。切勿根据配置文件推断状态——状态文件才是已存在资源的事实来源。
2. 先规划，再审核后应用。 每项变更都必须经过可见的计划（或 tfops 试运行）和明确确认。切勿应用未经审核的变更。
3. 锁定并限定状态范围。 在修改状态前，确认后端支持锁定，且操作者持有锁。状态操作（state mv、state rm、state push）必须经过审核、限定范围并备份。
4. 在边界验证。 apply 成功并不能证明操作成功：验证资源原本应满足的外部边界（DNS、负载均衡器、API 响应），并在下次计划时检查漂移。
5. 证据范围要有限。 切勿将原始状态文件、后端凭据或提供程序密钥完整输出到聊天中。tfops 本身不会进行任何脱敏，但所有输出都应限制在摘要范围内。

tfops 脚本

scripts/tfops 是一个面向 Agent 的 Terraform/Tofu CLI 封装程序。即使没有 terraform 二进制文件，也可以使用 --help、doctor 和直接的 --state 分析，因此 Agent 可以在任何位置盘点状态文件。

scripts/tfops doctor --json                 # binary, config, backend, state availability
scripts/tfops state --state state.json --json   # inspect a local state file directly
scripts/tfops plan --state state.json --json    # state-level plan summary (no binary needed)
scripts/tfops plan --json                   # full plan via terraform plan -json
scripts/tfops apply --dry-run --json        # preview only, never mutates
scripts/tfops plan --save-plan reviewed.tfplan --json
# Review reviewed.tfplan, then apply that same file
scripts/tfops apply --yes --plan reviewed.tfplan --json
scripts/tfops apply --yes --plan reviewed.tfplan --force --json  # bypass findings only after review
scripts/tfops import aws_instance.web i-0abc --dry-run

变更门控：apply 和 import 必须带 --yes 才能运行（退出码为 2）。apply 还要求计划通过 tfops plan --save-plan FILE 创建；该命令会明确启用提供程序刷新并写入 SHA-256 伴随文件。tfops 会验证伴随文件，将已审核的计划复制到私有临时快照上，在该快照上运行 terraform show -json，检查格式和成功证据，并在存在先前状态时验证该状态；默认情况下会阻止已污损的资源和检测到的漂移，并应用同一快照。受支持的计划 JSON 格式可以省略空的变更集合；errored 必须为 false，而当引擎报告 applyable/complete 时，它们必须为 true。--force 仅绕过有效计划证据中的问题；无法绕过缺失或无效的证据、缺少伴随文件、哈希不匹配，或未通过封装程序明确启用刷新的计划。伴随文件是用于避免意外混淆的本地来源凭据，并非加密签名。--dry-run 可预览操作而不进行变更。--state 摘要不能作为实时漂移证据，也不能满足 apply 门控。TERRAFORM 环境变量会覆盖二进制文件选择（否则将自动检测 terraform，再检测 tofu）。退出码：0 表示成功，1 表示分析/运行时错误，2 表示门控拒绝，127 表示缺少二进制文件，124 表示超时。

操作流程

1. 盘点：模块树、提供程序要求、后端配置、工作区、锁定文件、状态 serial/lineage。
2. 分析：运行 terraform validate、tfops plan --json（或在无法连接后端时生成状态文件摘要）。
3. 审核：将计划视为资源差异进行阅读，而不是阅读一大段文本——统计创建/更新/销毁数量，检查替换（先销毁再创建），抽查敏感变更。
4. 应用：限定范围、确认操作并持有后端锁；之后验证边界。
5. 检查漂移：变更后及按计划重新规划；调查本不应存在的差异。

模块结构

• 每个组合单元使用一个模块：包含输入（变量）、输出和单一职责的资源。从根模块调用模块；保持根模块精简。
• 固定 provider（required_providers）和模块版本；提交 terraform.lock.hcl。
• 使用 for_each/count 实现重复，而不是生成代码；使用 templatefile 注入配置，并将 provisioner 作为最后手段。
• 结构约定和组合模式见 references/01-modules-and-structure.md。

状态后端与锁

• 后端负责状态存储和锁定。默认的 local 后端将状态存储在磁盘上；远程后端（S3+DynamoDB、GCS、Azure Storage、Terraform Cloud/OpenTofu Cloud、Consul）将状态保存在磁盘之外，并支持协作。
• 锁定可防止并发写入：执行 apply 和状态操作时，始终确认锁处于持有状态。陈旧的锁会阻止操作，直到锁被释放（只有确认没有其他运行任务处于活动状态后，才能使用 force-unlock）。
• 状态中包含机密：对后端启用静态加密，限制读取权限，并将敏感值标记为 sensitive = true。
• 后端选择、迁移（terraform init -migrate-state / -reconfigure）和锁故障排查：references/02-state-and-backends.md。

Plan/apply 工作流

• plan 会读取配置、状态和 provider 数据，并提出差异；apply 会落实这些变更。将 plan 输出视为 apply 将要履行的约定。
• 将销毁和替换视为风险最高的变更进行审查；在重新创建存在危险时，使用 prevent_destroy 和 create_before_destroy 生命周期规则。
• 仅在紧急情况下使用 -target，切勿将其作为惯例；仅在经过审查的 CI/CD 门禁中使用 -auto-approve。
• 完整工作流、JSON plan 输出（-json）和审查清单：references/03-plan-apply-workflow.md。

漂移检测

• 漂移是声明的配置与实际基础设施之间的差异。无变更的 plan 是漂移探测手段：定期执行 plan，并将意外差异视为事故。
• 区分预期漂移（带外手动更改、外部变更）与非预期漂移（配置/状态不同步、provider 错误）。
• 修复方式是执行 plan 并在审查后 apply（协调状态），或者在资源从未受管理时使用 import；切勿把删除并重新创建作为默认做法。
• tfops 会检查经过审查的保存计划中的 tainted 资源和 provider 检测到的漂移；除非有意使用 --force，否则发现问题时会拒绝操作，并应用该计划的原样内容。直接分析状态可以标记 taint，但无法确认实时漂移。方法和频率：references/04-drift-detection.md。

远程状态

• 远程后端使状态可共享、持久保存并可锁定；本地状态仅用于实验。
• 使用 data "terraform_remote_state" 获取其他 stack 的输出——按 workspace/environment 引用，切勿手动复制输出。
• 状态文件不是交付物：必须保护远程状态（加密、ACL、审计），并确保其可恢复（版本控制、备份、恢复演练）。实践指南：references/05-remote-state-and-collaboration.md。

升级与重构流程

• 升级：阅读对应版本跨度的升级指南，使用 terraform validate/tofu validate 验证，运行 plan，先在非生产环境中 apply，并使用 terraform state replace-provider / state mv 处理 provider 版本或地址变更。
• 重构：使用 moved 块重命名或重构资源（plan 安全，无需直接操作状态），或者在 moved 不适用时，审查后使用 state mv；切勿删除状态来强制重新创建。
• 版本与支持说明以及分步流程：references/06-upgrades-and-refactors.md。

诊断

按证据顺序进行诊断：二进制文件/版本 → 配置验证 → 后端与锁状态 → 状态 serial/lineage → 计划差异 → apply 错误 → 边界检查。

• 锁错误：执行任何 force-unlock 前，先找到持有锁的一方（因后端而异）。
• 状态 serial/lineage 不匹配：说明状态可能过期或来自其他环境；只有在备份并审查范围后，才能使用 state pull/state push。
• tfops doctor 会收集第一层证据；故障模式及其探测方法见 references/07-diagnostics.md。

参考资料索引

在以下情况下加载	参考资料
模块设计、组合或结构约定	references/01-modules-and-structure.md
后端选择、迁移或锁定问题	references/02-state-and-backends.md
规划、应用或审查变更	references/03-plan-apply-workflow.md
配置与实际情况存在意外差异	references/04-drift-detection.md
共享状态或跨栈状态	references/05-remote-state-and-collaboration.md
版本升级、提供程序迁移或模块重构	references/06-upgrades-and-refactors.md
apply、锁定或状态错误	references/07-diagnostics.md
来源、版本观察结果和刷新流程	references/00-source-index.md

包含的工件

• scripts/tfops：面向 Agent 的封装工具（状态分析、plan/apply、带门控的变更、JSON 输出）。
• tests/test_tfops.py + tests/fixtures/fixture-state.json：针对随附状态夹具运行的确定性测试。
• references/：八份按日期编写并按来源索引的参考资料，涵盖上述运维主题。

验证边界

声明	最低证据
配置有效	terraform validate（或 tofu validate）退出码为 0
状态可读取	tfops state --state FILE --json 能解析并列出状态清单
计划安全	已审查的计划差异，包含 create/update/destroy/replace 数量，且没有盲目应用标记为 tainted 的资源
apply 成功	apply 退出码为 0，并且该资源所服务的外部边界响应正常
无漂移	apply 后立即重新规划，且按声明的周期执行时，结果均无变更

硬性边界

• 切勿暴露状态文件、后端凭据、提供程序机密或 sensitive 输出值。
• 未通过变更门控（审查计划后使用 --yes，或收到明确的人工指令），切勿运行 apply、import、state push 或 force-unlock。
• 切勿仅为“修复”漂移而删除状态或资源——应进行协调或导入。
• 运行提供程序专用流程前，务必检查模块的 required_providers 和版本固定项。

不适用场景

• IaC 方法论、工具选择或云设计决策——转交给 platform-engineering。
• 深入了解云提供商（AWS/GCP/Azure 各项服务的具体操作）——提供商参考资料和平台模式位于 platform-engineering 下；本技能负责 Terraform/OpenTofu 工具本身。
• Ansible、Pulumi、CloudFormation 或 CDK——这些工具各有自己的运维约定；此处仅涉及 Terraform/OpenTofu。
• 从头设计新模块（组合、接口、版本策略）——从 platform-engineering 方法论入手，再使用本技能执行。