Terraform State: Remote State, Locking & Backends

Terraform state is a mapping between your configuration and the real-world infrastructure it manages, stored in a state file that Terraform uses to plan changes and track resource lifecycle.

What You'll Learn

In this tutorial, you will learn what Terraform state is, why local state fails for teams, how remote backends with state locking prevent corruption, and how to migrate from local to remote state.

Why It Matters

State is Terraform's source of truth. Corrupted, lost, or conflicting state files cause duplicate resources, orphaned infrastructure, and failed deployments. Production teams must use remote state with locking to prevent these failures.

Real-World Use

Durga Antivirus Pro's platform team stores Terraform state in an S3 backend with DynamoDB locking. Twelve engineers apply changes concurrently without conflicts, and state history enables rollbacks to any previous infrastructure version.

What Is Terraform State?

The state file (<a href="/devops/terraform/">terraform</a>.tfstate) contains resource IDs, attributes, metadata, and dependencies. Terraform uses it to:

• Map configuration to real-world resources
• Track resource metadata and dependencies
• Detect configuration drift
• Cache attribute values for performance

{
  "version": 4,
  "terraform_version": "1.9.0",
  "resources": [
    {
      "module": "",
      "mode": "managed",
      "type": "aws_instance",
      "name": "web",
      "provider": "provider[\"registry.terraform.io/hashicorp/aws\"]",
      "instances": [
        {
          "attributes": {
            "id": "i-0abcd1234efgh5678",
            "ami": "ami-0c55b159cbfafe1f0",
            "instance_type": "t2.micro",
            "public_ip": "54.123.45.67]
          }
        }
      ]
    }
  ]
}

Expected output: The state file is valid JSON. You should never edit it manually.

Local State Problems

Team Conflicts

Two team members running <a href="/devops/terraform/">terraform</a> apply simultaneously with local state causes corruption. The second apply overwrites the first's changes, creating a mismatch between state and reality.

State Loss

Losing the local state file means Terraform cannot manage existing resources. You must re-import every resource or destroy and recreate infrastructure.

No History

Local state gives you one version. If an apply goes wrong, you cannot roll back to a previous state without manual backup.

Remote State

Remote state stores the state file in a shared backend accessible by the entire team:

terraform {
  backend "s3" {
    bucket         = "dodatech-terraform-state"
    key            = "prod/network/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "terraform-state-lock"
  }
}

Expected output: Running <a href="/devops/terraform/">terraform</a> init configures the S3 backend, downloads the existing state, and enables remote operations.

State Locking

State locking prevents concurrent modifications that corrupt the state file:

terraform {
  backend "s3" {
    bucket         = "dodatech-terraform-state"
    key            = "prod/network/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "terraform-state-lock"
  }
}

Expected output: When engineer A runs <a href="/devops/terraform/">terraform</a> apply, DynamoDB locks the state. Engineer B sees a "locking" error until A completes. The lock releases automatically.

Locking with Terraform Cloud

terraform {
  cloud {
    organization = "dodatech"
    workspaces {
      name = "production"
    }
  }
}

Expected output: Terraform Cloud handles state storage and locking automatically. The CLI applies through the Cloud API, which serializes operations.

State Commands

View Current State

terraform state list

Expected output: Lists all resources in the state file, for example aws_instance.web, aws_s3_bucket.logs.

Move a Resource

terraform state mv aws_instance.web aws_instance.legacy_web

Expected output: Renames the resource in state without modifying the infrastructure. The next plan shows the resource under the new name.

Remove a Resource from State

terraform state rm aws_instance.web

Expected output: Removes the resource from state without destroying it. Terraform no longer manages it.

Common Mistakes

1. Committing State Files to Git

State files contain sensitive data and should never be in version control. Use a .gitignore entry for *.tfstate*.

2. Running Apply Without Remote State

Local state on a shared machine gets overwritten. Always use remote state with locking for team environments.

3. Manually Editing State Files

Direct edits to state files cause corruption. Use <a href="/devops/terraform/">terraform</a> state commands instead.

4. Ignoring State Locking Errors

When you see a locking error, do not force-unlock unless you are certain no apply is running. Forced unlocks can corrupt state.

5. Not Backing Up State

Even with remote state, periodic backups protect against accidental deletion or corruption of the backend.

Practice Questions

1. What information does the Terraform state file contain? Resource IDs, attributes, metadata, provider information, and dependency relationships between resources.

2. Why is state locking important for teams? It prevents concurrent modifications that corrupt the state file, ensuring one apply runs at a time.

3. What is the difference between local and remote state? Local state is stored on disk and cannot be shared. Remote state is stored in a backend (S3, Terraform Cloud) and supports locking and team access.

4. How do you safely rename a resource in Terraform? Use <a href="/devops/terraform/">terraform</a> state mv old_name new_name to update the state without destroying and recreating the resource.

5. Challenge: Create an S3 bucket for state storage, a DynamoDB table for locking, configure the backend, apply a resource, and verify state locking by running concurrent applies.

Mini Project: Remote State Migration

Create an S3 bucket and DynamoDB table for state management. Configure the backend, run <a href="/devops/terraform/">terraform</a> init -migrate-state to move from local to remote state, and verify locking by running two concurrent apply operations.

Related Concepts

What's Next

Configure remote state with locking for your Terraform projects, then learn how Modules enable reusable, composable infrastructure components.

Built by the developers of Doda Browser, DodaZIP, and Durga Antivirus Pro.