Need help implementing isolated workspaces to fix DynamoDB state lock contention

Hello @Fath Swift

Welcome to Microsoft Q&A!

Thank you for your patience, and taking the time to elaborate on your concerns.

DynamoDB state lock contention is a common pain point when multiple Terraform runners try to apply plans in parallel. The supported way to avoid this is to isolate state usage so each runner has its own lock scope.

Practical Implementation Options.

1. Workspaces per Pipeline/Environment

Use terraform workspace to separate state files.

Each workspace automatically uses a different key prefix in the DynamoDB lock table.

In CI/CD, set TF_WORKSPACE=$CI_PIPELINE_ID or $ENVIRONMENT so each runner gets its own isolated workspace.

2. Separate Backend Paths

Configure unique S3 key prefixes for each environment/stage:

hcl

backend "s3" {
  bucket         = "my-terraform-state"
  key            = "env/${var.env}/terraform.tfstate"
  region         = "us-east-1"
  dynamodb_table = "terraform-locks"
}

This ensures dev, test, and prod don’t fight over the same lock.

3. Ephemeral Workspaces for CI/CD

For parallel test runs, generate a unique workspace name tied to the build ID.

Example: terraform workspace new build-${CI_JOB_ID}

Destroy or clean up after the run to avoid clutter.

4. Serialized Deployment for Shared Environments

• If multiple jobs must target the same environment, enforce serialization.
• Use CI/CD pipeline stages with explicit dependencies so only one runner applies at a time.

  Best Practices.

• Keep state files scoped to a single environment or service.
• Avoid “global” state unless absolutely necessary.
• Document workspace naming conventions so teams don’t accidentally overlap.
• Monitor DynamoDB lock table entries to confirm isolation is working.

In Summary: To fix DynamoDB lock contention, configure isolated workspaces or backend paths for each CI/CD runner. For ephemeral builds, generate unique workspace names; for shared environments, enforce serialization. This ensures parallel jobs don’t collide on the same lock.

I hope this helps to better understand the diagnostic options available and the risks involved.

If this information was helpful, please click Accept Answer.

Thank you for choosing Microsoft Q&A.