Terraform Aliased Provider Passing to Nested Modules Prompt
Wire aliased providers (multi-region, multi-account) down through nested module trees using explicit `configuration_aliases` and `providers = {}` maps instead of implicit inheritance.
- Target user
- Engineers building multi-region or multi-account module hierarchies
- Difficulty
- Advanced
- Tools
- Claude, ChatGPT
The prompt
You are a Terraform expert who designs module provider plumbing explicitly. You know that implicit provider inheritance into child modules is convenient for single-region setups but breaks down the moment a module needs two regions, two accounts, or an aliased provider — and that the fix is `configuration_aliases` plus an explicit `providers = {}` map at every call site.
I will provide:
- The module hierarchy (root → module A → module B) and which levels need which providers
- The provider aliases involved (e.g. `aws.primary`, `aws.replica`, `aws.dns_account`)
- Whether any leaf resource needs to span regions or accounts within a single module
Your job:
1. **Map the provider flow** — draw which alias each module level requires and where it originates. Identify any module currently relying on implicit inheritance that will break once a second alias is introduced.
2. **Declare the contracts** — in each child module's `terraform` block, add `required_providers` with `configuration_aliases = [ aws.this, aws.peer ]` for every aliased provider the module consumes. Explain why declaring the alias is what makes the module's provider dependency explicit and reviewable.
3. **Wire the call sites** — at every `module` block, supply the full `providers = { aws = aws.primary, aws.peer = aws.replica }` map. Show how the names on the left are the module's internal expectations and the values on the right are the caller's configured providers.
4. **Handle the nested hop** — show how an alias passed into module A gets forwarded again into module B, so the chain stays explicit end to end. Call out that there is no automatic re-inheritance once you start passing providers explicitly.
5. **Validate** — confirm `terraform validate` and `terraform plan` resolve every provider with no "missing required provider configuration" or "provider configuration not present" errors, and that resources land in the intended [REGIONS_OR_ACCOUNTS].
Output as: (a) the provider-flow map, (b) the `required_providers`/`configuration_aliases` block for each module, (c) the `providers = {}` map for each call site including the nested hop, (d) the resource-to-provider assignment proof, (e) the migration order if an existing single-provider module is being split.
Review the resulting plan before applying — moving a resource onto a different aliased provider can re-target it to a new region or account and recreate it.
Why this prompt works
Provider inheritance is one of Terraform’s most quietly dangerous conveniences. In a single-region module everything “just works” because the child module silently inherits the default aws provider from the root. The trap springs the day you introduce a second alias — a replica region, a DNS account, a peered VPC — and discover the child module has no way to ask for a specific provider. The prompt forces the model to start from the provider-flow map, because the design error is almost always about which alias originates where, not about the HCL syntax.
The core technique it encodes is the configuration_aliases declaration paired with an explicit providers = {} map at every call site. Declaring configuration_aliases = [aws.this, aws.peer] inside a module turns “this module happens to use whatever provider it inherited” into “this module requires exactly these two providers,” which is a contract reviewers and CI can check. The prompt deliberately covers the nested hop — forwarding an alias from module A into module B — because that is the step people forget, and once you pass any provider explicitly, automatic inheritance is gone for the whole subtree.
The guardrails matter because re-pointing a resource at a different aliased provider is not a cosmetic change: it can relocate the resource to another region or account and force a destroy-and-recreate. Requiring the resource-to-provider proof and a reviewed plan keeps this firmly in AI-drafts-human-verifies territory, where the model does the tedious wiring and the engineer confirms the plan does not quietly move stateful infrastructure across boundaries.