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.
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:
| Concern | Local state | Remote state |
|---|---|---|
| Sharing | Only on your laptop | Shared via a backend |
| Locking | None — two applies collide | Lock prevents concurrent writes |
| Durability | Lost if the laptop dies | Versioned and backed up |
| Secrets | Plaintext on disk | Encrypted 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 runningapplyat 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
.tfstateand.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 statesubcommands; hand edits silently break the format or dependencies. - Running
terraform destroyto "clean up" after a bad import. Import touches only state — a destroy would delete the real resource. Useterraform state rminstead. - 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.