terraform-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Terraform Best Practices

Terraform 最佳实践

Expert guidance for building production-grade Terraform infrastructure with enterprise patterns for module design, state management, security, testing, and multi-environment deployments.

本文提供构建生产级Terraform基础设施的专业指导，涵盖模块设计、状态管理、安全、测试和多环境部署的企业级实践模式。

When to Use This Skill

何时使用本技能

Writing reusable Terraform modules for teams or organizations
Setting up secure remote state management and backend configuration
Designing multi-environment infrastructure (dev/staging/prod)
Implementing infrastructure CI/CD pipelines with automated validation
Managing infrastructure at scale across multiple teams or projects
Migrating from manual infrastructure to infrastructure-as-code
Refactoring existing Terraform for better maintainability
Implementing security best practices for infrastructure code

为团队或组织编写可复用的Terraform模块
配置安全的远程状态管理与后端设置
设计多环境基础设施（开发/预发布/生产）
实现带自动验证的基础设施CI/CD流水线
跨多个团队或项目大规模管理基础设施
从手动基础设施迁移至基础设施即代码
重构现有Terraform代码以提升可维护性
为基础设施代码实施安全最佳实践

Core Concepts

核心概念

Module Design Philosophy

模块设计理念

Composition over monoliths: Break infrastructure into reusable child modules
Standard structure: main.tf, variables.tf, outputs.tf, versions.tf, README.md
Type constraints: Use validation blocks and complex types for safety
Dynamic blocks: Enable flexible configuration without duplication

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

State Management Principles

状态管理原则

Remote backends: S3+DynamoDB or Terraform Cloud for team collaboration
State encryption: KMS encryption at rest and in transit (mandatory)
State locking: Prevent concurrent modifications with DynamoDB
Workspace strategy: Directory-based for production, workspaces for similar envs

远程后端：采用S3+DynamoDB或Terraform Cloud实现团队协作
状态加密：静态和传输过程中均需启用KMS加密（强制要求）
状态锁定：通过DynamoDB防止并发修改冲突
工作区策略：生产环境采用基于目录的隔离，相似环境使用工作区

Security Fundamentals

安全基础

Secret management: AWS Secrets Manager, HashiCorp Vault (never hardcode)
Least privilege: Separate IAM roles per environment
Security scanning: tfsec, Checkov, Terrascan in CI/CD
Resource tagging: Enable cost tracking, ownership, compliance

密钥管理：使用AWS Secrets Manager、HashiCorp Vault（绝对禁止硬编码）
最小权限：为每个环境配置独立的IAM角色
安全扫描：在CI/CD中集成tfsec、Checkov、Terrascan
资源打标：实现成本追踪、归属管理与合规审计

Testing & Validation

测试与验证

Pre-commit hooks: Format, validate, lint before commits
Plan review: Always save and review plans before apply
Automated testing: Terratest for critical infrastructure modules
Policy as code: OPA/Sentinel for compliance enforcement

提交前钩子：提交代码前先格式化、验证、检查语法
计划审核：执行apply前务必保存并审核计划
自动化测试：为关键基础设施模块编写Terratest测试
策略即代码：使用OPA/Sentinel实现合规性强制要求

Quick Reference

快速参考

Task	Load reference
Module structure, variables, outputs, dynamic blocks	`skills/terraform-best-practices/references/module-design.md`
Remote backends, state encryption, workspace strategies	`skills/terraform-best-practices/references/state-management.md`
Variable precedence, tfvars, Terragrunt DRY config	`skills/terraform-best-practices/references/environment-management.md`
Secrets, IAM, scanning tools, resource tagging	`skills/terraform-best-practices/references/security.md`
Pre-commit hooks, Terratest, policy as code	`skills/terraform-best-practices/references/testing-validation.md`
Comprehensive checklist for all areas	`skills/terraform-best-practices/references/best-practices-summary.md`

任务	参考文档路径
模块结构、变量、输出、动态块	`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`
提交前钩子、Terratest、策略即代码	`skills/terraform-best-practices/references/testing-validation.md`
全领域综合检查清单	`skills/terraform-best-practices/references/best-practices-summary.md`

Workflow

工作流程

1. Project Setup

1. 项目初始化

bash

undefined

bash

undefined

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

undefined

undefined

2. Module Development

2. 模块开发

bash

undefined

bash

undefined

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

undefined

undefined

3. Security Hardening

3. 安全加固

bash

undefined

bash

undefined

Mark sensitive variables

Use secret management for credentials

Configure state encryption

Set up security scanning in CI/CD

undefined

undefined

4. Testing Pipeline

4. 测试流水线

bash

undefined

bash

undefined

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

undefined

cd tests && go test -v

undefined

5. Deployment Process

5. 部署流程

bash

undefined

bash

undefined

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

undefined

terraform output

undefined

6. Multi-Environment Management

6. 多环境管理

bash

undefined

bash

undefined

Use directory-based isolation for production

cd environments/prod terraform init terraform workspace list

Or use Terragrunt for DRY backend config

terragrunt plan

undefined

terragrunt plan

undefined

Common Mistakes

常见错误

❌ Hardcoding secrets in code → Use secret management services ❌ No state locking → Enable DynamoDB locking to prevent conflicts ❌ Skipping plan review → Always save and review execution plans ❌ No version constraints → Pin provider and module versions ❌ Local state in teams → Use remote backends for collaboration ❌ No security scanning → Integrate tfsec/Checkov in CI/CD ❌ Missing resource tags → Tag all resources for cost/ownership tracking ❌ No automated testing → Write Terratest for critical modules ❌ Monolithic modules → Break into composable child modules ❌ No backup strategy → Enable S3 versioning on state buckets

❌ 在代码中硬编码密钥 → 使用密钥管理服务 ❌ 未启用状态锁定 → 启用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

官方文档: https://developer.hashicorp.com/terraform/docs
风格指南: https://developer.hashicorp.com/terraform/language/syntax/style
模块注册表: 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/
最佳实践: https://www.terraform-best-practices.com/
AWS Provider: https://registry.terraform.io/providers/hashicorp/aws/latest/docs