Why does Terraform need a state file at all?

Words used on this page

state

Terraform's record of which real object belongs to each resource in your configuration, with the attribute values and dependencies it last saw.

resource address

The name Terraform records a resource under, such as terraform_data.web. It comes from your configuration, not from the cloud.

remote object

The real thing a resource manages, such as a server or a bucket, known to the provider by its own ID.

backend

Where state is kept: a local file by default, or remote storage such as an S3 bucket or HCP Terraform.

state lock

A lock Terraform takes on the state during operations that could write it, so two runs cannot change it at once. Not every backend supports one.

refresh

The first step of a plan: Terraform asks the provider for the current values of every object in state.

drift

A difference between what state records and what really exists, for example because something was changed outside Terraform.

sensitive

A marking that hides a value in Terraform's output. The value is still stored in state and plan files.

ephemeral value

A value Terraform keeps out of state and plan files entirely, such as a variable with ephemeral = true (Terraform 1.10 and later).

write-only argument

A resource argument, from Terraform 1.11, that is sent to the provider but never stored. Only providers that implement it offer one.

What Terraform forgets when it loses its state

Reproduced on Terraform 1.14.0 on macOS in an empty folder, with the time zone set to UTC, using only the built-in terraform_data resource: terraform init printed terraform.io/builtin/terraform is built in to Terraform and downloaded nothing. terraform apply -auto-approve had already created the one resource. Moving the state file aside stands in for losing it.

Command

cat main.tf
terraform state list
terraform state show terraform_data.web
mv terraform.tfstate lost.tfstate
terraform plan -no-color
mv lost.tfstate terraform.tfstate
terraform plan -no-color

Output

$ cat main.tf
resource "terraform_data" "web" {
  input = "web-1"
}

$ terraform state list
terraform_data.web

$ terraform state show terraform_data.web
# terraform_data.web:
resource "terraform_data" "web" {
    id     = "d44afb6b-f342-04bd-36e3-eb3bc76a3526"
    input  = "web-1"
    output = "web-1"
}

$ mv terraform.tfstate lost.tfstate

$ terraform plan -no-color

Terraform used the selected providers to generate the following execution
plan. Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # terraform_data.web will be created
  + resource "terraform_data" "web" {
      + id     = (known after apply)
      + input  = "web-1"
      + output = (known after apply)
    }

Plan: 1 to add, 0 to change, 0 to destroy.

─────────────────────────────────────────────────────────────────────────────

Note: You didn't use the -out option to save this plan, so Terraform can't
guarantee to take exactly these actions if you run "terraform apply" now.

$ mv lost.tfstate terraform.tfstate

$ terraform plan -no-color
terraform_data.web: Refreshing state... [id=d44afb6b-f342-04bd-36e3-eb3bc76a3526]

No changes. Your infrastructure matches the configuration.

Terraform has compared your real infrastructure against your configuration
and found no differences, so no changes are needed.

How to read it

• terraform state list shows the one address Terraform tracks. terraform state show shows what it recorded, including id = "d44afb6b-f342-04bd-36e3-eb3bc76a3526". That ID appears nowhere in main.tf: Terraform generated it when it created the resource, and state is the only place it is kept.
• With the state file moved away, the same configuration plans terraform_data.web will be created, with id = (known after apply). The object still exists; what is gone is the link between your block and it. With a real provider, applying this plan would create a second object beside the first, with a new ID.
• With the file back, the plan prints Refreshing state... [id=d44afb6b-...] and No changes. Terraform checked only the object state pointed it to. It did not have to search the account for it.
• In the same folder, a second terraform apply left the previous version in terraform.tfstate.backup. That file is the local backend's only built-in way back, and it holds the same values, secrets included, as the state.