← All insightsIaC

Structuring Terraform for teams: state, modules and environments

Nir Geier, CodeWizard · 3 July 2025 · 3 min read · Intermediate

Terraform scales badly when everything lives in one state file: plans crawl, blast radius is huge, and two people can never work at once. The fix is structure - split state, extract modules, isolate environments.

Remote, locked state - per component

hcl
terraform {
  backend "s3" {
    bucket         = "acme-tfstate"
    key            = "prod/network/terraform.tfstate"
    region         = "eu-west-1"
    dynamodb_table = "tf-locks"   # state locking
  }
}

A layout that survives growth

bash
infra/
  modules/
    network/        # reusable, versioned building blocks
    service/
  envs/
    prod/
      network/      # thin root module -> calls modules/network
      service/
    staging/
        ...
  • One state per component per environment - small, fast, low blast radius
  • Pin module and provider versions; commit .terraform.lock.hcl
  • Review every plan in the PR; apply only from main
  • Scan with tfsec/Checkov before apply
If your terraform plan takes five minutes, your state is too big - not your infrastructure.

Small states, versioned modules and reviewed plans turn Terraform from a scary shared file into a calm, parallel workflow.

Like where this is going?

Get hands-on help from the engineers who write these posts.

Book a free consult