Why should a reusable Terraform module never contain its own provider block, and what specifically breaks if it does?

## Configuration versus requirement Terraform draws a line that is easy to miss because both live in the same file: - A `provider "aws" { ... }` block **configures** an instance of a provider: region, endpoints, credentials, `assume_role`. - A `required_providers` entry **declares** what a module needs: source address, version constraint, and optionally `configuration_aliases`. The rule that follows is: **root modules configure, child modules declare.** A reusable module states its needs; the composition at the top decides how those needs are met. ## What breaks, concretely ### Repetition meta-arguments stop working Since Terraform 0.13, `count`, `for_each` and `depends_on` are legal on `module` blocks — but not if the module, or anything it calls, contains a provider block. Terraform reports "Module is incompatible with count, for_each, and depends_on". The reason is structural: those meta-arguments would create N instances of the module, and Terraform has no way to create N provider configurations from one block, nor to defer a provider configuration behind `depends_on`. So a single embedded provider block silently costs the module the most common scaling pattern there is, and the failure surfaces at the *caller*, months later, in an error message that says nothing about providers. ### The caller loses the decisions that matter A module with `provider "aws" { region = "us-east-1" }` inside it is a us-east-1 module forever. The caller cannot use it for the DR region, cannot point it at a different account, cannot add `default_tags`, and cannot make it use the credentials the pipeline assumed. Every one of those becomes a fork or a pull request against a shared repository. ### Removal is a trap This is the one that bites in production. State records, per resource, which provider configuration manages it. To destroy a resource Terraform must still be able to *reach* it, which means the configuration has to exist. If the configuration lived inside the module, then deleting the `module` block removes the resources **and** the only configuration that could destroy them, and Terraform stops with a "Provider configuration not present" error. Digging out means re-adding the module temporarily, destroying deliberately, then removing — or manual state surgery. A caller-owned configuration outlives the module call and makes removal a normal one-step operation. ## The shape that works ```hcl # child module — declares, never configures terraform { required_providers { aws = { source = "hashicorp/aws" version = ">= 5.0" configuration_aliases = [aws.replica] } } } ``` ```hcl # root module — configures, and binds module "service" { source = "./modules/service" for_each = toset(["blue", "green"]) providers = { aws = aws.primary aws.replica = aws.secondary } } ``` With no provider block inside the child, `for_each` on the module is legal again, and both instances get the configurations the root chose. ## The honest exception A **root** module — the thing you actually run `terraform apply` in — must contain provider blocks; that is where configuration belongs. Some teams also have "root-like" modules that are only ever called from one place and never with `for_each`; embedding a provider there works until the day someone reuses it. Treating the rule as absolute for anything published to a registry or shared across repositories costs nothing and avoids a class of bug whose symptom never mentions its cause. ## How to spot it in review Grep a module repository for `^provider "` outside root directories. Anything that turns up is a latent `count`/`for_each` block and a future removal problem. Fixing it is mechanical — delete the block, add `configuration_aliases` if more than one instance was in play, and update callers with a `providers` map — but it is a breaking interface change, so it belongs in a major version bump of the module.