Skip to main content
Terraform·8 min read

Terraform State Explained — The File That Makes Terraform Work

A deep dive into Terraform state: what it is, why it exists, local vs remote backends, S3 + DynamoDB locking, the terraform state subcommands, importing existing resources, sensitive data, and drift.

DT

DevOps Engineer & Technical Writer

The Problem

Terraform code describes what you want. Real cloud resources are what you have. Something has to remember the mapping between the two — which aws_instance.web in your code corresponds to which i-0abc123 in AWS. That something is state. Lose it, corrupt it, or share it carelessly, and Terraform either recreates resources it already made or refuses to run at all.

HOW `terraform plan` COMPARES CODE, STATE, AND REALITY CONFIGURATION (.tf) desired state aws_instance.web type = t3.small what you wrote STATE FILE last known mapping web → i-0abc123 type = t3.small what Terraform recorded REAL CLOUD actual resources i-0abc123 (running) type = t3.large (!) what actually exists plan: real type (t3.large) ≠ desired (t3.small) → Terraform proposes to change it back

Every terraform plan performs a three-way comparison: your configuration (desired), the state file (what Terraform last recorded), and the real cloud (what actually exists after a refresh). The diff between them becomes the plan.

What State Actually Contains

State is a JSON document. For each managed resource it records the resource address (aws_instance.web), the provider, and a full snapshot of every attribute returned by the API — IDs, ARNs, IP addresses, computed values, and dependencies. A trimmed example:

{

"version": 4,

"terraform_version": "1.9.0",

"resources": [

{

"mode": "managed",

"type": "aws_instance",

"name": "web",

"instances": [

{

"attributes": {

"id": "i-0abc123",

"instance_type": "t3.small",

"private_ip": "10.0.1.24"

},

"dependencies": ["aws_subnet.app"]

}

]

}

]

}

Terraform needs this because cloud APIs have no idea that i-0abc123 is "the web server in your config." Only state knows that mapping.

Local vs Remote State

By default Terraform writes terraform.tfstate to the working directory. That is fine for a solo experiment and dangerous for a team:

ConcernLocal stateRemote state
SharingOnly on your laptopShared via a backend
LockingNone — two applies collideLock prevents concurrent writes
DurabilityLost if the laptop diesVersioned and backed up
SecretsPlaintext on diskEncrypted at rest

For anything beyond a quick test, use a remote backend.

Remote Backend: S3 + DynamoDB Locking

The most common AWS setup stores state in an S3 bucket and uses a DynamoDB table for locking:

terraform {

backend "s3" {

bucket = "mycompany-tf-state"

key = "prod/terraform.tfstate"

region = "ap-south-1"

dynamodb_table = "tf-state-locks"

encrypt = true

}

}

  • S3 holds the state file. Enable bucket versioning so you can roll back a bad write.
  • DynamoDB holds a lock item. When someone runs apply, Terraform writes a lock; a second person running apply at the same time gets a clear error instead of corrupting state.
  • encrypt = true turns on server-side encryption at rest.

State Locking in Practice

If a colleague is mid-apply, your run stops immediately:

$ terraform apply

Error: Error acquiring the state lock

Lock Info:

ID: 9f3c-...-a21

Who: alice@laptop

Created: 2026-10-07 09:14:22 UTC

If a process crashed and left a stale lock, release it deliberately with the lock ID — never casually:

terraform force-unlock 9f3c-...-a21

The <code class="inline-code">terraform state</code> Subcommands

These let you inspect and surgically edit state without touching real infrastructure:

# List every resource address in state

terraform state list

# Show all recorded attributes for one resource

terraform state show aws_instance.web

# Rename / move an address (e.g. after refactoring into a module)

terraform state mv aws_instance.web module.compute.aws_instance.web

# Remove a resource from state WITHOUT destroying it in the cloud

terraform state rm aws_instance.legacy

state mv is essential when you refactor code into modules — it tells Terraform "this is the same resource, just renamed," so it is not destroyed and recreated. state rm is how you hand a resource off to another configuration or stop managing it, leaving the real resource untouched.

Importing Existing Resources

When a resource was created by hand (or by another tool), bring it under Terraform management with import. First write a matching resource block, then import by its real ID:

resource "aws_s3_bucket" "legacy" {

bucket = "mycompany-legacy-logs"

}

terraform import aws_s3_bucket.legacy mycompany-legacy-logs

Import only writes to state — it does not generate code. After importing, run terraform plan and keep editing your block until the plan shows no changes, which confirms your config matches reality. Terraform 1.5+ also supports declarative import {} blocks if you prefer importing in code.

Sensitive Data Lives in State

State records attribute values verbatim — including database passwords, generated keys, and private IPs. This has two consequences:

  • Never commit state to Git. Add .tfstate and .tfstate.* to .gitignore.
  • Encrypt the backend and lock down access. Treat the state bucket like a secrets store: restrict the IAM policy, enable encryption, and audit reads.

Marking an output sensitive = true only hides it from CLI output — it is still stored in state in cleartext.

Drift

Drift is when the real cloud diverges from state — someone resized the instance in the console, or an autoscaler changed a value. Terraform detects drift during the refresh phase of a plan:

# Refresh state against reality and show what changed, without applying

terraform plan -refresh-only

A normal plan then proposes to pull reality back toward your configuration. The fix for chronic drift is cultural as much as technical: stop making manual changes to Terraform-managed resources.

Common Mistakes to Avoid

  • Committing the state file to version control. It contains secrets and causes merge conflicts that corrupt infrastructure tracking.
  • Sharing local state over Dropbox or a shared drive. There is no locking, so two concurrent applies will corrupt it. Use a real backend.
  • Editing the state JSON by hand. Use terraform state subcommands; hand edits silently break the format or dependencies.
  • Running terraform destroy to "clean up" after a bad import. Import touches only state — a destroy would delete the real resource. Use terraform state rm instead.
  • Forgetting to enable S3 versioning. Without it, a bad write to state has no undo.

FAQ

Can I just delete the state file and start over?

No. Without state, Terraform no longer knows which real resources it manages, so your next apply will try to create duplicates of everything. If state is truly lost, you must re-import each resource. Keep remote state versioned so you can roll back instead.

What is the difference between <code class="inline-code">terraform state rm</code> and <code class="inline-code">terraform destroy</code>?

terraform state rm removes a resource from Terraform's tracking but leaves the real cloud resource running. terraform destroy deletes the actual resource. Use rm to stop managing something, destroy to tear it down.

Why do I need DynamoDB with an S3 backend?

S3 stores the state file, but S3 alone cannot guarantee that only one person writes at a time. DynamoDB provides the lock that prevents two concurrent applies from corrupting state. Without it you have remote storage but no safety against races.

How do I fix drift when someone changed a resource in the console?

Run terraform plan to see the proposed changes, then terraform apply to bring reality back in line with your configuration. If the manual change was intentional, update your Terraform code to match instead, then apply so state and config agree.