The Terraform State File

Terraform state is a JSON document, typically named terraform.tfstate, that records the mapping between the resources declared in your configuration and the real objects that exist in your cloud provider. Without state, Terraform would have no way of knowing that the aws_instance.web block in your .tf files corresponds to a specific EC2 instance with a specific ID somewhere in AWS. Every time you run terraform plan or terraform apply, Terraform reads this file, compares it against both your configuration and the live infrastructure (via provider API calls), and computes the difference needed to reconcile the three. State also stores resource metadata, dependency ordering, and sometimes sensitive attribute values, which is why how and where you store it matters enormously in production.

A state file contains a top-level schema version, a Terraform version marker, a unique lineage identifier, a serial number that increments on every write, and a resources array. Each resource entry records its type, name, provider configuration, and one or more instances (multiple instances occur with count or for_each) holding the full set of attributes returned by the provider after creation — not just the ones you set in your configuration. This is why a plan can detect drift: it re-reads live attributes and compares them to what state recorded last time.

By default Terraform writes state to a local file in the working directory. This works fine solo, but breaks down the moment more than one person or one CI job needs to run Terraform against the same infrastructure: two engineers with two divergent local copies of terraform.tfstate can each apply changes that overwrite the other's understanding of reality, leading to duplicated resources, orphaned resources Terraform no longer tracks, or an apply that destroys something a teammate just created. This is the core motivation for remote state backends, which centralize the file and (when the backend supports it) add locking so only one apply can proceed at a time.

Because state stores every attribute a provider returns, it frequently contains secrets in plaintext — database passwords generated by a resource, private keys, connection strings. Terraform marks some attributes as sensitive so they're redacted from CLI output, but the underlying state file itself is not encrypted by Terraform. Anyone with read access to the state file can potentially read those values. This is a strong argument for backends that support encryption at rest (such as an S3 bucket with SSE-KMS) and for tightly scoped IAM access to the state storage location.