how/state

Anatomy of terraform.tfstate

What lives inside the state file, why serial and lineage are there, and why a password from HCL ends up as plain text in it. The full JSON, layer by layer.

The state file is Terraform's private database about your infrastructure. Not a transactional Postgres, just JSON, usually terraform.tfstate.

Why you need it:

to match a resource from HCL (by the name aws_s3_bucket.demo) with a real object in the cloud (by id = "linuxlab-3f4a"). Without this, Terraform would not know which bucket it had created.
to remember dependencies: what depends on what, in which order to create and to destroy.
to cache resource attributes so that plan does not poke the cloud without need.

Press ▶, we will walk through the file layer by layer. The reference is tf-state.

step 1/6·00 · the file is closed

§ steps

terraform.tfstate sits in the project root next to main.tf. By default it is plain JSON on disk. After apply, an entry for each resource appears in it. Let's open it.

recap

The main things about state:

It is the source of truth. Not a file in the cloud, not the AWS console, but exactly terraform.tfstate. If state is broken or lost, Terraform loses its connection to reality (see tf-state-import).
serial grows on every apply. lineage is a UUID that never changes (it is generated when the state is first created). These two fields protect against conflicts with a remote backend.
dependencies are written into state, not computed on the fly. If you ran terraform state rm, you also dropped the dependencies. That is why state rm is dangerous.
Any sensitive value in HCL ends up in state in plain text. This is not a bug, it is how it works. You protect it with remote backend encryption and access control (see tf-secrets-in-state, tf-remote-backend-s3).

Next: tf-drift, what happens when state and reality drift apart.

§ dig into the knowledge base

§ try it hands-on