Skip to main content
Leveraging AWS DynamoDB for state locking is a best practice when using Terraform or Terragrunt in team environments. By coordinating locks through DynamoDB, you ensure that only one operation can modify your infrastructure state at a time, eliminating deployment conflicts and race conditions.
  • Guarantees serialized state modifications
  • Prevents concurrent terraform apply or terragrunt apply runs
  • Provides a scalable, highly available lock backend in AWS
The image describes the benefits of using Terraform/Terragrunt locks with AWS DynamoDB, highlighting state file locking, prevention of multiple user access, and the use of DynamoDB for state locking.

​
Understanding Terraform & Terragrunt State Locks

Terraform and Terragrunt implement a locking mechanism to safeguard the .tfstate file during operations that write state changes. When one user or process holds the lock:
  • All other operations are blocked until the lock is released
  • Accidental overwrites and drift are prevented
  • Collaboration becomes predictable and conflict-free
Here’s a quick overview of how the components fit together:
ComponentRoleExample Configuration
S3 BackendStores the Terraform state file securelybucket = "my-terraform-state-bucket"
DynamoDB TableManages concurrent locksdynamodb_table = "terraform-locks"
Key PathNamespaces state per environment/modulekey = "${path_relative_to_include()}/state"

​
Configuring Remote State in Terragrunt

Terragrunt can automatically create the required DynamoDB table when you define your remote state. Add the following block to your terragrunt.hcl: 
remote_state {
  backend = "s3"
  config = {
    bucket         = "my-terraform-state-bucket"
    key            = "${path_relative_to_include()}/terraform.tfstate"
    region         = "us-west-2"
    dynamodb_table = "terraform-locks"
    encrypt        = true
  }
}
Terragrunt checks for the existence of the DynamoDB table and creates it if missing—no manual setup required. Ensure your IAM role has permissions for dynamodb:CreateTable.

​
Handling Stuck Locks

Network interruptions or process crashes can leave stale locks in DynamoDB. To resolve this, use the Terraform CLI’s force-unlock command: 
terraform force-unlock LOCK_ID
Replace LOCK_ID with the identifier from the error message. This removes the lock entry in DynamoDB and lets you proceed.
force-unlock bypasses safety checks. Only use it when you are certain no other process is applying changes.

​
Further Reading and References

Watch Video