Skip to main content
Implementing state locking is critical for any Infrastructure as Code (IaC) workflow. By leveraging AWS DynamoDB, Terraform and Terragrunt coordinate changes to prevent conflicting updates and ensure consistency.
The image describes the features of Terraform/Terragrunt locks using AWS DynamoDB, highlighting state file locking, prevention of multiple user access, and the use of DynamoDB for state locking.
Terraform and Terragrunt acquire a lock before performing any write operations on the state file. In AWS-based pipelines, DynamoDB acts as the lock manager. This setup guarantees:
  • Exclusive write access to the state
  • Automatic creation of the lock table (when using Terragrunt’s remote_state)
  • Reliable, distributed coordination across teams and CI/CD environments

​
Configuring remote_state in Terragrunt

To enable DynamoDB locking, define a remote_state block in your terragrunt.hcl. Terragrunt will create the DynamoDB table if it doesn’t already exist. 
remote_state {
  backend = "s3"
  config = {
    bucket         = "my-terraform-state-bucket"
    key            = "envs/prod/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "my-terraform-lock-table"
  }
}
Terragrunt automatically provisions the DynamoDB table specified by dynamodb_table. You only need AWS IAM permissions for S3 and DynamoDB table creation.
Backend OptionDescriptionExample Value
bucketS3 bucket name for state storage"my-terraform-state-bucket"
keyPath within bucket for the .tfstate file"envs/prod/terraform.tfstate"
regionAWS region for both S3 and DynamoDB operations"us-east-1"
encryptEnable server-side encryption (SSE) for the filetrue
dynamodb_tableDynamoDB table name for state locking"my-terraform-lock-table"

​
Handling Stuck Locks

If a Terraform or Terragrunt process crashes mid-run, the DynamoDB lock may remain, blocking subsequent operations. Use the force-unlock command to clear a stuck lock. 
# Retrieve the LOCK ID from the error output, then run:
terragrunt force-unlock LOCK_ID --terragrunt-non-interactive
Forcing an unlock can lead to concurrent modifications if another process is still running. Always verify no other operations are active before using force-unlock.

​
Benefits of DynamoDB State Locking

BenefitDescription
Single-Writer EnforcementPrevents multiple users or CI jobs from applying at the same time
Automated Table ManagementTerragrunt creates and manages the DynamoDB lock table, reducing manual steps
Robust CI/CD IntegrationLocks persist across distributed pipelines, ensuring consistent state access
Safe Recovery from Failuresforce-unlock provides a backdoor to unblock state operations
By combining Terraform, Terragrunt, Amazon S3, and DynamoDB locks, teams can focus on building infrastructure rather than wrestling with state conflicts.

Watch Video