From 1bb602859af92f423b40efe74f329dd380c48678 Mon Sep 17 00:00:00 2001 From: James Bardin Date: Fri, 12 Feb 2021 11:44:26 -0500 Subject: [PATCH 1/5] update docs for configuration_aliases Remove references to the "proxy configuration block" concept, and add examples showing the usage of `configuration_aliases`. --- .../meta-arguments/module-providers.html.md | 7 +- .../modules/develop/providers.html.md | 76 +++++++++---------- .../language/providers/configuration.html.md | 18 +++++ 3 files changed, 57 insertions(+), 44 deletions(-) diff --git a/website/docs/language/meta-arguments/module-providers.html.md b/website/docs/language/meta-arguments/module-providers.html.md index 99cd8e431..fa9f1d276 100644 --- a/website/docs/language/meta-arguments/module-providers.html.md +++ b/website/docs/language/meta-arguments/module-providers.html.md @@ -36,9 +36,10 @@ module "example" { ## Default Behavior: Inherit Default Providers -The `providers` argument is optional. If you omit it, a child module inherits -all of the _default_ provider configurations from its parent module. (Default -provider configurations are ones that don't use the `alias` argument.) +If the child module does not declare any configuration aliases, the `providers` +argument is optional. If you omit it, a child module inherits all of the +_default_ provider configurations from its parent module. (Default provider +configurations are ones that don't use the `alias` argument.) If you specify a `providers` argument, it cancels this default behavior, and the child module will _only_ have access to the provider configurations you specify. diff --git a/website/docs/language/modules/develop/providers.html.md b/website/docs/language/modules/develop/providers.html.md index 4d71e3325..be08a1f11 100644 --- a/website/docs/language/modules/develop/providers.html.md +++ b/website/docs/language/modules/develop/providers.html.md @@ -22,18 +22,9 @@ within a `module` block. These two options are discussed in more detail in the following sections. A module intended to be called by one or more other modules must not contain -any `provider` blocks, with the exception of the special -"proxy provider blocks" discussed under -_[Passing Providers Explicitly](#passing-providers-explicitly)_ -below. - -For backward compatibility with configurations targeting Terraform v0.10 and -earlier Terraform does not produce an error for a `provider` block in a shared -module if the `module` block only uses features available in Terraform v0.10, -but that is a legacy usage pattern that is no longer recommended. A legacy -module containing its own provider configurations is not compatible with the -`for_each`, `count`, and `depends_on` arguments that were introduced in -Terraform v0.13. For more information, see +any `provider` blocks. A module containing its own provider configurations is +not compatible with the `for_each`, `count`, and `depends_on` arguments that +were introduced in Terraform v0.13. For more information, see [Legacy Shared Modules with Provider Configurations](#legacy-shared-modules-with-provider-configurations). Provider configurations are used for all operations on associated resources, @@ -82,6 +73,25 @@ settings come from provider _configurations_, and a particular overall Terraform configuration can potentially have [several different configurations for the same provider](/docs/language/providers/configuration.html#alias-multiple-provider-configurations). +To declare multiple configuration names for a provider within a module, add the +`configuration_aliases` argument: + +```hcl +terraform { + required_providers { + aws = { + source = "hashicorp/aws" + version = ">= 2.7.0" + configuration_aliases = [ aws.alternate ] + } + } +} +``` + +The above requirements are identical to the previous, with the addition of the +alias provider configuration name `aws.alternate`, which can be referenced by +resources using the `provider` argument. + If you are writing a shared Terraform module, constrain only the minimum required provider version using a `>=` constraint. This should specify the minimum version containing the features your module relies on, and thus allow a @@ -201,17 +211,18 @@ module "tunnel" { } ``` -The subdirectory `./tunnel` must then contain _proxy configuration blocks_ like -the following, to declare that it requires its calling module to pass -configurations with these names in its `providers` argument: +The subdirectory `./tunnel` must then declare the configuration aliases for the +provider to pass configurations with these names in its `providers` argument: ```hcl -provider "aws" { - alias = "src" -} - -provider "aws" { - alias = "dst" +terraform { + required_providers { + aws = { + source = "hashicorp/aws" + version = ">= 2.7.0" + configuration_aliases = [ aws.src, aws.dest ] + } + } } ``` @@ -219,20 +230,6 @@ Each resource should then have its own `provider` attribute set to either `aws.src` or `aws.dst` to choose which of the two provider configurations to use. -## Proxy Configuration Blocks - -A proxy configuration block is one that contains only the `alias` argument. It -serves as a placeholder for provider configurations passed between modules, and -declares that a module expects to be explicitly passed an additional (aliased) -provider configuration. - --> **Note:** Although a completely empty proxy configuration block is also -valid, it is not necessary: proxy configuration blocks are needed only to -establish which _aliased_ provider configurations a child module expects. -Don't use a proxy configuration block if a module only needs a single default -provider configuration, and don't use proxy configuration blocks only to imply -[provider requirements](/docs/language/providers/requirements.html). - ## Legacy Shared Modules with Provider Configurations In Terraform v0.10 and earlier there was no explicit way to use different @@ -282,13 +279,10 @@ its provider configurations from the calling module, by using the "providers" argument in the calling module block. ``` -To make a module compatible with the new features, you must either remove all -of the `provider` blocks from its definition or, if you need multiple -configurations for the same provider, replace them with -_proxy configuration blocks_ as described in -[Passing Providers Explicitly](#passing-providers-explicitly). +To make a module compatible with the new features, you must remove all of the +`provider` blocks from its definition -If the new version of the module uses proxy configuration blocks, or if the +If the new version of the module declares `configuration_aliases`, or if the calling module needs the child module to use different provider configurations than its own default provider configurations, the calling module must then include an explicit `providers` argument to describe which provider diff --git a/website/docs/language/providers/configuration.html.md b/website/docs/language/providers/configuration.html.md index 612e8f9d5..0fe91db0a 100644 --- a/website/docs/language/providers/configuration.html.md +++ b/website/docs/language/providers/configuration.html.md @@ -103,6 +103,24 @@ provider "aws" { } ``` +To declare a configuration alias within a module in order to receive an +alternate provider configuration from the parent module, add the +`configuration_aliases` argument to that provider's `required_providers` +entry. The following example declares both the `mycloud` and +`mycloud.alternate` provider configuration names within the containing module: + +```hcl +terraform { + required_providers { + mycloud = { + source = "mycorp/mycloud" + version = "~> 1.0" + configuration_alaises = [ mycloud.alternate ] + } + } +} +``` + ### Default Provider Configurations A `provider` block without an `alias` argument is the _default_ configuration From dfd84243920f3743aba884e22df1c9c89e573f76 Mon Sep 17 00:00:00 2001 From: James Bardin Date: Fri, 12 Feb 2021 14:49:00 -0500 Subject: [PATCH 2/5] link configuration aliases between pages --- .../docs/language/meta-arguments/module-providers.html.md | 8 ++++---- website/docs/language/modules/develop/providers.html.md | 2 ++ 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/website/docs/language/meta-arguments/module-providers.html.md b/website/docs/language/meta-arguments/module-providers.html.md index fa9f1d276..993b9f23f 100644 --- a/website/docs/language/meta-arguments/module-providers.html.md +++ b/website/docs/language/meta-arguments/module-providers.html.md @@ -36,10 +36,10 @@ module "example" { ## Default Behavior: Inherit Default Providers -If the child module does not declare any configuration aliases, the `providers` -argument is optional. If you omit it, a child module inherits all of the -_default_ provider configurations from its parent module. (Default provider -configurations are ones that don't use the `alias` argument.) +If the child module does not declare any [configuration aliases](/docs/language/modules/develop/providers.html#provider-aliases-within-modules), +the `providers` argument is optional. If you omit it, a child module inherits +all of the _default_ provider configurations from its parent module. (Default +provider configurations are ones that don't use the `alias` argument.) If you specify a `providers` argument, it cancels this default behavior, and the child module will _only_ have access to the provider configurations you specify. diff --git a/website/docs/language/modules/develop/providers.html.md b/website/docs/language/modules/develop/providers.html.md index be08a1f11..346ccd508 100644 --- a/website/docs/language/modules/develop/providers.html.md +++ b/website/docs/language/modules/develop/providers.html.md @@ -73,6 +73,8 @@ settings come from provider _configurations_, and a particular overall Terraform configuration can potentially have [several different configurations for the same provider](/docs/language/providers/configuration.html#alias-multiple-provider-configurations). +## Provider Aliases Within Modules + To declare multiple configuration names for a provider within a module, add the `configuration_aliases` argument: From 9859d4e70b536c8c54160411b63e8ddadb36fda8 Mon Sep 17 00:00:00 2001 From: James Bardin Date: Fri, 12 Feb 2021 14:55:57 -0500 Subject: [PATCH 3/5] Update website/docs/language/modules/develop/providers.html.md Co-authored-by: Kristin Laemmert --- website/docs/language/modules/develop/providers.html.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/language/modules/develop/providers.html.md b/website/docs/language/modules/develop/providers.html.md index 346ccd508..df5ff1b8b 100644 --- a/website/docs/language/modules/develop/providers.html.md +++ b/website/docs/language/modules/develop/providers.html.md @@ -282,7 +282,7 @@ argument in the calling module block. ``` To make a module compatible with the new features, you must remove all of the -`provider` blocks from its definition +`provider` blocks from its definition. If the new version of the module declares `configuration_aliases`, or if the calling module needs the child module to use different provider configurations From e40727076f2a465b9c28799c80c06d8f7a03f248 Mon Sep 17 00:00:00 2001 From: James Bardin Date: Fri, 12 Feb 2021 14:57:26 -0500 Subject: [PATCH 4/5] Update website/docs/language/modules/develop/providers.html.md Co-authored-by: Kristin Laemmert --- website/docs/language/modules/develop/providers.html.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/language/modules/develop/providers.html.md b/website/docs/language/modules/develop/providers.html.md index df5ff1b8b..fd5db189a 100644 --- a/website/docs/language/modules/develop/providers.html.md +++ b/website/docs/language/modules/develop/providers.html.md @@ -214,7 +214,7 @@ module "tunnel" { ``` The subdirectory `./tunnel` must then declare the configuration aliases for the -provider to pass configurations with these names in its `providers` argument: +provider so the calling module can pass configurations with these names in its `providers` argument: ```hcl terraform { From d54a9b176be31457dc5878e5acfb472c5ea1376a Mon Sep 17 00:00:00 2001 From: James Bardin Date: Fri, 12 Feb 2021 14:57:51 -0500 Subject: [PATCH 5/5] Update website/docs/language/providers/configuration.html.md Co-authored-by: Kristin Laemmert --- website/docs/language/providers/configuration.html.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/language/providers/configuration.html.md b/website/docs/language/providers/configuration.html.md index 0fe91db0a..20cc28dcb 100644 --- a/website/docs/language/providers/configuration.html.md +++ b/website/docs/language/providers/configuration.html.md @@ -115,7 +115,7 @@ terraform { mycloud = { source = "mycorp/mycloud" version = "~> 1.0" - configuration_alaises = [ mycloud.alternate ] + configuration_aliases = [ mycloud.alternate ] } } }