sdlc.dev

Terraform path · State · Topic 5 of 14

State: Terraform's memory

Not started

Every time Terraform creates something, it writes down what it created in the **state**: a JSON document that maps each resource address in your configuration (random_pet.name) to the real object's ID and its last known attributes. On the next run, Terraform reads state, refreshes those objects from the provider, and diffs them against the configuration. State is not a cache you can rebuild at will; it is the only record of which real objects belong to which blocks.

Why it matters: State is how Terraform knows that random_pet.name is the object with ID dev-known-woodcock. Lose it, corrupt it or let two runs write it at once, and Terraform can no longer manage what it built.

  1. 1State binds addresses to IDs

    For each resource address, state records the real object's ID and its last known attributes.

  2. 2Plans need it

    Without state, Terraform would not know which objects it owns, and would try to create everything again.

  3. 3Never hand-edit it

    Use terraform state commands, moved, import and removed blocks. Editing the JSON risks corrupting the serial, lineage or resource data.

  4. 4It is sensitive

    State holds every attribute, including passwords and keys, in plain text. Protect it like a secret.

1

How it works

The explanation, with examples you can run.

What is inside

From the local demo used in this path (Terraform 1.5.7), abridged:

{  "version": 4,  "terraform_version": "1.5.7",  "serial": 3,  "lineage": "86a3d8b9-6ec5-a133-dac0-a7eeb9bf9b0a",  "resources": [    {      "mode": "managed",      "type": "random_pet",      "name": "name",      "provider": "provider[\"registry.terraform.io/hashicorp/random\"]",      "instances": [        {          "schema_version": 0,          "attributes": { "id": "dev-known-woodcock", "length": 2, "prefix": "dev", "separator": "-" }        }      ]    }  ]}
  • lineage is a unique ID for this state's history; serial increases on every write. Terraform refuses to replace a state with one of a different lineage or a lower serial unless forced.
  • attributes are everything the provider returned, including computed values and secrets.
  • Dependencies between instances are recorded too, so Terraform can destroy objects in the right order even after their blocks are deleted from the configuration.

Working with state safely

terraform state list                        # every address in stateterraform state show random_pet.service     # one object's attributesterraform state mv  OLD NEW                 # rename an address (prefer a moved block)terraform state rm  ADDRESS                 # forget an object, leave it running (prefer a removed block)terraform state pull > backup.tfstate       # copy the current remote state

Configuration-driven alternatives (moved, import and removed blocks, covered in the refactoring topic) are better for anything routine, because they go through a plan and code review like any other change. Keep the state subcommands for repairs.

Do not edit the JSON by hand. It is easy to break the structure, forget the serial or leave dependencies pointing at nothing, and a bad state can make the next apply destroy things. If you must repair one, pull a backup first, change it with the CLI, and verify with a plan that shows no unexpected changes.

The rules that follow

  1. One writer at a time. Two simultaneous applies against one state lose updates or corrupt it. Use a backend with locking (next topic).
  2. Store it remotely, versioned. A laptop's terraform.tfstate is one disk failure from orphaning your infrastructure, and nobody else can run a plan.
  3. Keep it out of Git. It contains secrets, and merges of state files are meaningless.
  4. Keep states small. One state per environment and per area (network, data, apps) limits the blast radius of a bad apply and keeps plans fast.
  5. Restrict access. Read access to state is read access to every secret in it.
2

Check yourself

3 questions. Get them all right to finish this topic.

  1. 1.You delete terraform.tfstate and run terraform plan. What does Terraform propose?
  2. 2.You need to rename a resource address in state. What is the safe way?
  3. 3.What are the serial and lineage fields in a state file for?

0 of 3 right so far. Get all three to finish this topic.

Go deeper