Chapter 34: Terraform State Remote S3 Backend Locking and Workspaces

34.1 State — Terraform's memory of what it built

By Ravindra Bagale · Last updated: 25 October 2026

Story. On a Netflix-style team, an engineer deleted terraform.tfstate from a laptop to "clean up" and the next plan wanted to create every resource again. State is the file that maps each resource block to a real cloud id. Without it Terraform cannot tell what it owns. State also stores attribute values in plain text, including passwords, so it must never be committed to Git.

# .gitignore
.terraform/
*.tfstate
*.tfstate.*
crash.log
*.tfvars
!example.tfvars

terraform state list
terraform show

What each line does

• .terraform/ — Ignores the downloaded provider plugins.
• *.tfstate — Never commits the state file, which can hold secrets.
• *.tfstate.* — Also ignores backup copies such as terraform.tfstate.backup.
• crash.log — Ignores crash logs that may contain sensitive data.
• *.tfvars — Ignores personal value files.
• !example.tfvars — Keeps the shared example file so teammates know what to fill in.
• terraform state list — Lists every resource address Terraform tracks.
• terraform show — Prints the full current state in readable form.

When it is green.

aws_instance.web
aws_s3_bucket.logs
aws_security_group.web

When it is red.

Plan: 3 to add, 0 to change, 0 to destroy.
(expected 0 changes - state file was lost; the real resources still exist)

Fix. Do not apply. Restore the state from backup or remote versioning, or import the existing resources (Chapter 37). This is exactly why the next section moves state to S3.

What: every term in plain English

• state file — terraform.tfstate. A JSON file that links every resource block in your code to a real object id in AWS.
• resource address — The name of one resource inside state, such as aws_s3_bucket.logs or module.vpc.aws_subnet.public[0].
• serial — A number inside state that goes up by one on every write. Terraform uses it to refuse an older copy.
• lineage — A random id given to a state when it is first created. Two states with different lineage are different projects.
• terraform.tfstate.backup — The previous copy of local state. Terraform writes it just before it saves a new one.
• refresh — Terraform asks AWS for the current value of every resource in state before it plans.
• sensitive in state — Passwords and keys are stored in plain text inside state, even when the output is hidden on screen.

Example 1: Look inside a real state file

At a Wipro client, a new joiner was told "never touch state" but nobody showed him what it is. Open one yourself with a free provider so the file stops being a mystery.

1. Make a folder named state-lab.
2. Paste main.tf below.
3. Run init and apply.
4. Open terraform.tfstate with jq and read the keys.

# main.tf
terraform {
  required_providers {
    random = {
      source  = "hashicorp/random"
      version = "~> 3.6"
    }
  }
}

resource "random_pet" "app" {
  prefix = "badge"
}

resource "random_password" "db" {
  length  = 16
  special = false
}

output "app_name" {
  value = random_pet.app.id
}

terraform init
terraform apply -auto-approve
jq '{version, serial, lineage, resources: [.resources[] | .type + "." + .name]}' terraform.tfstate

Output

{
  "version": 4,
  "serial": 3,
  "lineage": "6f1c2a8e-7d4b-1e2f-9a10-3c5d7e9f0b12",
  "resources": [
    "random_password.db",
    "random_pet.app"
  ]
}

What it shows: State is plain JSON. version is the file format, serial counts writes, lineage identifies the project, and resources lists what Terraform owns.

Example 2: See that state stores secrets in plain text

A Paytm security review once flagged a state file in a shared folder because it held a database password. Prove it to yourself, then you will never commit state again.

1. Use the same folder.
2. Ask Terraform for the password output only through state.
3. Search the state file for the result field.

terraform state show random_password.db
jq -r '.resources[] | select(.type=="random_password") | .instances[0].attributes.result' terraform.tfstate

Output

# random_password.db:
resource "random_password" "db" {
    id          = "none"
    length      = 16
    result      = (sensitive value)
    special     = false
}
Xk3PqL9vT2mWbR7a

What it shows: The CLI hides the value, but the file holds it in clear text. That is why state goes to an encrypted, private S3 bucket and never to Git.

Example 3: Use the state commands you will need every week

When a Flipkart engineer asks "is this bucket managed by Terraform?", the answer comes from state list and state show, not from guessing.

1. List all addresses.
2. Show one resource.
3. Print outputs from state.
4. Pull a copy of state to a file.

terraform state list
terraform state show random_pet.app
terraform output
terraform state pull > copy.tfstate
ls -l copy.tfstate

Output

random_password.db
random_pet.app
# random_pet.app:
resource "random_pet" "app" {
    id        = "badge-proud-falcon"
    length    = 2
    prefix    = "badge"
    separator = "-"
}
app_name = "badge-proud-falcon"
-rw-r--r-- 1 ravi ravi 1874 Oct 25 10:12 copy.tfstate

What it shows: state pull works for both local and remote state, so it is the safe way to take a copy before any risky change.

Example 4: Recover after deleting local state by mistake

This is the Netflix-style story from the top of the lesson. Practise it on free resources so a real outage does not scare you.

1. Delete terraform.tfstate on purpose.
2. Run plan and read the summary.
3. Restore from terraform.tfstate.backup or your pulled copy.
4. Plan again and confirm zero changes.

rm terraform.tfstate
terraform plan | tail -1
cp copy.tfstate terraform.tfstate
terraform plan | tail -1

Output

Plan: 2 to add, 0 to change, 0 to destroy.
No changes. Your infrastructure matches the configuration.

What it shows: Without state Terraform thinks nothing exists. With the copy back, it matches again. On AWS you would import instead if no copy existed.

Command cheat sheet

Verify: did it work?

1. State has resources

   terraform state list | wc -l
   

   Output

   2
   

2. No state in Git

   git check-ignore terraform.tfstate
   

   Output

   terraform.tfstate
   

When it is red 1

Error: state snapshot was created by Terraform v1.9.5, which is newer than current v1.6.0

Cause. Someone applied with a newer Terraform version. Older versions cannot read the newer file format.

Fix, step by step

1. Run terraform version on both machines.
2. Upgrade your Terraform to the same or newer version.
3. Pin the version with required_version in the terraform block.
4. Plan again.

When it is red 2

Error: Failed to load state: state snapshot has lineage "aaa..." but expected "bbb..."

Cause. You copied a state file from a different project into this folder.

Fix, step by step

1. Stop and do not apply.
2. Find the right state copy for this project.
3. Compare lineage values with jq.
4. Put the matching file back and plan.

When it is red 3

Plan: 12 to add, 0 to change, 0 to destroy.  (on a project that is already live)

Cause. State is missing or the backend points to the wrong key.

Fix, step by step

1. Do not apply.
2. Run terraform state list to see if state is empty.
3. Check the backend key in backend.tf.
4. Restore state or import the resources.

Cleanup

terraform destroy -auto-approve
rm -f copy.tfstate

Practice tasks

Homework: try at home

Recap

• State links code addresses to real cloud ids.
• Serial counts writes; lineage names the project.
• Secrets sit in state as plain text.
• state list, state show and state pull are the daily tools.
• Lost state means plan wants to create everything again.

FAQ

Can I edit terraform.tfstate by hand?

Avoid it. Use terraform state mv, state rm or import. A hand edit can break the JSON or the serial.

Why is there a .backup file?

Terraform keeps the previous local copy before it writes a new one, so you can go back one step.

Does state hold my code?

No. It holds what was created and its attributes. Your code stays in .tf files.

Is state needed for destroy?

Yes. Terraform destroys only what is listed in state.

Where should state live in a team?

In a remote backend such as S3 with encryption and locking. The next lesson shows it.

Interview questions

1. What is Terraform state and why is it needed?

   It maps each resource address to a real id. Terraform needs it to know what it owns, to plan changes and to destroy.

2. What happens if state is lost?

   Plan shows everything as new. Restore a backup or import the existing resources before applying.

3. Why should state not be in Git?

   It can contain secrets in plain text and two people can commit conflicting copies.

4. What are serial and lineage?

   Serial counts writes so an older copy is refused. Lineage is a unique id for one state.

5. How do you take a safe copy of remote state?

   Run terraform state pull and save the output to a dated file.

Samajla ka?

Ravi Sir's Cards for this lesson

Revision cardInterview card

मराठी cards