Multi-account & multi-region layouts

Structure a real estate.

The reason Terragrunt exists shows most clearly in a large layout: many accounts, many regions, many components. The convention is a live repository whose folder structure mirrors your real topology — account / region / environment / component — where each leaf is a small terragrunt.hcl unit, and hcl files at each level contribute shared config (the root has the backend, the account level has the provider/assume-role, the region level has the region, the env level has tags). Modules live in a separate repo, versioned.

live/
  root.hcl                     # backend for all units
  prod-account/
    account.hcl                # provider, assume-role for the prod account
    us-east-1/
      region.hcl               # region + region-specific config
      vpc/terragrunt.hcl
      database/terragrunt.hcl
      app/terragrunt.hcl
    eu-west-1/ ...
  dev-account/ ...
modules/                       # separate, versioned Terraform modules repo

Why mirror the topology

Mapping folders to accounts/regions/components makes the estate navigable — the path tells you exactly what a unit is and where it deploys — and lets each level of the hierarchy own the config that belongs there (account credentials at the account level, region at the region level). path_relative_to_include() then derives unique state keys from that structure automatically. It is the layout that turns “hundreds of state files” from chaos into something a new engineer can read.