What is Terraform State? (Explained Simply)

If you've started learning Terraform, you've heard about "state." It sounds complicated, but the idea behind it is simple. Let's break it down.

The Problem Terraform Has to Solve

When you write Terraform code and run terraform apply, Terraform creates real infrastructure — EC2 instances, S3 buckets, VPCs, whatever you defined.

Now here's the question: next time you run terraform apply, how does Terraform know what already exists? It can't just read your AWS account — there are thousands of resources there from other teams, other tools, even manual clicks.

Terraform needs a way to track: "these specific resources were created by me, with this configuration."

That's what state is.

What Terraform State Actually Is

Terraform state is a JSON file (terraform.tfstate) that maps your Terraform code to real infrastructure.

{
  "version": 4,
  "resources": [
    {
      "type": "aws_instance",
      "name": "web_server",
      "instances": [
        {
          "attributes": {
            "id": "i-0a1b2c3d4e5f",
            "instance_type": "t3.micro",
            "ami": "ami-0c55b159cbfafe1f0"
          }
        }
      ]
    }
  ]
}

Every time you run terraform apply, Terraform:

1. Reads your .tf files (what you want)
2. Reads the state file (what you have)
3. Reads real infrastructure (what actually exists)
4. Calculates the difference
5. Makes changes to close the gap
6. Updates the state file

Your code → Terraform → State file → Cloud (AWS/GCP/Azure)

Where State Is Stored

Local State (default, not recommended for teams)

By default, Terraform stores state in a file called terraform.tfstate in your project directory.

ls -la
# terraform.tfstate      ← your state file
# terraform.tfstate.backup
# main.tf
# variables.tf

Problem: If you work in a team, each person has their own state file. Two engineers run terraform apply at the same time — both think the other's resources don't exist. Chaos.

Remote State (recommended)

For teams, store state in a shared remote location with locking.

AWS S3 + DynamoDB (most common):

terraform {
  backend "s3" {
    bucket         = "my-company-terraform-state"
    key            = "production/eks/terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "terraform-state-locks"
    encrypt        = true
  }
}

• S3: stores the state file, versioned (you can roll back)
• DynamoDB: handles locking (prevents two people from applying at the same time)

Terraform Cloud / HCP Terraform:

terraform {
  cloud {
    organization = "my-company"
    workspaces {
      name = "production"
    }
  }
}

Terraform Cloud stores state, handles locking, shows a UI, and has a free tier for small teams.

Why State Locking Matters

Imagine two engineers both run terraform apply at the same moment:

Engineer A: reads state → calculates plan → starts applying
Engineer B: reads state → calculates plan → starts applying
                                           ↑ both see the same state!

Both think the resource doesn't exist. Both try to create it. One succeeds, one fails — or worse, both succeed and you have duplicate resources.

State locking prevents this:

Engineer A: reads state → acquires lock → applies → releases lock
Engineer B: tries to acquire lock → BLOCKED → waits → gets lock → applies

With S3 backend, DynamoDB holds the lock. You'll see this error if someone else is applying:

Error: Error acquiring the state lock
Lock Info:
  ID: 12345678-abcd
  Who: engineer_a@company.com
  Created: 2026-04-17 10:30:00

State File: Never Edit It Manually

The state file is a Terraform-managed file. Do not edit it with a text editor.

If state gets out of sync, use Terraform commands:

# Show what's in state
terraform state list
 
# Show details of a specific resource
terraform state show aws_instance.web_server
 
# Remove a resource from state (doesn't delete real resource)
terraform state rm aws_instance.web_server
 
# Import an existing resource into state
terraform import aws_instance.web_server i-0a1b2c3d4e5f
 
# Move a resource to a new address (after refactoring)
terraform state mv aws_instance.web_server aws_instance.app_server

State Drift

Sometimes your real infrastructure changes outside of Terraform — someone clicks in the AWS console, a script modifies a resource.

The state file still has the old values. This is called drift.

# Refresh state to match real infrastructure
terraform refresh
 
# Or check for drift without changing anything
terraform plan -refresh=true

Terraform will show you what changed and what it wants to fix.

Sensitive Data in State

State files contain sensitive data — database passwords, private keys, API tokens. Treat your state file like a secret.

resource "aws_db_instance" "main" {
  password = var.db_password   # this ends up in state!
}

This is why:

• Always encrypt your S3 state bucket (encrypt = true)
• Use IAM policies to restrict who can read the state bucket
• Never commit terraform.tfstate to Git (add it to .gitignore)

# .gitignore
*.tfstate
*.tfstate.backup
.terraform/

State Workspaces

Workspaces let you have multiple state files for the same Terraform code — useful for managing dev/staging/prod with the same configuration.

# Create a workspace
terraform workspace new staging
 
# Switch workspace
terraform workspace select production
 
# List workspaces
terraform workspace list
# * default
#   staging
#   production

Each workspace has its own state file in S3:

s3://my-bucket/production/eks/terraform.tfstate
s3://my-bucket/staging/eks/terraform.tfstate

Common State Problems and Fixes

State lock stuck after a crash:

terraform force-unlock <lock-id>

Resource exists in cloud but not in state:

terraform import <resource_type>.<name> <real_id>

State file got corrupted:

• Restore from S3 versioning (this is why versioning is important!)

Summary

Learn More

• DevOpsBoys Terraform Remote State Guide — step-by-step S3 backend setup
• Terraform Official Docs: State — full reference
• Terraform: From Beginner to Master on Udemy — the best paid course, covers state management in depth

Once you understand state, Terraform becomes much less mysterious. It's just a file that helps Terraform remember what it created.