How Terraform Uses and Manages State

What it is

State is Terraform's record of the infrastructure it manages. It maps each resource address in your configuration, such as aws_instance.web, to the real object it created, such as instance i-0abc123, and stores that object's last known attributes.

By default state is a JSON file named terraform.tfstate in the working directory, written by the local backend. Teams usually move it to a remote backend or HCP Terraform so everyone works from the same copy.

How it works

Why Terraform needs state

Without state, Terraform could not tell whether a resource in your configuration already exists or needs to be created. It also could not know what to delete when you remove a block from the configuration.

State during plan and apply

By default terraform plan and terraform apply refresh state first: Terraform asks the providers for the current attributes of every managed object. Differences between the refreshed values and the configuration become proposed changes.

After terraform apply makes changes, Terraform writes the new attributes back to state. Commands such as terraform validate and terraform output do not refresh state.

Drift and refresh only mode

Drift is when someone changes a managed object outside Terraform, for example in the cloud console. The next plan detects it during refresh and proposes changes to bring the object back to the configuration.

To accept the outside changes into state without changing any infrastructure, use refresh only mode:

terraform plan -refresh-only
terraform apply -refresh-only

The standalone terraform refresh command is deprecated because it updated state without showing you what would change first.

Where state lives

terraform {
  backend "s3" {
    bucket       = "example-tf-state"
    key          = "network/terraform.tfstate"
    region       = "us-east-1"
    use_lockfile = true
  }
}

State locking stops two runs from writing the same state at once. Backends that support it lock automatically for any operation that could write state.

Secrets in state

State stores resource attributes in plain text, including passwords, keys and values marked sensitive = true. Marking a value sensitive only hides it in CLI output.

Protect state like a secret: use a remote backend with encryption at rest and restricted access, and never commit terraform.tfstate to version control. Ephemeral values, such as ephemeral variables and ephemeral resources, are not stored in state or plan files.

Working with state safely

Do not edit the state file by hand. Use the CLI instead: terraform state list and terraform state show inspect it, terraform state mv and terraform state rm change it, and terraform show prints it in readable form.

How the exam asks about this

• "True or false: a database password passed in as a variable ends up in plain text in the state file." True, if it is stored as a resource attribute; sensitive only hides it in output.
• "An engineer changed a tag in the console and wants state to reflect it without touching infrastructure." Run terraform apply -refresh-only.
• "Which file does the local backend write by default?" terraform.tfstate in the working directory, with terraform.tfstate.backup holding the previous version.