terraform-best-practices

Terraform Best Practices 是由 Terramate 维护的 Terraform 与基础设施即代码（Infrastructure as Code，IaC）综合优化指南，以技能形式提供。该技能包含 37 条规则，分布在 10 个类别中，并按影响程度划分优先级，用于指导自动化重构和代码生成。

适用时机

在以下场景中可参考这些指南：

• 编写新的 Terraform 模块或配置
• 实现基础设施模式（AWS、GCP、Azure 等）
• 审查代码中的安全性与可靠性问题
• 重构现有的 Terraform/OpenTofu 代码
• 优化状态管理与性能
• 建立团队工作流与治理规范

规则类别与优先级

规则按优先级分为多个类别，每个类别有对应的前缀标识：

1. 组织与工作流（CRITICAL，前缀 org-）
2. 状态管理（CRITICAL，前缀 state-）
3. 安全最佳实践（CRITICAL，前缀 security-）
4. 模块设计（HIGH，前缀 module-）
5. 资源组织（MEDIUM-HIGH，前缀 resource-）
6. 变量与输出模式（MEDIUM，前缀 variable-、output-）
7. 语言最佳实践（MEDIUM，前缀 language-）
8. Provider 配置（MEDIUM，前缀 provider-）
9. 性能优化（LOW-MEDIUM，前缀 perf-）
10. 测试与验证（LOW，前缀 test-）

快速参考

1. 组织与工作流（CRITICAL）— 5 条规则

• org-version-control：所有 Terraform 代码纳入版本控制
• org-workspaces：每个配置的每个环境使用一个工作区
• org-access-control：控制谁可以更改哪些基础设施
• org-change-workflow：为基础设施变更建立正式流程
• org-audit-logging：跟踪所有基础设施变更

2. 状态管理（CRITICAL）— 3 条规则

• state-remote-backend：始终使用远程状态后端
• state-locking：启用状态锁定以防止损坏
• state-import：将现有基础设施导入 Terraform

3. 安全最佳实践（CRITICAL）— 3 条规则

• security-no-hardcoded-secrets：绝不在代码中硬编码密钥
• security-credentials：使用适当的凭证管理（OIDC、Vault、IAM 角色）
• security-iam-least-privilege：遵循最小权限原则

4. 模块设计（HIGH）— 5 条规则

• module-single-responsibility：每个逻辑组件对应一个模块
• module-naming：使用一致的命名约定（terraform--）
• module-versioning：为所有模块引用指定版本
• module-composition：像积木一样组合模块
• module-registry：使用现有的社区/共享模块

5. 资源组织（MEDIUM-HIGH）— 5 条规则

• resource-naming：使用一致的命名约定
• resource-tagging：为所有资源打标签以便成本跟踪
• resource-lifecycle：使用 lifecycle 块（prevent_destroy、ignore_changes）
• resource-count-vs-foreach：优先使用 for_each 而非 count
• resource-immutable：优先采用不可变基础设施模式

6. 变量与输出模式（MEDIUM）— 6 条规则

• variable-types：使用具体类型、正向命名、nullable
• variable-validation：添加验证规则以便尽早发现错误
• variable-sensitive：将密钥标记为 sensitive，不设默认值
• variable-descriptions：为所有变量添加描述文档
• output-descriptions：为所有输出添加描述文档
• output-no-secrets：绝不直接输出密钥

7. 语言最佳实践（MEDIUM）— 5 条规则

• language-no-heredoc-json：使用 jsonencode/yamlencode，而非 HEREDOC
• language-locals：使用 locals 为复杂表达式命名
• language-linting：运行 terraform fmt 和 tflint
• language-data-sources：使用数据源而非硬编码
• language-dynamic-blocks：使用动态块实现 DRY 代码

8. Provider 配置（MEDIUM）— 1 条规则

• provider-version-constraints：固定 Provider 版本

9. 性能优化（LOW-MEDIUM）— 2 条规则

• perf-parallelism：为大型部署调整并行度
• perf-debug：启用调试日志以进行故障排查

10. 测试与验证（LOW）— 2 条规则

• test-strategies：测试金字塔（validate、lint、plan、集成）
• test-policy-as-code：实施策略检查（OPA、Checkov、tfsec）

如何使用

阅读各个规则文件以获取详细说明和代码示例，例如：

• rules/state-remote-backend.md
• rules/security-no-hardcoded-secrets.md
• rules/module-versioning.md

每个规则文件包含：

• 规则重要性的简要说明
• 错误代码示例及解释
• 正确代码示例及解释
• 额外背景与参考

完整汇编文档

如需包含所有规则展开内容的完整指南，请参阅 AGENTS.md。