1. Use Remote State with State Locking
"Local state is fine - until it isn't."
Storing Terraform state files locally is a recipe for drift and disaster when working in teams or automating with CI/CD. Always use remote state with locking mechanisms enabled.
Preferred setup:
Use Terraform Cloud, AWS S3 + DynamoDB, or Azure Storage + Blob Locking. Locking prevents race conditions in concurrent terraform apply executions. It also provides visibility and collaboration for teams.
Example (AWS):
terraform {
backend "s3" {
bucket = "my-tf-state"
key = "dev/network/terraform.tfstate"
region = "us-west-2"
dynamodb_table = "my-tf-locks"
encrypt = true
}
}
2. Modularize for Reusability and Consistency
"If you're copying and pasting Terraform code, you're doing it wrong."
Modules help reduce code duplication and make infrastructure reusable across environments or projects. I've created core modules for VPCs, security groups, IAM roles, and ECS clusters, then customized them via inputs.
Benefits:
- Faster provisioning.
- Enforces organizational standards.
- Easier onboarding for new engineers.
Structure tip:
modules/
vpc/
ecs/
iam/
environments/
dev/
prod/
Keep your modules clean and version-controlled. Avoid over-engineering; start simple and refactor as you scale.3. Use Workspaces or Explicit Folder-Based Separation
For smaller projects, Terraform workspaces can help manage multiple environments (e.g., dev, qa, prod) using the same code base. However, for complex setups, I prefer explicit directory separation.
Why folder-based separation often wins:
Easier CI/CD integration.
Less risk of accidental environment switches.
Better GitOps alignment.
Example structure:
live/
dev/
main.tf
prod/
main.tf
Combine this with strong naming conventions and tagging strategies to avoid resource confusion.
4. Enforce Code Quality and Policy-as-Code
Terraform lets you define infrastructure as code, so treat it like software.
Use tools like:
tflint and terraform fmt for style and syntax.
checkov or tfsec for security and compliance scanning.
Sentinel or OPA (Open Policy Agent) for policy-as-code.
Integrate these checks into your CI/CD pipelines to catch issues early.
Example GitHub Actions snippet:
- name: Terraform Format
run: terraform fmt -check -recursive - name: Run TFLint
run: tflint --recursive
- Tag Everything and Document Inputs/Outputs When you return to a Terraform project after 6 months, or when someone else does,tags and documentation save the day. Best practices: Use consistent tagging across all resources (owner, environment, project, cost center). Document module inputs and outputs with descriptions. Use terraform-docs to generate README files for module
Example:
variable "environment" {
description = "The environment to deploy (e.g. dev, prod)"
type = string
}
output "vpc_id" {
description = "The ID of the created VPC"
value = aws_vpc.main.id
}
Final Thoughts
These five practices; remote state, modularization, environment separation, code quality enforcement, and documentation, aren't just "nice to have." They're foundational. They've helped me avoid downtime, scale teams, and build resilient cloud platforms.
If you're starting out with Terraform, start with one or two of these and iterate. If you're already deep into IaC, consider how your current workflows align with these principles.
What are your top Terraform lessons from the field? I'd love to hear them.
Top comments (0)