Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 37 ยท State Management

Remote State, Backends and State Locking

Store Terraform state remotely with an S3 or HCP Terraform backend, understand state locking, migrate local state and share outputs with terraform_remote_state.

A local terraform.tfstate works for a lone learner. The moment a second person or a CI job joins, it breaks: two people applying at once can overwrite each other's changes, and a laptop dies with the only copy of your infrastructure's memory. The fix is a remote backend: a shared, durable place for the state, with locking so only one run changes it at a time.

This lesson shows how backends work, how to configure the common ones, what locking really protects, and how to move an existing state without losing it.

What a backend does

A backend decides where state is stored and where operations such as plan and apply run. The default is local. Common remote backends:

Backend Where state lives Locking
s3 An S3 bucket (versioned, encrypted) Native lockfile (use_lockfile), or DynamoDB in older setups
azurerm Azure Blob Storage Blob lease
gcs Google Cloud Storage bucket Object-based
http Any HTTP service you provide Optional
cloud (HCP Terraform) Managed by HashiCorp Built in
pg PostgreSQL table Advisory locks

You choose one in a terraform block. Backend blocks cannot use variables or references, because Terraform reads them before it evaluates anything else.

HCL
terraform {
  required_version = ">= 1.10"

  backend "s3" {
    bucket       = "acme-terraform-state"
    key          = "prod/network/terraform.tfstate"
    region       = "eu-central-1"
    encrypt      = true
    use_lockfile = true
  }
}

The key is the object path, so one bucket can hold many independent states: prod/network, prod/app, staging/app. Smaller states mean a smaller blast radius and faster plans.

Create the bucket outside the configuration that uses it, either by hand or in a tiny separate "bootstrap" configuration. Enable versioning on it, so a bad write can be rolled back to an earlier object version.

For values that differ per environment, leave them out of the file and supply them at init time (partial configuration):

Terminal
terraform init \
  -backend-config="bucket=acme-terraform-state" \
  -backend-config="key=staging/app/terraform.tfstate"

How locking works

Before any operation that writes state, Terraform asks the backend for a lock. If someone else holds it, you wait or fail:

TEXT
Error: Error acquiring the state lock

Lock Info:
  ID:        6f1a8f0c-0000-1111-2222-333344445555
  Operation: OperationTypeApply
  Who:       dana@laptop
  Created:   2026-03-02 09:14:11 UTC

Example output; your IDs and users will differ. Locking prevents two applies from interleaving and corrupting state. It does not make two people's changes merge: the second run simply waits and then plans against the new state.

If a run crashes, a stale lock may remain. After you are sure nobody is running Terraform, release it:

Terminal
terraform force-unlock 6f1a8f0c-0000-1111-2222-333344445555

Use -lock-timeout=5m in CI so a job waits briefly instead of failing at once.

sequenceDiagram
  participant A as Run A
  participant B as Run B
  participant S as Backend
  A->>S: acquire lock
  S-->>A: ok
  B->>S: acquire lock
  S-->>B: denied (held by A)
  A->>S: write state (serial 8)
  A->>S: release lock
  B->>S: acquire lock
  S-->>B: ok

Run B waits until Run A has written state and released the lock.

A lock and serial model you can run

Real backends differ in details, but the logic is simple: one holder, and a serial that must not go backwards. This stand-in models both.

Python Lock and serial simulator

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Migrating local state to a backend

Add the backend block, then run:

Terminal
terraform init -migrate-state

Terraform detects the change, shows the old and new backend, and asks whether to copy the existing state. Answer yes. Afterwards check with terraform state list, and delete the local copy only once you have verified the remote one. Moving between backends works the same way, and terraform init -reconfigure skips migration when you want to start fresh against a different backend.

Reading another configuration's outputs

When one configuration (for example network) creates a VPC that another (app) needs, you have two options. The data source terraform_remote_state reads the other state's outputs:

HCL
data "terraform_remote_state" "network" {
  backend = "s3"
  config = {
    bucket = "acme-terraform-state"
    key    = "prod/network/terraform.tfstate"
    region = "eu-central-1"
  }
}

resource "aws_instance" "web" {
  subnet_id = data.terraform_remote_state.network.outputs.public_subnet_id
}

It needs read access to the whole state file, which can contain secrets. Many teams prefer a looser coupling: publish IDs to a parameter store or tag resources, and look them up with ordinary data sources (Data Sources if you need a refresher).

Python Simulating remote state outputs

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

HCP Terraform and cloud

HCP Terraform (formerly Terraform Cloud) stores state, locks it, keeps its history, and can run plans and applies remotely. You select it with a cloud block (organization and workspace names). Teams that want the same features without HashiCorp's service use S3, GCS or Azure with a CI system, or tools such as Atlantis (CI lesson).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why can a backend block not reference variables?

    The backend is initialized first, so values must be literals or passed with -backend-config.
  2. 2. What does state locking prevent?

    Locking serializes writes; it does not hide the state or merge competing changes.
  3. 3. Which command copies existing local state into a newly configured backend?

    init -migrate-state detects the backend change and offers to copy the state.
  4. 4. When is force-unlock appropriate?

    Force-unlocking during a live run can corrupt state, so verify first.

Summary

  • Remote backends give teams a shared, durable, lockable state.
  • Use one state per component (prod/network, prod/app) to limit blast radius and speed up plans.
  • Enable encryption and versioning on the state bucket.
  • init -migrate-state moves state between backends.
  • terraform_remote_state shares outputs but exposes the whole state to the reader.

Next: State Commands: Move, Import and Remove