Terraform has to remember which real object belongs to which block in your code. When you write resource "docker_container" "web", nothing on the Docker host says “I am docker_container.web“. That link lives in the state. Get state right and Terraform is calm and predictable; get it wrong and you see plans that want to recreate everything, or two people overwriting each other’s work.
What is in the state file
After an apply, the local backend writes terraform.tfstate, a JSON file. Do not edit it by hand, but do know how to look inside:
$ terraform state list
docker_container.web
docker_image.web
docker_network.orbit
$ terraform state show docker_container.web
# docker_container.web:
resource "docker_container" "web" {
id = "6f1c2e9b..."
image = "sha256:a3e1..."
name = "orbit-dev-web"
...
}
$ terraform state show -json docker_container.web | jq .values.name
"orbit-dev-web"
state show -json is new in Terraform 1.16 and makes scripting much easier. State holds:
- The mapping from each resource address to a real object ID.
- Every attribute the provider returned, including computed ones such as IDs and IP addresses. That is how other resources can reference them without calling the API again.
- Metadata: dependencies between resources, provider used, a serial number and a lineage ID so Terraform notices if two unrelated states get mixed up.
State contains secrets. Database passwords, private keys and tokens returned by providers land in state in plain text, even when marked sensitive. Treat the state file like a password vault: encrypted storage, restricted access, never in Git.
Why local state breaks down
A terraform.tfstate on your laptop is fine for practice. For anything shared it fails in three ways:
- Sharing: your teammate’s laptop does not have your state, so their plan wants to create everything again.
- Concurrency: two applies at the same time both read the old state and both write a new one; one of them loses.
- Durability: a lost laptop or a
git cleandeletes the only record of what Terraform manages.
A remote backend fixes all three: state lives in shared, durable storage and a lock stops two runs from writing at the same time.
Remote state on S3, with native locking
S3 is the most common backend. Until recently it needed a DynamoDB table just for locking. Since Terraform 1.11, S3 locks with a small .tflock object next to the state, and DynamoDB locking is deprecated.
terraform {
backend "s3" {
bucket = "orbit-tfstate-123456789012"
key = "orbit/staging/terraform.tfstate"
region = "eu-west-1"
encrypt = true
use_lockfile = true
}
}
The bucket itself should have versioning on (so you can recover an older state), public access blocked and access limited to the people and pipelines that run Terraform. Create it once, by hand or from a tiny separate “bootstrap” configuration, never from the configuration whose state it holds.
Backend blocks cannot use variables, because they are read during init. To reuse one block across environments, leave out the parts that change and pass them at init time (partial configuration):
# staging.s3.tfbackend
bucket = "orbit-tfstate-123456789012"
key = "orbit/staging/terraform.tfstate"
region = "eu-west-1"
$ terraform init -backend-config=staging.s3.tfbackend
Moving from local to remote state is one command. Add the backend block and run:
$ terraform init -migrate-state
Do you want to copy existing state to the new backend?
Enter a value: yes
Successfully configured the backend "s3"!
Already using DynamoDB locking? Add use_lockfile = true while keeping dynamodb_table, run terraform init -reconfigure, and once every pipeline uses 1.11 or newer, remove dynamodb_table and delete the table.
Since Terraform 1.15 the S3 backend also accepts credentials from aws login, so you do not need long-lived access keys on your laptop.
Remote state on HCP Terraform
HCP Terraform (formerly Terraform Cloud) stores state, locks it, keeps a version history and can run plans and applies remotely. Configure it with a cloud block instead of backend:
terraform {
cloud {
organization = "orbit"
workspaces {
name = "orbit-staging"
}
}
}
$ terraform login
$ terraform init
Other backends follow the same idea: azurerm (Azure Storage, locks with blob leases), gcs (Google Cloud Storage), kubernetes (a Secret), pg (PostgreSQL) and http.
Locks and how to free a stuck one
Every command that can write state takes the lock first. If a run crashes, the lock can stay behind:
$ terraform plan
Error: Error acquiring the state lock
Lock Info:
ID: 3c1f9a6e-8a4b-4f0c-9d1e-2b7a5c0e4d11
Operation: OperationTypeApply
Who: ci-runner@build-42
Created: 2026-10-30 09:12:44 UTC
First check that nobody is really running Terraform (the Who and Created fields help). Only then release it:
$ terraform force-unlock 3c1f9a6e-8a4b-4f0c-9d1e-2b7a5c0e4d11
Forcing the lock while an apply is actually running is how states get corrupted.
Refactoring without destroying: moved
You rename docker_container.web to docker_container.frontend. To Terraform that looks like “destroy web, create frontend“. A moved block tells it the object simply has a new address:
moved {
from = docker_container.web
to = docker_container.frontend
}
$ terraform plan
# docker_container.web has moved to docker_container.frontend
Plan: 0 to add, 0 to change, 0 to destroy.
Prefer moved blocks over the older terraform state mv command: the move is in code, reviewed in a pull request and applied the same way in every environment. You can delete old moved blocks once every state has been applied with them.
Letting go without destroying: removed and destroy = false
Sometimes Terraform should stop managing something without deleting it, for example when the cache moves to another team’s configuration. Delete the resource block and add a removed block (Terraform 1.7+):
removed {
from = docker_container.cache
lifecycle {
destroy = false
}
}
Plan shows that the container will be forgotten, not destroyed. This replaces terraform state rm with something reviewable.
Terraform 1.16 also accepts destroy = false directly in a resource’s lifecycle block. When Terraform would destroy that resource, it removes it from state instead and leaves the real object alone. That is handy for something shared, like a network another stack also uses, inside a configuration you tear down often.
The state commands, and when to use them
| Command | Use it for | Prefer instead |
|---|---|---|
terraform state list | Seeing what is managed | |
terraform state show <addr> | Inspecting one resource | |
terraform state mv | Renames and moves | moved block |
terraform state rm | Forgetting a resource | removed block |
terraform import | Adopting an existing object | import block (lesson 7) |
terraform state pull | Downloading a copy (backups, debugging) | |
terraform state push | Overwriting remote state | Almost never: last resort |
Quick reference
| Task | Command |
|---|---|
| List managed resources | terraform state list |
| Inspect one as JSON (1.16) | terraform state show -json docker_container.web |
| Use a partial backend file | terraform init -backend-config=staging.s3.tfbackend |
| Copy local state to a new backend | terraform init -migrate-state |
| Change backend settings without copying | terraform init -reconfigure |
| Release a stuck lock | terraform force-unlock <LOCK_ID> |
| Download remote state | terraform state pull > backup.tfstate |
| Log in to HCP Terraform | terraform login |
Exercise
You rename resource “docker_container” “web” to “frontend” and the plan wants to destroy one container and create another. What is the cleanest fix?
Show answer
Answer: C. A moved block records the rename in code, so every environment applies it the same way and the real container is kept.
Exercise
Your team uses Terraform 1.17 with an S3 backend. What do you need for state locking?
Show answer
Answer: B. Since 1.11, the S3 backend locks with a .tflock object next to the state when use_lockfile is true. DynamoDB locking still works but is deprecated.
Key takeaways
- State maps each resource address to a real object and caches its attributes.
- State holds secrets in plain text: encrypt it, restrict it, keep it out of Git.
- Shared work needs a remote backend with locking: S3 with
use_lockfile = true, HCP Terraform, or your cloud’s storage. - Free a stuck lock with
force-unlockonly after checking nobody is applying. - Refactor with
movedblocks and stop managing things withremovedblocks, not with state surgery. destroy = false(1.16) makes Terraform forget a resource instead of destroying it.
FAQ
What happens if I lose the state file?
Terraform forgets everything it managed. The real infrastructure keeps running, but the next plan wants to create it all again. You can rebuild state with import blocks, which is slow; S3 versioning or HCP Terraform’s state history makes recovery a two-minute job instead.
Should each environment have its own state?
Yes. Separate state per environment (and often per component, such as network versus applications) limits the blast radius of a mistake and keeps plans fast. Lesson 11 compares the ways to organise this.
Can two configurations share one state file?
No. Each configuration owns its state. If one needs values from another, read the other’s outputs (terraform_remote_state) or publish them to a shared store.
Is it safe to look at the state file in a text editor?
Reading is fine if you are allowed to see the secrets in it. Editing is not: use moved, removed and import blocks, or terraform state commands, which check the format and keep a backup.