Terraform Best Practices: The Definitive Guide

Why Terraform Best Practices Matter

Terraform has revolutionized how we manage infrastructure, allowing us to define it as code (IaC). However, moving from a simple `main.tf` file to managing complex, production-grade infrastructure for a team requires a disciplined approach. Adopting best practices isn't just about writing cleaner code; it's about ensuring your infrastructure is stable, secure, scalable, and maintainable. This guide breaks down the essential practices that separate hobbyist projects from professional, enterprise-ready deployments.

1. Project Structure: A Scalable Foundation

A well-organized project structure is the most critical first step. It provides clarity and makes it easier for team members to collaborate. Avoid putting everything in a single `main.tf` file. Instead, group resources logically by environment and component.

Environment-Based Layout

Isolating environments (e.g., `dev`, `staging`, `prod`) is crucial for preventing accidental changes to production. The most robust method is to use separate directories, each with its own state file.

├── environments/
│   ├── dev/
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   ├── backend.tf
│   │   └── terraform.tfvars
│   ├── staging/
│   │   ├── ...
│   └── prod/
│       ├── ...
├── modules/
│   ├── aws_vpc/
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   └── outputs.tf
│   └── aws_rds_instance/
│       ├── ...
└── data/
    └── ...

• environments/: Contains the root configuration for each environment. Each subdirectory is a self-contained Terraform project.
• modules/: Contains reusable, modular components (like a VPC or a database) that are called by the environment configurations.

2. State Management: The Single Source of Truth

Terraform uses a state file to map your configuration to real-world resources. By default, this file (`terraform.tfstate`) is created locally. This is fine for solo projects but is a major risk for teams.

Always Use Remote State

Remote state stores the state file in a shared location, like an AWS S3 bucket or Azure Blob Storage. This allows everyone on the team to access the same state file.

Enable State Locking

State locking prevents multiple people from running `terraform apply` at the same time, which could corrupt your state file. Services like AWS DynamoDB or HashiCorp Consul can be used for this.

terraform {
  backend "s3" {
    bucket         = "my-terraform-state-bucket-prod"
    key            = "global/s3/terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "terraform-state-lock-table"
    encrypt        = true
  }
}

3. Modules: Write Reusable, Composable Infrastructure

Modules are the cornerstone of writing scalable and maintainable Terraform code. A module is a container for multiple resources that are used together. Instead of copying and pasting your VPC configuration for every environment, you create a VPC module and call it.

Creating a Simple Module

variable "vpc_cidr" {
  description = "CIDR block for the VPC"
  type        = string
}

variable "project_name" {
  description = "Name of the project for tagging"
  type        = string
}

resource "aws_vpc" "main" {
  cidr_block = var.vpc_cidr

  tags = {
    Name    = "${var.project_name}-vpc"
    Project = var.project_name
  }
}

output "vpc_id" {
  value = aws_vpc.main.id
}

Calling the Module

module "my_vpc" {
  source = "../../modules/aws_vpc"

  vpc_cidr     = "10.0.0.0/16"
  project_name = "production-app"
}

4. Security: Handling Secrets and Policies

Never commit sensitive data like passwords, API keys, or certificates directly into your version control system.

Managing Secrets

Use a dedicated secrets management tool. You can fetch secrets at runtime using a data source.

data "aws_secretsmanager_secret_version" "db_creds" {
  secret_id = "prod/my-app/db-credentials"
}

locals {
  db_credentials = jsondecode(data.aws_secretsmanager_secret_version.db_creds.secret_string)
}

resource "aws_db_instance" "default" {
  # ... other configuration
  username = local.db_credentials.username
  password = local.db_credentials.password
}

Policy as Code

Use tools like HashiCorp Sentinel or Open Policy Agent (OPA) to enforce policies on your Terraform runs. For example, you can write a policy to prevent the creation of S3 buckets without encryption enabled.

5. CI/CD: Automating Your Workflow

A mature Terraform workflow is fully automated. Integrating Terraform into a CI/CD pipeline ensures that every change is automatically linted, validated, and planned before it is applied.

GitHub Actions Workflow for Terraform

This workflow triggers on a pull request, running `fmt`, `validate`, and `plan`. When the PR is merged to the `main` branch, it runs `apply`.

name: 'Terraform CI/CD'

on:
  push:
    branches: [ "main" ]
  pull_request:

jobs:
  terraform:
    name: 'Terraform'
    runs-on: ubuntu-latest
    env:
      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
      TF_WORKING_DIR: 'environments/prod'

    steps:
    - name: Checkout
      uses: actions/checkout@v4

    - name: Setup Terraform
      uses: hashicorp/setup-terraform@v3

    - name: Terraform Init
      run: terraform init
      working-directory: ${{ env.TF_WORKING_DIR }}

    - name: Terraform Validate
      run: terraform validate
      working-directory: ${{ env.TF_WORKING_DIR }}
      
    - name: Terraform Plan
      id: plan
      run: terraform plan -no-color -input=false
      working-directory: ${{ env.TF_WORKING_DIR }}
      if: github.event_name == 'pull_request'

    - name: Terraform Apply
      if: github.ref == 'refs/heads/main' && github.event_name == 'push'
      run: terraform apply -auto-approve -input=false
      working-directory: ${{ env.TF_WORKING_DIR }}
      

Terraform Best Practices Checklist

Next Steps