AgentSkillsCN

terraform-best-practices

遵循Terraform基础设施即代码的最佳实践，打造可扩展且易于维护的云基础设施。适用于Terraform模块的编写、基础设施状态的管理，或大规模基础设施自动化的实施。

SKILL.md
--- frontmatter
name: terraform-best-practices
description: Terraform infrastructure-as-code best practices for scalable and maintainable cloud infrastructure. Use when writing Terraform modules, managing infrastructure state, or implementing infrastructure automation at scale.

Terraform Best Practices

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

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

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

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

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

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

Quick Reference

TaskLoad reference
Module structure, variables, outputs, dynamic blocksskills/terraform-best-practices/references/module-design.md
Remote backends, state encryption, workspace strategiesskills/terraform-best-practices/references/state-management.md
Variable precedence, tfvars, Terragrunt DRY configskills/terraform-best-practices/references/environment-management.md
Secrets, IAM, scanning tools, resource taggingskills/terraform-best-practices/references/security.md
Pre-commit hooks, Terratest, policy as codeskills/terraform-best-practices/references/testing-validation.md
Comprehensive checklist for all areasskills/terraform-best-practices/references/best-practices-summary.md

Workflow

1. Project Setup

bash
# 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. Module Development

bash
# 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. Security Hardening

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

4. Testing Pipeline

bash
# 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. Deployment Process

bash
# 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. Multi-Environment Management

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

# Or use Terragrunt for DRY backend config
terragrunt plan

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

Resources