Module 2: Terraform Fundamentals

Lesson 2.5: How Terraform Uses State

Plain language

State is Terraform's record of what it manages. By default it's stored as terraform.tfstate (JSON) in the working directory. Without state, Terraform couldn't tell which real object a block like random_pet.server refers to.

Why state exists

Purpose Explanation
Mapping Binds each resource address to a real object ID
Metadata Tracks dependencies, so Terraform can destroy in the right order even after a reference is removed from config. Also records which provider configuration manages each resource.
Performance Caches attribute values. Large teams can skip refresh with -refresh=false, with care.
Collaboration Remote state with locking lets teams share one source of truth (Module 6)

What's inside

  • version, terraform_version, serial (increments on each write), and lineage (a unique ID for this state's history)
  • Each resource's type, name, provider, and every attribute value
  • Output values

Under the hood

  • By default, plan and apply refresh state from the real APIs before diffing, which is how drift is detected (Module 6).
  • State is plaintext. It contains every attribute the provider returns, including passwords, private keys, and tokens. Marking a value sensitive = true only hides it in CLI output. It is still stored in state. Module 4 covers ephemeral values and write-only arguments, which keep some values out of state.
  • Never edit state by hand. Use terraform state subcommands and moved, removed, or import blocks (Modules 6 and 7).