Documentation incorrectly asserts that using a providers argument in a module block disables implicit provider inheritance

[ravron]

Terraform Version

Terraform v1.9.2

Affected Pages

https://developer.hashicorp.com/terraform/language/modules/develop/providers#passing-providers-explicitly

What is the docs issue?

The documentation linked says:

Once the providers argument is used in a module block, it overrides all of the default inheritance behavior, so it is necessary to enumerate mappings for all of the required providers.

However, this does not appear to be true. I set up the following two files:

main.tf

provider "aws" {
  region = "us-west-2"
}

provider "aws" {
  alias = "other"
  region = "us-east-2"
}

module "example" {
  source = "./example"

  providers = {
    aws.other = aws.other
  }
}

In this main.tf, we have two AWS providers: aws and aws.other. We pass only aws.other to the example module.

example/main.tf

terraform {
  required_providers {
    aws = {
      source                = "hashicorp/aws"
      configuration_aliases = [aws.other]
    }
  }
}

resource "aws_sns_topic" "default" {
  name = "example-default"
}

resource "aws_sns_topic" "other" {
  provider = aws.other
  name = "example-other"
}

In the example/main.tf file, we create two SNS topics: one using the default aws provider, and one using the aws.other AWS alias. Based on the quote from the documentation, I would expect that the first of the two SNS topics would fail in some way, since it is using a default provider that was not passed to the module, and the default inheritance behavior should be overridden.

But this works just fine, creating two topics in two different regions.

The upshot is that I believe the default inheritance behavior does continue to operate, even when the providers argument is used in a module block, contrary to the documentation I quoted. I think this is fundamentally the same issue as reported in #21923 and #25317.

Proposal

There are two options I see:

1. Change the documentation to indicate what Terraform actually does. The quoted sentence could be deleted, or changed to read something like "If the unaliased provider name is not present in the providers map, it will still be inherited in the same way as implicit provider inheritance."
2. Change Terraform behavior so that the documentation is correct. This is my preference, simply because the documentation's justification is convincing: "This is to avoid confusion and surprises that may result when mixing both implicit and explicit provider passing." Indeed, it is confusing how implicit and explicit provider passing mix.

References

• explicit provider block non-default only #25317
• Docs: "Passing Providers Explicitly" has an incorrect assertion #21923

[crw]

Thanks for this report!

[yogi345]

I think correcting documentation would be good option, since the default provider would be called anyway if alias is not provided. I can take this bug to update documentation if agreed upon.

[crw]

I am going to have this reviewed in triage next week, I'll update here if we agree this is how the documentation should be changed.

[yogi345]

Any update on this Craig?

[crw]

Hi @yogi345, sorry for the delay. There was agreement in triage that the docs were probably written before implementation was finished, the way it was thought the feature would work, and not fixed afterwards for how the feature actually works. So basically we would want to do option 1, change the documentation so that it is correct. The main thing to do is just validate the claims made in the original post, and then update the documentations to match the actual functionality. I am going to be out for the next three weeks, but please feel free to take a look and file an appropriate pull request to the docs, otherwise we will try to pick this up again when I get back. Thanks!

[yogi345]

Sure @crw , I will validate the behavior and raise the documentation update PR.

[yogi345]

@crw / @ravron I have raised PR to update the documentation #35880. There are few checks which are in "Expected — Waiting for status to be reported" will those checks run automatically after approval or do I have to follow certain steps, could please guide?

[crw]

@yogi345 nope, don't worry about those checks. I am attempting to move this through the process now (I was out-of-office, but am back.)

[yogi345]

No problem Craig. Thanks for your response. Let me know the further process, since this would be my 1st contribution.

…

On Tue, 19 Nov, 2024, 4:48 am Craig Wright, ***@***.***> wrote: @yogi345 <https://github.com/yogi345> nope, don't worry about those checks. I am attempting to move this through the process now (I was out-of-office, but am back.) — Reply to this email directly, view it on GitHub <#35781 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABLWBVIWPTOJYUZ7LURBOH32BJYUJAVCNFSM6AAAAABO3VCAHOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDIOBUGM2DQMRYHE> . You are receiving this because you were mentioned.Message ID: ***@***.***>