Terraform Mistakes: State, Modules, and the ‘One Big Plan’ Trap

Quickstart

If you only do a few things to avoid painful Terraform mistakes, do these. They reduce blast radius, increase safety, and make “plan” output trustworthy again.

Overview

Terraform mistakes usually aren’t “syntax mistakes.” They’re design mistakes that only show up after you scale: more engineers, more environments, more modules, more resources. The failure modes are predictable: state gets messy, module boundaries get fuzzy, and a single command tries to change the entire world.

Core concepts

Before we talk about fixes, you need three foundational ideas: what state really is, what modules are really for, and why “one big plan” feels convenient right up until it doesn’t.

1) Terraform state: the truth Terraform uses

Terraform doesn’t “discover” your infrastructure from scratch each run. It tracks what it created in a state file, and uses that state to compute diffs. That’s why state is both powerful and dangerous: if state is wrong, the plan can be wrong.

2) Remote backends + locking: preventing “two people applied at once”

A remote backend centralizes state storage. Locking prevents two applies from running concurrently on the same state. Without locking, you can get conflicting updates, partial applies, and the classic “Terraform is haunted” feeling.

3) Modules: reusable building blocks with stable interfaces

Modules are best used to enforce consistency: naming, tagging, network rules, IAM patterns, and “known good” defaults. They’re worst used as “everything in one module” or as copy-paste folders that diverge immediately.

4) The “one big plan” trap: why monolith stacks fail at scale

The trap looks like this: you start with one repo and one root module. It’s fast. It’s simple. Then you add environments, shared resources, multiple teams, and many modules. Suddenly: every plan is huge, every apply takes forever, and you can’t change one app without touching ten others.

Step-by-step

This is a practical guide to escape fragile Terraform setups. You can apply it whether you’re starting fresh or refactoring an existing monolith. The goal is repeatability: small plans, safe applies, clear ownership.

Step 1 — Choose your state boundaries (stacks)

Start by splitting your infrastructure into “deployment units” that can change independently. The best boundaries often match ownership and failure domains, not cloud services.

Step 2 — Set up remote state + locking

Remote state is table stakes for collaboration. Locking prevents concurrent applies. Access control keeps state safe. Here’s an example backend configuration for an AWS-style setup (adapt it to your cloud and backend choice).

terraform {
  required_version = ">= 1.6.0"

  backend "s3" {
    bucket         = "acme-terraform-state"
    key            = "prod/networking/terraform.tfstate"
    region         = "eu-central-1"
    dynamodb_table = "acme-terraform-locks"
    encrypt        = true
  }
}

provider "aws" {
  region = "eu-central-1"

  default_tags {
    tags = {
      managed_by = "terraform"
      env        = "prod"
    }
  }
}

Step 3 — Design modules like products (inputs/outputs as a contract)

A module should hide internal resource naming and expose a stable API. The easiest way to enforce this is to keep the module’s variable list small, name inputs after business intent, and export only what downstream stacks need.

# modules/app_service/main.tf (sketch)
variable "name" {
  type        = string
  description = "Service name used for naming and tagging."
}

variable "env" {
  type        = string
  description = "Environment (dev/stage/prod)."
}

variable "subnet_ids" {
  type        = list(string)
  description = "Where the service runs."
}

variable "image" {
  type        = string
  description = "Container image (immutable tag or digest preferred)."
}

# ...resources go here...
# - compute (ECS/EKS/VM)
# - security group rules
# - autoscaling
# - alarms

output "service_url" {
  description = "Public URL or internal endpoint for consumers."
  value       = "https://example.invalid/${var.name}"
}

# root stack usage (apps/payments/main.tf)
module "payments" {
  source = "../../modules/app_service"

  name       = "payments"
  env        = "prod"
  subnet_ids = data.terraform_remote_state.networking.outputs.private_subnet_ids
  image      = "registry.example.com/payments@sha256:deadbeef..."
}

Step 4 — Build a repeatable plan/apply workflow (human + CI)

The safest Terraform workflow is: format, validate, plan, review, apply the exact reviewed plan. This reduces “works on my machine” differences and prevents applying a different plan than the one approved.

name: terraform

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

jobs:
  plan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4

      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: 1.7.5

      - name: Format + validate
        run: |
          terraform fmt -check -recursive
          terraform init -input=false
          terraform validate

      - name: Plan (no apply on PR)
        run: |
          terraform plan -input=false -no-color -out=tfplan

  apply:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    needs: [ plan ]
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: 1.7.5

      - name: Apply (main only)
        run: |
          terraform init -input=false
          terraform apply -input=false -auto-approve tfplan

Step 5 — Refactor safely: move state, don’t recreate resources

Refactors are where teams accidentally destroy production. The key idea: when you change a resource’s address (module path, name, for_each key), Terraform may think it’s a new resource. Use state move operations to preserve identity.

Common mistakes

These are the patterns behind “Terraform is scary.” Each mistake includes a fix you can apply without rewriting your entire codebase.

FAQ

Should I use Terraform workspaces for environments?

Workspaces can work, but they’re easy to misuse. They share the same configuration and differ only by state. For many teams, separate folders/stacks per environment (with separate state keys) is clearer and reduces accidental cross-env applies. If you do use workspaces, enforce them in CI and never “guess” which workspace you’re in.

What’s the best way to structure Terraform state for a growing cloud?

Favor multiple small states (“stacks”) over one giant state. A common structure is foundation, networking, platform, and per-service app stacks. Each state should have a clear owner, a clear apply process, and a limited blast radius.

How do I share outputs between stacks without creating tight coupling?

Share only stable, foundational outputs (subnet IDs, cluster endpoints, core DNS zones) and keep them versioned and documented. Avoid sharing internals (resource names, full policy docs) unless you truly want consumers to depend on them. If many stacks need the same data, that’s a hint it belongs in a foundation/platform layer.

Why does Terraform want to replace a resource after a refactor?

Terraform tracks identity by resource address (module path + resource name + keys). If that address changes, Terraform may treat it as a new resource. The fix is to refactor in steps and move state so Terraform understands it’s the same underlying cloud object.

Is it okay to run Terraform apply from a developer laptop?

For low-stakes dev stacks: sometimes. For shared staging/prod: it’s risky. CI-based applies give you consistent versions, consistent environment variables, audit trails, and approval gates. If laptops are involved, set strict rules: pinned versions, remote state, and mandatory plan review.

How do I avoid the “one big plan” trap in a mono-repo?

A mono-repo is fine; the trap is one root module/state controlling everything. Keep separate stacks inside the repo (separate backends/state keys), and run CI per stack based on changed paths. You get the code-sharing benefits of a mono-repo without the blast radius of a monolith state.

Cheatsheet

A scan-fast checklist to avoid the most common Terraform mistakes (state, modules, and big plans).

Wrap-up

Most Terraform pain isn’t “Terraform being hard.” It’s predictable consequences of three design choices: fragile state handling, unclear module boundaries, and the temptation to run one giant plan for everything.

Once you build these habits, Terraform becomes what it should be: a reliable tool for controlled change. And your future self won’t fear the plan output.

Related posts

• Cloud Cost Optimization: 15 Leaks You Can Fix This Month
• Serverless Done Right: When Functions Beat Containers
• Cloud Networking Basics: VPCs, Subnets, NAT, and Security Groups
• Test Your Infrastructure: Policy-as-Code and Guardrails
• Docker for Developers: Images, Layers, and Caching Explained
• Kubernetes Without Tears: Pods, Services, Ingress in One Story