Terragrunt for Beginners
Managing Remote State with Terragrunt
Setting up DynamoDB Locks
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.
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"
}
}
Note
Terragrunt automatically provisions the DynamoDB table specified by dynamodb_table. You only need AWS IAM permissions for S3 and DynamoDB table creation.
| Backend Option | Description | Example Value |
|---|---|---|
| bucket | S3 bucket name for state storage | "my-terraform-state-bucket" |
| key | Path within bucket for the .tfstate file | "envs/prod/terraform.tfstate" |
| region | AWS region for both S3 and DynamoDB operations | "us-east-1" |
| encrypt | Enable server-side encryption (SSE) for the file | true |
| dynamodb_table | DynamoDB 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
Warning
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
| Benefit | Description |
|---|---|
| Single-Writer Enforcement | Prevents multiple users or CI jobs from applying at the same time |
| Automated Table Management | Terragrunt creates and manages the DynamoDB lock table, reducing manual steps |
| Robust CI/CD Integration | Locks persist across distributed pipelines, ensuring consistent state access |
| Safe Recovery from Failures | force-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.
Links and References
- Terraform Remote State
- Terragrunt Documentation
- AWS DynamoDB Developer Guide
- Managing Locks with S3 and DynamoDB
Watch Video
Watch video content