The State File Anatomy

The state file is JSON with a defined structure: a handful of top-level fields — version, serial, lineage, terraform_version — followed by a list of resource instances and their recorded attributes. You rarely touch it directly, but reading it once demystifies a lot of Terraform's behavior.

Knowing the anatomy is also what makes later state surgery safe rather than terrifying. When you understand why serial increments, what lineage protects against, and where the secrets live, the operations that move and remove resources stop feeling like open-heart surgery on a file you do not understand.

Top-Level Fields

Every state file opens with bookkeeping. version is the state format version; terraform_version records which binary last wrote it; serial is an integer that increments on every write; and lineage is a UUID generated when the state is first created and carried forever after, identifying this particular state's history.

{
  "version": 4,
  "terraform_version": "1.10.5",
  "serial": 17,
  "lineage": "a1b2c3d4-5e6f-7890-abcd-ef0123456789",
  "outputs": { },
  "resources": [ ]
}

Resources and Instances

The resources array holds one entry per resource block, each carrying a mode (managed for resources, data for data sources), a type, a name, the provider that owns it, and an instances list. A plain resource has one instance; a resource with count or for_each has one per key. Each instance carries the full bag of resolved attributes — every value the provider returned after creating the object.

{
  "mode": "managed",
  "type": "aws_db_instance",
  "name": "primary",
  "provider": "provider[\"registry.terraform.io/hashicorp/aws\"]",
  "instances": [
    {
      "schema_version": 2,
      "attributes": {
        "id": "db-XYZ",
        "username": "admin",
        "password": "S3cr3t-in-plaintext"
      },
      "dependencies": ["aws_db_subnet_group.main"]
    }
  ]
}

Sensitive Values in State

Look again at that password field. It sits in the state file in plaintext, exactly as the provider returned it — regardless of whether you marked it sensitive in the config. The sensitive flag governs CLI output, not storage: it stops the value printing in a plan or an output, and does nothing to the bytes on disk. RDS passwords, generated private keys, and random_password results all land here in the clear, which is the entire reason state must be treated as a secret.

Dependencies and Metadata

Each instance also records the dependencies Terraform inferred and a schema_version for the resource. The dependency list lets Terraform reconstruct destroy order even if you later remove the references from your config. The schema version drives state upgrades: when a provider changes how it stores a resource, it bumps the schema version and supplies a migration that Terraform runs on read, which is why a state written by a much newer provider can fail to load on an old one.

Serial and Lineage in Practice

These two fields are how Terraform refuses to clobber state. Before writing, it checks that the serial it is about to overwrite is the one it read — if someone else wrote in between, the serial moved and Terraform rejects the stale write. lineage guards a different failure: copy a state file from an unrelated project over this one and the UUID will not match, so Terraform warns it is looking at a different state history rather than silently treating it as the same stack. Let Terraform manage both; hand-editing them is how you get a backend to reject your file.