terraform

Terraform 和 OpenTofu

编写和审查可复现的基础设施，划定范围明确的状态边界，保护凭据，确保计划可供审查，并且每次 apply 都须经过明确的人工批准。资源参数和行为以已安装的运行时和锁定的提供程序架构为准。

特定版本的行为：更改锁定版本或依赖运行时功能前，请检查现有锁文件和提供程序文档。

适用场景

• 编写或审查 Terraform/OpenTofu 配置、模块、提供程序、状态或导入
• 设计后端、锁定、状态边界、OIDC、策略即代码或漂移检测方案
• 为受监管或 PCI 范围内的系统实施基础设施控制
• 审查生成的 HCL，检查安全性、正确性、替换行为和状态影响

不适用场景

• Kubernetes 清单或 Helm 图表；请使用 kubernetes
• 只读的 Kubernetes 健康检查；请使用 kubernetes-health
• VM 客户机配置；请使用 ansible 或 virtualization
• CI/CD 流水线架构；请使用 ci-cd
• 数据库架构、索引、复制或引擎运维；请使用 databases
• 应用安全审计；请使用 security-audit
• Proxmox VM/LXC 预配细节（bpg/proxmox 提供程序、模板、cloud-init）；请使用 virtualization——本技能负责通用 HCL/模块/状态工作

AI 自检

• 提供程序版本和资源参数与已安装的锁文件及当前提供程序文档一致
• 区域、账户 ID、CIDR、AMI 和凭据均为变量或发现的值，而非字面值
• IAM 遵循最小权限原则；宽泛的操作/资源和公开入站流量均为明确且有理由的例外
• 存储具备加密、访问控制、版本控制、日志记录，并明确设定公开访问策略
• 已审查后端加密、锁定、状态访问权限以及 sensitive 值的暴露情况
• 有状态资源具备明确的生命周期、备份、迁移和替换行为
• 提供程序/模块/操作版本均已锁定；已提交 .terraform.lock.hcl
• 在条件允许时，避免秘密值进入普通状态，并记录运行时交付路径
• 导入、移动、替换和销毁操作均在审查过的计划中清晰可见
• 不存在 provisioner 或已提交的真实值 tfvars；在支持的情况下，已设置标签/所有权信息
• terraform fmt 和 terraform validate 均通过；扫描和策略门禁符合代码库的策略
• 已落实跨领域的 Agent 卫生要求；相关时请阅读 references/agent-hygiene.md

秘密生命周期

追踪每项凭据从颁发者到 CI 身份、提供程序使用、状态和工作负载的完整路径。记录负责轮换和撤销的人员、租约时长以及应用重新加载路径。将 sensitive 视为显示脱敏，而非防止状态持久化的保护措施。在获批的测试环境中验证轮换和撤销，不打印任何值；运行时交付由 kubernetes 负责，流水线身份由 ci-cd 负责。

工作流

复制此清单并跟踪进度：

• 步骤 1：已确定范围（账户、后端、状态边界、秘密）
• 步骤 2：已阅读相关参考资料（执行任何状态命令前先阅读 state-and-security）
• 步骤 3：fmt、validate、tflint、checkov 对新增问题的检查均无发现（失败时，修复问题并返回步骤 3）
• 计划已与所有者审查；Agent 不得执行 apply

1. 确定范围

明确提供程序/账户边界、环境、资源依赖关系、后端和锁定设计、现有模块、合规范围以及秘密交付路径。对于现有系统，在引入新模式前，检查当前 HCL、.terraform.lock.hcl、后端、工作区/状态边界以及以往的计划惯例。

2. 查阅针对具体实现的指导

• 阅读 references/implementation-patterns.md，了解 Terraform 与 OpenTofu 的选择、HCL 结构、生命周期／临时值、导入／移动、S3 审查、模块结构、账户边界和扫描。
• 阅读 references/state-and-security.md，了解后端配置、加密、锁定、OIDC 或状态操作。执行任何会更改状态的命令前都要阅读此文档。
• 阅读 references/module-patterns.md，了解模块 API／测试或注册表的选择。
• 阅读 references/compliance.md，了解 PCI 控制、漂移检测、审计证据和受监管架构。生产交付前阅读 references/production-checklist.md。

3. 构建并验证，但不执行应用

从受影响的堆栈按顺序运行相关检查（OpenTofu 堆栈使用 tofu）。如果 fmt 或 validate 失败，或者 tflint／checkov 报告了本次更改引入的问题，请修复并从 fmt 重新运行；只有 validate 通过后才能执行 plan。对于既存的 tflint／checkov 问题，应如实报告，不要因此阻止 plan。语法检查通过并不意味着基础设施变更就是安全的：与负责人一起检查计划中的创建、变更、替换、导入和销毁操作。

terraform fmt -check -recursive
terraform validate
if command -v tflint >/dev/null; then tflint --recursive; else echo "tflint not installed: lint NOT run; report it as unverified"; fi
if command -v checkov >/dev/null; then checkov -d . --framework terraform; else echo "checkov not installed: policy scan NOT run; report it as unverified"; fi
terraform plan -out=plan.tfplan
if command -v conftest >/dev/null; then terraform show -json plan.tfplan | conftest test -; else echo "conftest not installed: policy gate NOT run; report it as unverified"; fi

报告已运行的检查、检查结果以及不可用的工具。plan、状态操作和策略门禁提供的证据各不相同。未经明确授权且未审查确切范围，不得运行 terraform apply、tofu apply、销毁、移除状态、强制解锁或在线迁移。

输出约定

完整约定请参阅 references/output-contract.md。

• 技能名称： TERRAFORM
• 交付物类别： audits
• 模式： 条件式。对于对现有内容的分析、审查、审计或改进，请遵循本地报告规则，并写入 docs/local/audits/terraform/<YYYY-MM-DD>-<slug>.md。构建或解释基础设施仍以对话方式进行。
• 严重级别： P0 | P1 | P2 | P3 | info

相关技能

• ansible - 配置置备后的环境
• kubernetes / kubernetes-health - 集群配置和只读集群诊断
• databases - 置备服务背后的数据库引擎操作
• ci-cd - 调用 Terraform 的流水线设计
• docker - 容器映像设计

规则

1. 固定提供商、模块和 CI 操作的版本。 提交依赖锁定文件。
2. 保护状态和密钥。 对状态进行加密、锁定、限制访问和审计；切勿提交凭据。
3. 遵循最小权限原则并明确生命周期控制。 不要掩盖破坏性替换。
4. 不要使用 provisioner。 使用声明式基础设施、用户数据或 ansible。
5. 隔离高风险／CDE 状态。 为其设置独立的后端、身份和审批边界。
6. 在支持的情况下，在 CI 中使用 OIDC。 将 plan 和 apply 身份分开，并严格限制权限范围。
7. AI 不负责执行 terraform apply。 人工审查具体计划、归档计划，并由人工授权变更。