terraform-best-practices

Terraform 最佳实践

关于构建生产级 Terraform 基础设施的专家指南，涵盖模块设计、状态管理、安全性、测试和多环境部署的企业级模式。

何时使用此技能

• 为团队或组织编写可复用的 Terraform 模块
• 设置安全的远程状态管理和后端配置
• 设计多环境基础设施（dev/staging/prod）
• 使用自动验证实现基础设施 CI/CD 流水线
• 在多个团队或项目中大规模管理基础设施
• 从手动管理基础设施迁移到基础设施即代码
• 重构现有 Terraform 以提高可维护性
• 为基础设施代码实施安全最佳实践

核心概念

模块设计理念

• 组合优于单体：将基础设施拆分为可复用的子模块
• 标准结构：main.tf、variables.tf、outputs.tf、versions.tf、README.md
• 类型约束：使用验证块和复杂类型来确保安全性
• 动态块：实现灵活配置，避免重复

状态管理原则

• 远程后端：使用 S3+DynamoDB 或 Terraform Cloud 进行团队协作
• 状态加密：静态和传输中的 KMS 加密（必须）
• 状态锁定：使用 DynamoDB 防止并发修改
• 工作区策略：生产环境使用基于目录的策略，相似环境使用工作区

安全基础

• 密钥管理：使用 AWS Secrets Manager、HashiCorp Vault（切勿硬编码密钥）
• 最小权限：为每个环境设置独立的 IAM 角色
• 安全扫描：在 CI/CD 中使用 tfsec、Checkov、Terrascan
• 资源标签：启用成本跟踪、所有权管理和合规管理

测试与验证

• Pre-commit 钩子：在提交前执行格式化、验证和 lint 检查
• 计划审查：始终保存并审查计划，然后再应用
• 自动化测试：使用 Terratest 测试关键基础设施模块
• 策略即代码：使用 OPA/Sentinel 强制执行合规要求

快速参考

任务	加载参考资料
模块结构、变量、输出、动态块	skills/terraform-best-practices/references/module-design.md
远程后端、状态加密、工作区策略	skills/terraform-best-practices/references/state-management.md
变量优先级、tfvars、Terragrunt DRY 配置	skills/terraform-best-practices/references/environment-management.md
密钥、IAM、扫描工具、资源标签	skills/terraform-best-practices/references/security.md
Pre-commit 钩子、Terratest、策略即代码	skills/terraform-best-practices/references/testing-validation.md
所有领域的综合检查清单	skills/terraform-best-practices/references/best-practices-summary.md

工作流

1. 项目设置

# Initialize directory structure
mkdir -p {modules,environments/{dev,staging,prod}}

# Set up remote backend (bootstrap S3 + DynamoDB first)
# Configure backend.tf with encryption and locking

2. 模块开发

# Create module with standard structure
cd modules/my-module
touch main.tf variables.tf outputs.tf versions.tf README.md

# Add validation to variables
# Use complex types for structured inputs
# Document outputs with descriptions

3. 安全加固

# Mark sensitive variables
# Use secret management for credentials
# Configure state encryption
# Set up security scanning in CI/CD

4. 测试流水线

# Install pre-commit hooks
pre-commit install

# Run validation locally
terraform init
terraform validate
terraform fmt -check

# Security scanning
tfsec .
checkov -d .

# Automated tests (critical modules)
cd tests && go test -v

5. 部署流程

# Plan with output file
terraform plan -out=tfplan

# Review plan thoroughly
terraform show tfplan

# Apply only after approval
terraform apply tfplan

# Verify deployment
terraform output

6. 多环境管理

# Use directory-based isolation for production
cd environments/prod
terraform init
terraform workspace list

# Or use Terragrunt for DRY backend config
terragrunt plan

常见错误

❌ 在代码中硬编码密钥 → 使用密钥管理服务 ❌ 未启用状态锁定 → 启用 DynamoDB 锁定以防止冲突 ❌ 跳过计划审查 → 始终保存并审查执行计划 ❌ 未设置版本约束 → 固定 provider 和模块版本 ❌ 团队使用本地状态 → 使用远程后端进行协作 ❌ 未进行安全扫描 → 在 CI/CD 中集成 tfsec/Checkov ❌ 缺少资源标签 → 为所有资源添加标签，以跟踪成本和所有权 ❌ 未进行自动化测试 → 为关键模块编写 Terratest ❌ 单体模块 → 拆分为可组合的子模块 ❌ 没有备份策略 → 为状态存储桶启用 S3 版本控制

Resources

• Official Docs: https://developer.hashicorp.com/terraform/docs
• Style Guide: https://developer.hashicorp.com/terraform/language/syntax/style
• Module Registry: https://registry.terraform.io/
• Terragrunt: https://terragrunt.gruntwork.io/
• Terratest: https://terratest.gruntwork.io/
• tfsec: https://aquasecurity.github.io/tfsec/
• Checkov: https://www.checkov.io/
• Best Practices: https://www.terraform-best-practices.com/
• AWS Provider: https://registry.terraform.io/providers/hashicorp/aws/latest/docs