Terraform state

Both problems have the same cause: a file called terraform.tfstate that lived only on Maya’s laptop.

This lesson is about what that file is, and the four things a team does to keep it safe.

After an apply, Terraform writes terraform.tfstate: a record of every resource it created, linked to that resource’s real ID in AWS.

Your code says an ECR repository named quickcart-orders. Your AWS account may have thousands of things in it. State is how Terraform knows which one is yours, and whether it already exists.

Every plan compares three things

That last row is why state matters so much. Without it, Terraform can’t tell that something already exists.

Why two people at once breaks it

What’s inside it

Every attribute of every resource: IDs, names, addresses, settings AWS filled in — and any secret that passed through Terraform, in plain text. So state has to be treated like a password file, because in part it is one.

The fix, in four parts

The backend block, every setting explained

You tell Terraform where state lives with a backend block, usually in a file called backend.tf:

terraform {
  backend "s3" {
    bucket       = "quickcart-tfstate-111122223333"
    key          = "dev/terraform.tfstate"
    region       = "us-east-1"
    encrypt      = true
    use_lockfile = true
  }
}

The chicken and the egg

The bucket that holds state can’t be created by the Terraform code that needs it — where would that state live? So you create it once, by hand, and never manage it with Terraform. It’s the one place where clicking in the console is correct.

First, the three-way comparison. Pick what happens, and see what the next plan does about it.

$ terraform plan

No changes. Your infrastructure matches the configuration.

Now the race. Maya and Leo press apply at the same moment. Play it with locking off, then again with locking on, and watch the state file.

What to notice: with locking off, both applies finished successfully — no error, no warning. That’s what makes it dangerous. Nothing tells you anything went wrong until a later plan tries to create something that already exists.

Pennies — one S3 bucket holding a few small files, and an empty ECR repository, which is free.

You’ll build a tiny Terraform project, move its state into S3, watch the lock refuse a second command, and bring back an old version of the state. About 30 minutes.

You need Terraform 1.10 or later and a working AWS login in your terminal. Set up your computer covers both. Check with:

terraform version

Terraform v1.16.4
on linux_amd64

Any version from 1.10 upwards works. Yours may be newer, and the second line names your system, such as darwin_arm64 on a Mac.

1. Make a small project with local state

   If you already have a Terraform folder from Your first resource, you can use it and skip to step 2. Otherwise, make a new folder and move into it:

   TerminalCopy

   mkdir quickcart-tf

   Part	What it means
   mkdir	make a directory
   quickcart-tf	its name, inside the folder you’re in now

   TerminalCopy

   cd quickcart-tf

   Part	What it means
   cd	change directory — every later command runs in here
   quickcart-tf	the folder you just made

   In that folder, create main.tf:

   main.tfCopy

   terraform {
     required_version = ">= 1.10.0"
   
     required_providers {
       aws = {
         source  = "hashicorp/aws"
         version = "~> 6.0"
       }
     }
   }
   
   provider "aws" {
     region = "us-east-1"
   }
   
   resource "aws_ecr_repository" "orders" {
     name                 = "quickcart-orders"
     image_tag_mutability = "IMMUTABLE"
     force_delete         = true
   
     tags = {
       Project = "quickcart"
     }
   }

   Setting	What it does	If you leave it out	When you’d change it
   required_version	Refuse to run on a Terraform older than 1.10, which has no use_lockfile	An old Terraform would fail later with a confusing error about the backend	When you start relying on a newer feature
   required_providers → aws	Which plugin talks to AWS: hashicorp/aws, any 6.x version	Terraform guesses the source and takes the newest version, which may one day bring breaking changes	When you deliberately upgrade to a new major version
   provider "aws" → region	Where the resources are created	Terraform uses the region from your AWS login settings, which may not be the one you expect	To build somewhere else
   aws_ecr_repository "orders"	An ECR repository — a private store for container images. orders is Terraform’s name for it; quickcart-orders is AWS’s	—	—
   name	The repository’s name in AWS	Required	Never after creation — changing it replaces the repository
   image_tag_mutability	IMMUTABLE means a tag like v1 can never be pointed at a different image	Defaults to MUTABLE: someone can push a different image under the same tag	Rarely. Storing images: ECR explains why
   force_delete	Let terraform destroy delete the repository even if it holds images	Destroy fails while any image is inside	Set to false for production repositories
   tags	Labels, so you can find and cost everything belonging to QuickCart	No labels; harder to find later	Add owner, environment and cost-centre tags in real projects

   Set up the folder and build the repository:

   TerminalCopy

   terraform init

   Part	What it means
   terraform init	download the AWS provider and prepare this folder

   You should see

   Terraform has been successfully initialized!

   TerminalCopy

   terraform apply

   Part	What it means
   terraform apply	work out a plan, show it, and carry it out once you type yes

   It shows the plan and asks you to confirm. Type yes.

   You should see

   Plan: 1 to add, 0 to change, 0 to destroy.
   
   Do you want to perform these actions?
     Terraform will perform the actions described above.
     Only 'yes' will be accepted to approve.
   
     Enter a value: yes
   
   aws_ecr_repository.orders: Creating...
   aws_ecr_repository.orders: Creation complete after 1s [id=quickcart-orders]
   
   Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

   You now have a file called terraform.tfstate in the folder. That’s Terraform’s memory, sitting on your laptop — Maya’s situation.

2. Create the state bucket in the console

   First, find your account number: open the account menu at the top right of the console and copy the 12-digit Account ID. In this course it’s shown as 111122223333; use yours instead.

   AWSIn the AWS console: S3→General purpose buckets→Create bucket

   Field	Enter
   Bucket type	General purpose
   Bucket name	quickcart-tfstate- followed by your account ID, like quickcart-tfstate-111122223333
   Object Ownership	ACLs disabled — the default
   Block all public access	On — the default. Leave it
   Bucket Versioning	Enable
   Default encryption	SSE-S3 — the default. Leave it

   Choose Create bucket.

   You should see

   The bucket in the list. Open it, go to Properties, and check that Bucket Versioning says Enabled.

   Versioning is the setting people skip, and regret. It’s the only way back if the state is ever damaged.

3. Add the backend block

   In the same folder as main.tf, create backend.tf. Put your own bucket name in place of the highlighted account number:

   backend.tfCopy

   terraform {
     backend "s3" {
       bucket       = "quickcart-tfstate-111122223333"
       key          = "dev/terraform.tfstate"
       region       = "us-east-1"
       encrypt      = true
       use_lockfile = true
     }
   }

   Every setting is explained in the idea, above.

4. Move the state across

   TerminalCopy

   terraform init -migrate-state

   Part	What it means
   terraform init	set the folder up again, now with the S3 backend
   -migrate-state	copy the state you already have into the new backend

   It asks before copying. Type yes.

   It asks, then confirms

   Initializing the backend...
   Do you want to copy existing state to the new backend?
     Pre-existing state was found while migrating the previous "local" backend to the
     newly configured "s3" backend. No existing state was found in the newly
     configured "s3" backend. Do you want to copy this state to the new "s3"
     backend? Enter "yes" to copy and "no" to start with an empty state.
   
     Enter a value: yes
   
   
   Successfully configured the backend "s3"! Terraform will automatically
   use this backend unless the backend configuration changes.

5. Check it worked

   AWSIn the AWS console: S3→General purpose buckets→your bucket→dev/

   You should see

   A file called terraform.tfstate.

   Now ask Terraform to compare everything again, reading state from S3 this time:

   TerminalCopy

   terraform plan

   Part	What it means
   terraform plan	compare code, state and AWS, and show what would change — without changing anything

   You should see

   No changes. Your infrastructure matches the configuration.

   Same result as before. Only the state’s location changed.

6. Watch the lock refuse a second command

   To see the lock you need a command that stops half-way and holds it. apply does that while it waits for you to type yes — but only when there’s a change to approve. So first make a small change: add a second tag, Team, at the end of main.tf. The whole file now reads:

   main.tfCopy

   terraform {
     required_version = ">= 1.10.0"
   
     required_providers {
       aws = {
         source  = "hashicorp/aws"
         version = "~> 6.0"
       }
     }
   }
   
   provider "aws" {
     region = "us-east-1"
   }
   
   resource "aws_ecr_repository" "orders" {
     name                 = "quickcart-orders"
     image_tag_mutability = "IMMUTABLE"
     force_delete         = true
   
     tags = {
       Project = "quickcart"
       Team    = "platform"
     }
   }

   Now open two terminal windows, both in the quickcart-tf folder.

   Window 1 — start an apply. When it asks Enter a value:, don’t answer yet:

   TerminalCopy

   terraform apply

   Part	What it means
   terraform apply	takes the lock, plans the tag change, then waits for you — still holding the lock

   Window 2 — while window 1 is waiting:

   TerminalCopy

   terraform plan

   Part	What it means
   terraform plan	also needs the lock, even though it changes nothing, so it reads a state nobody is halfway through writing

   Window 2 is refused

   Error: Error acquiring the state lock
   
   Lock Info:
     ID:        6f1c2d9e-3b7a-4c55-9e2f-8a0d4b1c7e21
     Path:      quickcart-tfstate-111122223333/dev/terraform.tfstate
     Operation: OperationTypeApply
     Who:       maya@maya-laptop
     Version:   1.16.4
     Created:   2026-09-25 10:22:11.482913 +0000 UTC
     Info:
   
   Terraform acquires a state lock to protect the state from being written
   by multiple users at the same time. Please resolve the issue above and try
   again. For most commands, you can disable locking with the "-lock=false"
   flag, but this is not recommended.

   Your ID, name and times will differ, and there’s an extra Error message line from S3 explaining the refusal. That refusal is the whole point. It tells you who holds the lock and since when.

   Now go back to window 1 and type yes. The tag is added and the lock is released. Run terraform plan in window 2 again, and this time it works.

7. Bring back an old version

   Because of the tag change, the bucket now holds more than one version of the state.

   AWSIn the AWS console: S3→your bucket→dev/→terraform.tfstate→Versions

   You should see

   Two or more versions, each with a time. The newest is at the top, marked Current version.

   Tick the older version, choose Download, and move the file into your project folder, renamed to recovered.json. Then replace the state with it:

   TerminalCopy

   terraform state push recovered.json

   Part	What it means
   terraform state push	replace the state in S3 with a file you give it
   recovered.json	the older version you downloaded

   Straight afterwards, see how the recovered state compares with reality:

   TerminalCopy

   terraform plan

   Part	What it means
   terraform plan	refresh the state from AWS, then compare it with the code

   You should see

   No changes. Your infrastructure matches the configuration.

   The old version didn’t know about the Team tag, but plan reads the real repository from AWS first and finds the tag already there. The recovery was safe because the old state still pointed at the same real resource.

8. Clean-up step: Clean up

   Delete the repository Terraform built:

   TerminalCopy

   terraform destroy

   Part	What it means
   terraform destroy	plan the removal of everything in the state, and carry it out once you type yes

   You should see

   Destroy complete! Resources: 1 destroyed.

   Keep the bucket if you’re carrying on with the course. It costs pennies, and later lessons and the pipeline project use it.

   If you’re not carrying on, empty it and delete it: S3 → your bucket → Empty, type permanently delete, then Delete the bucket itself. Emptying a versioned bucket removes every old version too.

If a lock ever gets stuck

A laptop goes to sleep mid-apply, or a terminal is closed. The lock is never released, and everyone is refused. First, check that nobody is really applying — the error tells you who holds the lock. Then remove it using the ID from the error:

terraform force-unlock LOCK_ID

Do you really want to force-unlock?
  Terraform will remove the lock on the remote state.
  This will allow local Terraform commands to modify this state, even though it
  may still be in use. Only 'yes' will be accepted to confirm.

  Enter a value: yes

Terraform state has been successfully unlocked!