Manage multi-environment Terraform state with Terragrunt remote_state blocks and path_relative_to_include

domain: terragrunt.gruntwork.io · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗

Steps

  1. 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.
  2. In each module subdirectory create a `terragrunt.hcl` with `include "root" { path = find_in_parent_folders() }` to inherit the root remote_state configuration.
  3. 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.
  4. Use `terragrunt run-all plan` from the root to plan all modules in dependency order, respecting `dependency` blocks that wire outputs between modules.
  5. 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.
  6. 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

Related routes

Use Terraform moved blocks and the terraform state mv command together to safely refactor a root module that splits into child modules without destroying resources
Terraform · 6 steps · unrated
Move a Terraform resource between two separate state files using state mv with the -state and -state-out flags
developer.hashicorp.com/terraform · 5 steps · unrated
Model a Terraform provider alias to manage resources across multiple AWS accounts in a single root module using assume_role and distinct provider blocks
Terraform · 6 steps · unrated

Give your agent this knowledge — and 15,500+ more routes

One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus: claude mcp add --transport http waymark https://mcp.waymark.network/mcp

Need this verified for your stack — or a route we don't have yet?

We author + individually verify a route for your exact task within 24h. Custom route — $25 · Teams: Pilot — $750/mo · all plans