The State File

The idea in one sentence

Terraform state is a JSON file that maps every resource in your configuration to the real-world object it created, and it is the only thing that lets Terraform know what it manages.

Why Terraform needs state at all

When you run terraform apply, Terraform creates resources through a cloud provider’s API — an EC2 instance, an S3 bucket, an IAM role. The provider API has no concept of “Terraform.” If you have 500 EC2 instances in an AWS account, the AWS API cannot tell you which of those instances Terraform created for a given resource "aws_instance" "web" block, which ones a teammate created by hand in the console, and which ones belong to a completely different Terraform configuration.

Terraform solves this by keeping its own record. Every time you apply, Terraform writes the mapping between your configuration’s resource addresses and the real infrastructure IDs into a state file, by default named terraform.tfstate:

resource "aws_instance" "web" {
  ami           = "ami-0abcdef1234567890"
  instance_type = "t3.micro"
}

After apply, the state file records something like aws_instance.web -> i-0123456789abcdef0, plus every attribute AWS returned for that instance — its private IP, its ARN, its security group associations, and so on. That cached data means Terraform does not have to call the AWS API and re-describe every resource just to compute a plan; it can compare your configuration against the last known state first, which is both how it detects what changed and a real performance win on large configurations. State is also where Terraform stores dependency metadata, so it knows the order in which resources must be created, updated, or destroyed.

The plaintext risk hiding in your state file

State files are not sanitized. Any attribute value Terraform receives from a provider — or that you set directly in your configuration — is written into terraform.tfstate as plaintext, including values that are secrets. A common example:

resource "aws_db_instance" "main" {
  identifier     = "app-db"
  engine         = "postgres"
  instance_class = "db.t3.micro"
  username       = "app_admin"
  password       = "S3cretPassword!"
}

You never ran terraform output on that password and you never printed it in a log line. It still lands in terraform.tfstate in plaintext, because Terraform has to remember every attribute it set in order to detect drift on the next plan. Anyone who can read that file can read the password.

This is why terraform.tfstate must never be committed to version control. Add it to .gitignore from the very first commit of a new project:

terraform.tfstate
terraform.tfstate.backup
*.tfstate
*.tfstate.*

The next lesson covers moving state off your laptop entirely and into a properly access-controlled remote backend, which is the real fix for this risk — a .gitignore entry only stops the most obvious accident.

Inspecting state

Terraform ships three commands for looking inside state without opening the JSON file by hand:

# Human-readable dump of the entire current state
terraform show

# List every resource address currently tracked in state
terraform state list

# Show full attribute detail for one specific resource
terraform state show aws_instance.web

terraform state list is the fast way to answer “what does this configuration actually manage right now” — it prints addresses like aws_instance.web or module.network.aws_vpc.main with no other detail. terraform state show <address> drills into one of those addresses and prints every attribute Terraform has recorded for it, which is often faster than going to the AWS console when you need to check a specific value Terraform is tracking.

flowchart LR
  cfg["Terraform config (.tf files)"] --> apply["terraform apply"]
  apply --> aws["Real AWS resources"]
  aws -->|attributes written back| state["terraform.tfstate"]
  cfg -->|next run| plan["terraform plan"]
  state -->|read for comparison| plan

Config and real AWS resources both feed the state file that the next plan reads