Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 37 ยท State Management

Terraform State: What It Is and Why It Exists

Understand Terraform state: what terraform.tfstate stores, how Terraform uses it to map code to real resources, and how to inspect it safely with state commands.

Every time you run terraform plan, Terraform answers one question: "What must change so that reality matches my code?" To answer it, Terraform needs to know what already exists. It does not ask the cloud about everything you ever created; it keeps its own record, called the state. Without state, Terraform could not tell whether the server in your code is a brand-new one or the same server it created last week.

State is the most important and the most dangerous part of Terraform. It is the bridge between your configuration (aws_instance.web) and a real object (i-0abc123...). This lesson explains what is inside, how Terraform uses it, and how to look at it without breaking anything.

Terraform and OpenTofu use the same state format, so everything here applies to both. Terraform cannot run on this site, so HCL and command output are read-only; the small Python programs are stand-ins that model the ideas.

What the state file contains

By default, Terraform writes a JSON file named terraform.tfstate next to your configuration. A trimmed example looks like this:

JSON
{
  "version": 4,
  "terraform_version": "1.9.5",
  "serial": 7,
  "lineage": "5b1c0e0e-1111-2222-3333-abcdefabcdef",
  "outputs": { "bucket_name": { "value": "demo-assets-42", "type": "string" } },
  "resources": [
    {
      "mode": "managed",
      "type": "aws_s3_bucket",
      "name": "assets",
      "provider": "provider[\"registry.terraform.io/hashicorp/aws\"]",
      "instances": [
        { "schema_version": 0, "attributes": { "id": "demo-assets-42", "bucket": "demo-assets-42" } }
      ]
    }
  ]
}

The important fields are:

  • serial goes up by one on every change. Backends use it to detect stale copies.
  • lineage is a random ID created with the state. Two files with different lineages are different histories and must never be mixed.
  • resources lists every managed resource (mode: managed) and data source (mode: data) with all its attributes, exactly as the provider last reported them.
  • outputs stores the values of your output blocks.

How Terraform uses state

During a plan Terraform does three things.

  1. It refreshes: asks each provider for the current attributes of every resource in state.
  2. It compares the configuration with the refreshed state.
  3. It produces a plan: create what is in code but not in state, update what differs, destroy what is in state but no longer in code.
flowchart LR
  C["Configuration (.tf)"] --> P["Plan: diff"]
  S["State (tfstate)"] --> P
  R["Real infrastructure"] -->|"refresh"| S
  P --> A["Apply"]
  A -->|"writes new values"| S
  A --> R

State sits between code and the real world.

State also stores things the cloud does not remember for you: the dependency order between resources, and metadata such as which provider handled each resource. Performance is a third reason: in large setups Terraform trusts state instead of reading thousands of objects, when you pass -refresh=false.

A tiny model of the diff

The program below is a stand-in for the core idea. It takes a desired configuration and a state, and prints what a plan would do.

Python Plan = desired minus state

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice that with no state at all, everything in desired would be "create", even if it already exists in the cloud. That is why losing state is so painful: Terraform would try to create duplicates.

Inspecting state safely

Never open terraform.tfstate in an editor and change it by hand. Use the read-only commands instead:

Terminal
terraform state list                      # all resource addresses
terraform state show aws_s3_bucket.assets # attributes of one resource
terraform show                            # whole state, human readable
terraform show -json | jq '.values'       # machine readable
terraform output bucket_name              # one output value

Example output (not produced by this site):

TEXT
$ terraform state list
aws_s3_bucket.assets
aws_s3_bucket_versioning.assets

Resources created with count or for_each have indexed addresses such as aws_instance.web[0] or aws_instance.web["blue"], and resources inside modules are prefixed: module.network.aws_vpc.main.

Python List and show resources from a state document

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Sensitive data in state

State stores attribute values in plain text. That includes database passwords, private keys and generated tokens, even when you mark a variable sensitive = true (that only hides it from plan output). Treat the state like a secret:

  • Never commit terraform.tfstate to Git. Add *.tfstate, *.tfstate.* and .terraform/ to .gitignore.
  • Use a remote backend with encryption and tight access rules (next lesson).
  • Prefer ephemeral values or secret managers for credentials where the provider allows it.

Backups and the .terraform folder

Terraform keeps terraform.tfstate.backup with the previous version after each local apply. The .terraform folder is different: it holds downloaded providers and backend configuration. You can delete it and run terraform init again, but deleting the state itself is a disaster.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the main job of the Terraform state?

    State links addresses like aws_instance.web to real IDs, so Terraform knows what it already manages.
  2. 2. Which command lists every resource address in state without changing anything?

    terraform state list is read-only and prints one address per line.
  3. 3. Does marking a variable sensitive keep it out of the state file?

    Sensitive affects display, not storage. Protect the state itself.
  4. 4. What does the lineage field tell you?

    Different lineages mean unrelated states; mixing them can corrupt your setup.

Summary

  • State maps configuration addresses to real resources and stores their attributes.
  • A plan is the difference between your code and the refreshed state.
  • serial and lineage help backends detect stale or foreign state files.
  • Read state with terraform state list, state show and show; do not edit the JSON by hand.
  • State contains secrets in plain text: keep it out of Git and encrypt it at rest.

Next: Remote State and Locking