A child Terraform module has to create resources in a second AWS region. How does the module get that provider configuration, and what must the child module declare to accept it?

## Inheritance is only partial When you call a module without saying anything about providers, the child inherits the parent's **default** (unaliased) configurations. That covers the common case: a module full of `aws_*` resources works out of the box using whatever region the root's default `provider "aws"` block set. Aliased configurations are deliberately excluded from that inheritance. An alias is a local name, and letting child modules reach up into the caller's namespace for it would make the module depend on the caller's private naming. So the caller must pass it, and the child must declare that it expects one. ## The child side: configuration_aliases Inside the child module, the `required_providers` entry grows a `configuration_aliases` list. Each entry creates an additional named provider slot that the module's own resources can reference, but which the module itself never configures: ```hcl terraform { required_providers { aws = { source = "hashicorp/aws" version = ">= 5.0" configuration_aliases = [aws.replica] } } } resource "aws_s3_bucket" "replica" { provider = aws.replica bucket = var.replica_bucket_name } ``` This is the important design point: `configuration_aliases` declares a **requirement**, not a configuration. The module says "I need a second aws configuration and I will call it `replica`"; where that configuration points — which region, which account, which credentials — stays the caller's decision. `configuration_aliases` was introduced in Terraform 0.15; before that, modules with multiple provider instances were far clumsier. ## The parent side: the providers map The `module` block's `providers` argument is a map. Read it as *child name = parent configuration*: ```hcl module "replicated" { source = "./modules/replicated-bucket" providers = { aws = aws.us aws.replica = aws.eu } } ``` Here the child's default `aws` is bound to the parent's `aws.us`, and the child's `aws.replica` slot to the parent's `aws.eu`. The names on the two sides are independent — the caller can rearrange freely, which is exactly what makes the module reusable across a primary/secondary swap. Two behaviours surprise people: - **Supplying `providers` turns inheritance off.** Once the map is present, only what it lists exists inside the child. If the child also uses a `google_*` resource and you did not map `google`, that is an error, not a silent fallback. - **The map is not optional if the child declares `configuration_aliases`.** A missing entry fails at plan time with a message naming the module and the missing configuration. That early failure is the feature: without the declaration the module would just create everything in the default region and nobody would notice until a DR test. ## Nesting The same map is how you reach further down. A grandparent passes into a parent, and the parent passes on to its own children with another `providers` block. Nothing is implicit past the default configuration, so a deep tree that needs a second region carries the mapping at every level. That verbosity is a signal worth listening to: if three levels of module all need an explicit alias, the design may be better served by two invocations of a single-region module, one per region. ## Why not just declare a provider inside the child? Because a module that configures its own provider cannot be used with `count`, `for_each` or `depends_on`, cannot have its credentials or region chosen by the caller, and cannot be cleanly removed later — Terraform still needs that configuration to destroy what it created. The `configuration_aliases` + `providers` pair exists precisely so a module can *require* a provider instance without *owning* one. ## What good looks like A well-built multi-region module has no `provider` blocks at all, a `required_providers` entry that lists exactly the configurations it needs, resources that reference those names, and documentation that states the map a caller must supply. Its README shows the `providers = { ... }` snippet, because that map is as much part of the module's interface as its input variables.