Create a root `terragrunt.hcl` at the repository root with a `remote_state` block specifying the S3 backend, bucket, region, and a `key` using `path_relative_to_include()` to give each module a unique state path.
In each module subdirectory create a `terragrunt.hcl` with `include "root" { path = find_in_parent_folders() }` to inherit the root remote_state configuration.
Run `terragrunt init` in a module directory; Terragrunt automatically creates the S3 bucket and (if configured) the DynamoDB table if they do not exist, then runs `terraform init` with the generated backend config.
Use `terragrunt run-all plan` from the root to plan all modules in dependency order, respecting `dependency` blocks that wire outputs between modules.
Set `generate` block inside `remote_state` with `path = "backend.tf"` and `if_exists = "overwrite_terragrunt"` to have Terragrunt generate the `backend.tf` file automatically so source modules remain backend-agnostic.
Pin the Terragrunt version in CI using a `.tool-versions` file or a version constraint in `terragrunt.hcl` under `terraform_version_constraint` and `terragrunt_version_constraint`.
Known gotchas
As of Terragrunt v1.0 (April 2026), some HCL configuration syntax changed; validate your `terragrunt.hcl` files against the v1 docs, particularly the `remote_state` block structure.
`run-all` commands run modules in parallel by default; dependency blocks serialize the order but non-dependent modules run concurrently, which can cause S3 bucket creation race conditions on first run.
`path_relative_to_include()` returns the path relative to the root `terragrunt.hcl`; ensure the S3 key does not start with `/` or contain `..` segments that would escape the expected state prefix.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp