Terraform & OpenTofu

文件组织与命名规范

• 小写加下划线：如 web_api，而非 webAPI 或 web-api
• 使用具描述性的名词，且**不包含资源类型**：如 aws_instance.web_api，而非 aws_instance.web_api_instance
• 使用单数形式，而非复数
• 对模块内唯一实例的资源使用 this 命名（即每模块中该类型仅存在一个）
• 变量命名需体现上下文：如 vpc_cidr_block，而非 cidr

代码块顺序规范

资源定义（Resources）： count/for_each（其后空一行）→ 参数 → 嵌套块 → tags → depends_on → lifecycle（置于最后）

变量定义（Variables）： description → type → default → validation → nullable

每个变量必须声明 type 和 description；每个输出必须声明 description；敏感字段须显式标记 sensitive = true。

模块结构

module-name/
├── main.tf, variables.tf, outputs.tf, versions.tf
├── examples/
│   ├── minimal/
│   └── complete/
└── tests/
    └── defaults.tftest.hcl

保持模块轻量（单一职责原则）。examples/ 目录兼具文档说明与集成测试用例双重作用。所有对外发布的模块均须遵循语义化版本控制（Semantic Versioning）。

count 与 for_each 的选用

默认优先使用 for_each —— 若从 count 列表中移除中间某一项，会导致其后所有资源被销毁重建。仅在布尔条件判断或真正完全一致的副本场景下使用 count。

测试策略

原生测试关键要点（.tftest.hcl 文件置于 tests/ 目录下）：

• command = plan 用于快速单元测试；command = apply 用于集成测试（默认行为）
• assert { condition = expr; error_message = "..." } —— 每个 run 块中可定义多个断言
• expect_failures = [var.name] 支持负向测试（例如验证非法输入是否被正确拒绝）
• mock_provider "aws" { mock_resource "..." { defaults = { ... } } } —— 仅适用于 plan 模式，无需凭据，CI 构建速度快
• variables {} 可置于文件顶层（影响全部 run 块），也可置于单个 run 块内（覆盖全局变量）
• 引用前置 run 的输出：如 run.setup.vpc_id
• 独立状态的并行执行：设置 parallel = true，后续顺序执行将自动成为同步点
• 启用 parallel = true 时，必须为每个并行 run 显式指定 state_key = "name"
• 文件命名建议：*_unit_test.tftest.hcl（plan 模式） vs *_integration_test.tftest.hcl（apply 模式）

版本锁定策略

关键现代特性支持： moved 块（1.1+）、带默认值的 optional() 类型（1.3+）、原生测试框架（1.6+）、模拟 Provider（1.7+）、跨变量校验（1.9+）、只写参数（write-only arguments，1.11+）。 Stacks（HCP —— 请查阅当前发布状态）：将多个配置编排为统一部署单元 —— 建议评估其在多环境部署模式中的适用性。

状态管理与安全规范

• 必须使用支持锁机制的远程 Backend：如 S3+DynamoDB、Azure Blob、GCS 或 Terraform Cloud；共享基础设施严禁使用本地 state。
• State 文件须静态加密；禁止提交 .tfstate、.terraform/ 或 *.tfplan；必须提交 .terraform.lock.hcl。
• Provider 级别配置 default_tags，确保资源标签一致性。
• 所有存储服务须启用静态加密；网络默认私有化 —— 公网访问需显式开启并提供合理依据。
• 安全组遵循最小权限原则；禁止无明确理由的 0.0.0.0/0 入站规则。
• 禁止硬编码凭证 —— 应使用 assume_role、OIDC 或密钥管理服务（如 AWS Secrets Manager）。
• 提交前检查流程：先自动格式化（terraform fmt -recursive —— 直接重写文件），再校验（terraform validate && tflint && trivy config .）
• 重构资源或模块路径时，使用 moved { from = old; to = new } 避免销毁重建；该块在成功 apply 后应立即移除。

问题排查

• State 锁卡死：执行 terraform force-unlock —— 仅限确认无其他并发操作运行时使用
• 资源漂移（Drift）：使用 terraform plan -refresh-only 检测，terraform apply -refresh-only 接受变更
• 替换已标记为损坏（tainted）的资源：使用 terraform apply -replace=ADDR（terraform taint 已弃用）
• 导入已有资源：Terraform 1.5+ 支持 import 块实现声明式导入；亦可使用命令行方式 terraform import ADDR ID

依赖管理

使用 locals 结合 try() 函数控制销毁顺序，避免显式依赖 depends_on：

locals {
  vpc_id = try(aws_vpc_ipv4_cidr_block_association.this[0].vpc_id, aws_vpc.this.id, "")
}

该写法强制 Terraform 在销毁 CIDR 关联前先销毁子网，从而规避删除失败错误。

• 子网 CIDR 应通过计算生成：cidrsubnet(var.vpc_cidr, 8, count.index) —— **禁止硬编码子网地址**
• 多区域部署：通过 provider "aws" { alias = "eu_west_1" } 定义别名 Provider，并在模块调用中以 providers = { aws = aws.eu_west_1 } 显式指定

最终校验

在确认完成前，请务必执行以下命令：

terraform fmt -check && terraform validate && tflint && trivy config .

所有命令必须**零错误通过**。