What State Knows

Scenario: Your configuration talks about fakecloud_server.api in friendly, human terms, but the real FakeCloud API only knows that object by an opaque internal identifier like srv-a81 - something has to durably remember which is which.

State is the piece of this whole system that connects your human-readable configuration to real, provider-side objects. Concretely, it's a JSON file (by default terraform.tfstate, sitting locally unless you configure a remote backend - next section) that records, for every resource Terraform manages: its Terraform address, the real object's provider-assigned ID and other attributes as of the last apply or refresh, and dependency metadata used to rebuild the graph on future runs.

It helps to be precise about what state is not: it is not merely a performance cache you could safely delete and regenerate (deleting it makes Terraform believe none of your infrastructure exists, and it will then propose creating everything again - a genuine incident), and it should never be hand-edited directly with a text editor. Every plan is really a three-way comparison: your configuration (the desired end state you wrote), your prior state (what Terraform remembers doing last time), and freshly refreshed data read live from the provider (observed current reality). Any state file also carries lineage and serial metadata specifically so that two people's near-simultaneous updates can be detected and rejected rather than silently overwriting each other - the locking mechanism you'll meet two sections from now builds directly on this.

Analogy: State is the title registry for a portfolio of managed property - it's the document that proves which real-world parcel corresponds to which entry in your books. Losing an architectural blueprint is bad and inconvenient. Losing the title registry is worse: you can still see the buildings standing there, but you no longer have a trustworthy record of which title belongs to which building, which risks duplicate ownership claims or, worst case, someone accidentally scheduling the wrong building for demolition.

A worked configuration

terraform state list
terraform state show fakecloud_server.api
terraform show
# Back up before exceptional state surgery:
terraform state pull > reviewed-backup.json

Treat state exactly like production data, because functionally it is: encrypt it, restrict who can read or write it, version it so you can recover a prior snapshot, back it up independently, and only ever change it through Terraform's own commands - never a manual text edit. State frequently contains secrets (a generated database password, a token) even when your .tf configuration files never hardcode one anywhere, simply because the provider returned that value as part of a resource's attributes and Terraform faithfully recorded it.

Common mistakes in production

• Deleting or manually editing terraform.tfstate to "clean it up" - Terraform will then genuinely believe the managed infrastructure doesn't exist and may propose recreating all of it.
• Assuming state is safe to skip encrypting or access-restricting because "the .tf files don't contain any secrets" - state very often contains secrets the configuration never explicitly wrote.

Goal: Treat the plan as a change contract: understand every create, update, replacement, and destroy before approving it. Reinforce this lesson in the tf-local-backend-basics Terraform lab. Open /labs/terraform and choose slug tf-local-backend-basics; the lab runs real Terraform against the offline FakeCloud provider.