How to Use DynamoDB for State Locking in Terraform

To use DynamoDB for state locking in Terraform, configure the backend block with s3 for state storage and specify a dynamodb_table for locking. This setup prevents multiple users from changing the state at the same time by locking the state file in the DynamoDB table.

Syntax

The terraform block configures the backend to use s3 for storing the state file and dynamodb_table for locking. Key parts include:

• bucket: The S3 bucket name where the state file is stored.
• key: The path inside the bucket for the state file.
• region: AWS region for both S3 and DynamoDB.
• dynamodb_table: The DynamoDB table name used for state locking.

terraform

terraform {
  backend "s3" {
    bucket         = "my-terraform-state-bucket"
    key            = "path/to/my/terraform.tfstate"
    region         = "us-west-2"
    dynamodb_table = "terraform-lock-table"
    encrypt        = true
  }
}

Example

This example shows a complete Terraform backend configuration using an S3 bucket for state storage and a DynamoDB table for locking. It ensures that only one Terraform process can modify the state at a time.

terraform

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

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

resource "aws_s3_bucket" "example" {
  bucket = "example-bucket-for-terraform"
  acl    = "private"
}

Output

Terraform will initialize the backend using the specified S3 bucket and DynamoDB table for locking. When you run 'terraform apply', it will acquire a lock in the DynamoDB table to prevent concurrent changes.

Common Pitfalls

• Missing DynamoDB Table: The DynamoDB table must exist before initializing Terraform; otherwise, locking will fail.
• Incorrect Table Name: The dynamodb_table name must exactly match the existing table.
• Region Mismatch: The AWS region for S3 and DynamoDB must be the same or correctly specified.
• Permissions: The AWS credentials used must have permissions to read/write the S3 bucket and read/write the DynamoDB table.

terraform

/* Wrong: DynamoDB table does not exist */
terraform {
  backend "s3" {
    bucket         = "my-bucket"
    key            = "state.tfstate"
    region         = "us-west-2"
    dynamodb_table = "nonexistent-lock-table"
    encrypt        = true
  }
}

/* Right: Create DynamoDB table before use */
resource "aws_dynamodb_table" "terraform_lock" {
  name         = "terraform-lock-table"
  billing_mode = "PAY_PER_REQUEST"
  hash_key     = "LockID"

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

Quick Reference

Setting	Description
bucket	Name of the S3 bucket to store Terraform state
key	Path inside the bucket for the state file
region	AWS region for S3 and DynamoDB
dynamodb_table	DynamoDB table name used for state locking
encrypt	Enable encryption for the state file in S3

Key Takeaways

Configure Terraform backend with S3 for state storage and DynamoDB for locking to prevent concurrent state changes.

Ensure the DynamoDB table exists before initializing Terraform to avoid locking errors.

Use matching AWS regions and correct permissions for both S3 and DynamoDB resources.

Enable encryption on the S3 bucket to secure your Terraform state file.

Check the DynamoDB table name carefully in the backend configuration to avoid misconfiguration.