Terraform Best Practices: Lessons from Real-World Team Projects

Learning Terraform the Hard Way

I've made most of the Terraform mistakes so you don't have to. Corrupted state files at 2 AM, modules that nobody could understand, CI/CD pipelines that deployed to production when they shouldn't have.

These practices come from fixing those mistakes.

Project Structure That Scales

The Monolith Trap

Many teams start with everything in one file. This works until you have 50+ resources, then it becomes unmanageable.

Better: Environment Separation

terraform/
├── environments/
│   ├── dev/
│   ├── staging/
│   └── prod/
├── modules/
│   ├── networking/
│   ├── compute/
│   └── database/
└── global/
    ├── iam/
    └── dns/

Each environment has its own state file. Changes to dev can't accidentally affect prod.

Module Design

Good modules are:

Single purpose: One module, one job
Configurable: Expose what needs to vary
Documented: README with examples
Versioned: Tag releases

State Management

Remote State is Non-Negotiable

Local state files cause team conflicts, no locking, and no backup. Use remote backends like S3 with DynamoDB for AWS, or Azure Storage for Azure.

State File Security

Your state file contains sensitive data:

Enable encryption at rest
Restrict access to state bucket
Enable versioning for recovery
Never commit state to Git

Writing Better Terraform Code

Use Variables Wisely

Don't hardcode values. Use variables with descriptions, defaults, and validation rules.

Data Sources Over Hardcoding

Look up values dynamically instead of hardcoding AMI IDs or other values that change.

Meaningful Resource Names

"sg1" tells you nothing. "web_app_alb_security_group" tells you everything.

CI/CD for Terraform

Basic Pipeline

Validate and format check on all branches
Plan on pull requests
Apply on main with required approval

For teams using Azure DevOps, our [Azure DevOps Pipelines guide](/blog/azure-devops-pipelines-beginners-guide) walks through setting up the full CI/CD workflow with approval gates, environment deployments, and service connections for Azure.

Security Scanning

Add tfsec and Checkov to catch security issues before deployment.

Common Mistakes

1. Ignoring Drift

Run terraform plan regularly to detect manual changes.

2. Not Using Workspaces Correctly

Workspaces are for temporary variations, not environments.

3. Storing Secrets in Variables

Never put secrets in code. Fetch from secret managers at runtime.

4. Massive Blast Radius

If one terraform apply can break everything, split into smaller configurations.

Quick Reference: Team Guidelines

Guideline	Details
State	Remote backend, always encrypted
Formatting	Run terraform fmt before commit
Validation	CI must pass validate and plan
Reviews	All changes require PR review
Environments	Separate state per environment
Secrets	Never in code, use secret managers

Frequently Asked Questions

What are the most important Terraform best practices for teams?

The three highest-impact practices for team Terraform environments are remote state with locking (prevents concurrent apply conflicts), environment separation with separate state files per environment (dev, staging, prod), and mandatory PR review with a CI plan step before merge. These three practices together prevent the most common categories of production incidents in IaC-managed environments.

Why should Terraform state not be stored in Git?

Terraform state files contain sensitive data including resource IDs, IP addresses, connection strings, and any secrets that Terraform touched during provisioning. State files are JSON and are stored in plaintext unless encrypted separately. Committing state to Git exposes secrets in version history, creates merge conflict issues when multiple engineers apply simultaneously, and provides no locking mechanism to prevent concurrent state corruption.

What is Terraform state locking and why does it matter?

State locking prevents multiple Terraform processes from modifying the state file simultaneously, which would cause corruption. When using a remote backend like Azure Storage with blob leases or AWS S3 with DynamoDB locking, Terraform acquires a lock before any operation that modifies state and releases it when done. Without locking, two engineers running terraform apply at the same time can interleave writes and corrupt the state file, requiring manual recovery.

Should I use Terraform workspaces for environment separation?

Terraform workspaces are designed for temporary variations on the same configuration, not for permanent environment separation. Using workspaces for dev, staging, and prod environments is a common mistake: it shares a single backend configuration, makes it easy to accidentally apply against the wrong environment, and provides no access control separation between environments. The correct approach is separate directories with separate state backends per environment.

How do I handle secrets in Terraform without hardcoding them?

Never put secrets in Terraform variables, .tfvars files, or any file committed to version control. Use a secrets manager: in Azure, reference Key Vault secrets using a data source at runtime; in AWS, use Secrets Manager or Parameter Store data sources. For CI/CD pipelines, inject secrets as environment variables from your secrets management system (GitHub Actions secrets, Azure Key Vault references in Azure DevOps) rather than storing them in pipeline YAML files.