Lesson 05 intermediate

Terraform State and Backends

What the state file holds and why Terraform needs it, how to store it remotely with locking on S3 (no DynamoDB needed any more) or HCP Terraform, and how to refactor safely with moved, removed and the new destroy = false.

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 clean deletes 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

CommandUse it forPrefer instead
terraform state listSeeing what is managed
terraform state show <addr>Inspecting one resource
terraform state mvRenames and movesmoved block
terraform state rmForgetting a resourceremoved block
terraform importAdopting an existing objectimport block (lesson 7)
terraform state pullDownloading a copy (backups, debugging)
terraform state pushOverwriting remote stateAlmost never: last resort

Quick reference

TaskCommand
List managed resourcesterraform state list
Inspect one as JSON (1.16)terraform state show -json docker_container.web
Use a partial backend fileterraform init -backend-config=staging.s3.tfbackend
Copy local state to a new backendterraform init -migrate-state
Change backend settings without copyingterraform init -reconfigure
Release a stuck lockterraform force-unlock <LOCK_ID>
Download remote stateterraform state pull > backup.tfstate
Log in to HCP Terraformterraform 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?

  1. Run terraform apply and let it recreate the container
  2. Edit terraform.tfstate and change the name by hand
  3. Add a moved block from docker_container.web to docker_container.frontend
  4. Run terraform force-unlock and plan again
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?

  1. A DynamoDB table with a LockID key
  2. use_lockfile = true in the backend block
  3. Nothing, S3 locks every object automatically
  4. An HCP Terraform account
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-unlock only after checking nobody is applying.
  • Refactor with moved blocks and stop managing things with removed blocks, 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.

↑ ↓ navigate Enter open Esc close