Terraform — Production Guide
Complete Production Implementation Guide
Version: 1.8.x | Category: Infrastructure as Code | Level: Intermediate+
Terraform is the industry standard for infrastructure as code. This guide covers production patterns — state management, modules, workspaces, CI/CD integration, and advanced techniques used at scale.
Table of Contents
- Core Concepts
- Remote State — The Right Way
- Module Architecture
- Workspaces vs Directory Structure
- Production AWS VPC Example
- CI/CD Integration
- Testing Terraform
- Import & Refactoring
- Production Gotchas
- Essential Commands
1. Core Concepts {#concepts}
The Terraform Workflow
Write → Init → Plan → Apply → Destroy
- Write: HCL configuration files (
.tf) - Init: Download providers, configure backend
- Plan: Dry run — shows exactly what will change
- Apply: Execute the plan (creates/updates/destroys resources)
- Destroy: Remove all managed resources (careful!)
File Structure Convention
infrastructure/
├── modules/ # Reusable modules
│ ├── vpc/
│ │ ├── main.tf
│ │ ├── variables.tf
│ │ ├── outputs.tf
│ │ └── README.md
│ ├── eks/
│ └── rds/
├── environments/
│ ├── production/
│ │ ├── main.tf # Calls modules
│ │ ├── variables.tf
│ │ ├── terraform.tfvars # Env-specific values (gitignored for secrets)
│ │ ├── backend.tf # Remote state config
│ │ └── providers.tf
│ ├── staging/
│ └── development/
└── global/ # Cross-env resources (Route53, IAM roles)
├── main.tf
└── backend.tf
2. Remote State — The Right Way {#state}
Bootstrap State Backend (S3 + DynamoDB)
hcl
Backend Configuration
hcl
3. Module Architecture {#modules}
Writing a Reusable Module
hcl
hcl
hcl
Calling the Module
hcl
4. Workspaces vs Directory Structure {#workspaces}
Recommendation: Use Directory Structure (Not Workspaces)
Workspaces are confusing and risky for production. One accidental terraform workspace select production in the wrong directory is catastrophic. Instead:
# ✅ Good: Separate directories per environment
environments/
production/ → separate state file, separate apply, no risk of cross-contamination
staging/ → separate state file
development/ → separate state file
# ❌ Risky: Workspaces
# One directory, switching between workspaces
# Risk: apply prod state while thinking you're in staging
When Workspaces Are OK
Use workspaces only for truly identical environments (e.g., ephemeral preview environments per PR) where state contamination doesn't matter:
bash
5. Production AWS VPC Example {#vpc}
hcl
6. CI/CD Integration {#cicd}
GitHub Actions Pipeline
yaml
7. Testing Terraform {#testing}
bash
8. Import & Refactoring {#import}
bash
9. Production Gotchas {#gotchas}
| Gotcha | Impact | Fix |
|---|---|---|
| terraform destroy without -target | Destroys ALL managed resources | Always use -target for partial destroys |
| Provider version not pinned | Minor version update breaks resources | Always pin: version = "~> 5.0" |
| Storing secrets in .tfvars | Secrets committed to git | Use Vault, AWS Secrets Manager, or env vars |
| No prevent_destroy lifecycle | Accidental deletion of DBs, S3 buckets | Add lifecycle { prevent_destroy = true } to critical resources |
| Force-unlock without verification | Corrupts state if another plan is running | Verify no running plan before terraform force-unlock |
| Not using -out flag in CI | Apply may differ from plan if resources changed between plan and apply | Always: plan -out=tfplan, apply tfplan |
| count vs for_each for resources | Removing item from middle of count list destroys and recreates all after it | Use for_each with maps instead of count with lists |
| Hardcoded region | Breaks when deploying to another region | Use variables for all region-specific values |
| Large state files | Slow plans, hard to debug | Split into multiple state files per concern |
| terraform apply -auto-approve in production | No human review of changes | Always require manual approval for production |
10. Essential Commands {#commands}
bash