State locking with DynamoDB in Terraform - Commands & Configuration

Introduction

When multiple people or systems work on the same infrastructure using Terraform, they can accidentally overwrite each other's changes. State locking with DynamoDB prevents this by making sure only one person or system can make changes at a time.

When you have a team working together on the same Terraform infrastructure.

When you want to avoid conflicts and errors caused by simultaneous Terraform runs.

When you use Terraform in automated pipelines that might run at the same time.

When you want to keep your Terraform state safe and consistent in a shared environment.

When you use AWS as your cloud provider and want a simple way to lock state.

Config File - main.tf

main.tf

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

provider "aws" {
  region = "us-east-1"
}

resource "aws_dynamodb_table" "terraform_lock" {
  name         = "terraform-lock"
  billing_mode = "PAY_PER_REQUEST"
  hash_key     = "LockID"

  attribute {
    name = "LockID"
    type = "S"
  }
}

This Terraform file does two things:

• It sets up the s3 backend to store the Terraform state file securely in an S3 bucket named example-terraform-state.
• It enables state locking by specifying a DynamoDB table named terraform-lock to prevent simultaneous changes.
• It creates the DynamoDB table terraform-lock with a primary key LockID to manage locks.

Commands

This command initializes Terraform, sets up the backend with S3 and DynamoDB for state storage and locking.

Terminal

terraform init

Expected Output

Initializing the backend...



Successfully configured the backend "s3".



Terraform has been successfully initialized!



You may now begin working with Terraform. Try running "terraform plan" to see

any changes that are required for your infrastructure. All Terraform commands

should now work.

This command applies the Terraform configuration, creating the DynamoDB table for locking and setting up the backend.

Terminal

terraform apply -auto-approve

Expected Output

aws_dynamodb_table.terraform_lock: Creating...

aws_dynamodb_table.terraform_lock: Creation complete after 3s [id=terraform-lock]



Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

→

-auto-approve - Automatically approves the apply without asking for confirmation

This command checks for any changes to the infrastructure while using the locked state to avoid conflicts.

Terminal

terraform plan

Expected Output

No changes. Infrastructure is up-to-date.

Key Concept

If you remember nothing else from this pattern, remember: DynamoDB state locking ensures only one Terraform process changes infrastructure at a time, preventing conflicts.

Common Mistakes

Not creating the DynamoDB table before running Terraform apply.

Terraform cannot lock the state without the DynamoDB table, so concurrent runs can corrupt the state.

Create the DynamoDB table using Terraform or manually before enabling state locking.

Using a DynamoDB table with a different name than specified in the backend configuration.

Terraform will fail to acquire the lock because it looks for the exact table name.

Ensure the DynamoDB table name in the backend matches the actual table name.

Not enabling encryption or versioning on the S3 bucket storing the state.

This can lead to accidental data loss or unauthorized access to the state file.

Enable encryption and versioning on the S3 bucket for safety.

Summary

Configure Terraform backend to use S3 for state storage and DynamoDB for state locking.

Create a DynamoDB table with a primary key to manage locks.

Run terraform init to initialize backend and terraform apply to create resources.

Use terraform plan and apply commands safely with state locking to avoid conflicts.