The Terraform Mistakes I Made So You Do Not Have To

Source: Dev.to

I have been writing Terraform professionally for 4 years, and I have also been making Terraform mistakes for the same amount of time. Below are the mistakes that actually cost me time, money, or sleep, and what I learned from each.

Mistake 1: One Giant State File for Everything

When I started, putting everything in one state file felt elegant—one source of truth, simple to reason about.

Then a mistake in a single module made the entire state file unusable during apply. Two engineers tried to apply changes simultaneously and hit state‑lock conflicts. The state file grew to 50 MB, and plans started taking 8 minutes.

What I do now

Use one state file per service per environment. It adds a bit of setup overhead but is dramatically safer to operate.

Mistake 2: Storing Secrets in Variables

I know, obviously bad, but I still did it.

I was moving fast on a new project, needed to pass a database password to the application config, and thought I would fix it later. The password lived in a tfvars file for 8 months, and the file was committed to Git for 3 months before I noticed.

What I do now

Store secrets in AWS Secrets Manager or Parameter Store. Terraform reads the secret ARN, not the secret value.

Mistake 3: Using Terraform for Configuration Management

Terraform provisions infrastructure; it is not designed for configuration management.

I wrote Terraform resources to install packages, write config files, and manage services on EC2 instances using remote-exec and user_data. It worked until servers drifted because someone made a manual change. Terraform thought the configuration was correct, but the servers disagreed.

What I do now

Maintain a hard separation: Terraform provisions; Ansible (or another CM tool) configures. Never overlap the responsibilities.

Mistake 4: Ignoring the Blast Radius

Early in a project I had a root‑level module that managed VPC, subnets, security groups, RDS, ECS cluster, and application services all together.

A typo in the application service configuration caused Terraform to evaluate dependencies across everything. The plan showed changes to resources I didn’t expect to touch. I panicked, ran terraform apply -target, introduced more drift, and spent 4 hours fixing it, causing 20 minutes of unnecessary downtime.

What I do now

Create separate modules for infrastructure layers with explicit interfaces between them. Changes to application config cannot accidentally affect networking resources.

Mistake 5: Not Planning for Terraform State Migration

When you outgrow your state structure, you need to migrate resources between state files using terraform state mv commands—one per resource. With 200+ resources, this becomes a significant project; getting it wrong can orphan resources or create duplicates.

What I do now

Design the state structure for where the project will be in 12 months, not just for today. Starting with more granular state is far easier than splitting a monolith later.

Mistake 6: Manual Workspace Management

I used Terraform workspaces to manage staging and production environments, assuming a different workspace equals a different state and thus a different environment.

The problem: nothing prevents you from running terraform apply in the wrong workspace. I once applied a destructive change to production instead of staging, causing a short outage that could have been avoided.

What I do now

Use separate directories for separate environments. The directory structure makes it obvious which environment you are operating on.

The Pattern in All of These

Every mistake I made with Terraform came from optimizing for the short term. A single state file is simpler to set up than many; user data is faster than setting up Ansible; workspaces are less overhead than separate directories.

The short‑term convenience always came with a long‑term cost.

Terraform is a tool for managing infrastructure that will outlast any individual engineer’s involvement. Design for that.

I am building Step2Dev to make the right Terraform practices the default, not the exception. More at .

What Terraform mistake cost you the most? Drop it in the comments.