resilien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

website: Consistently recommend the required_providers block 

Previously we were inconsistent in whether we were recommending the
new required_providers block or the "version" setting inside a "provider"
block.
This commit is contained in:
Martin Atkins 2019-10-28 15:53:06 -07:00
parent 7c110f9cf8
commit f8a32f0b83
3 changed files with 33 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
website/docs/configuration/modules.html.md
View File

@ -203,8 +203,8 @@ provider configuration first.
### Provider Version Constraints in Modules
To declare that a module requires particular versions of a specific provider,
use the [`required_providers`](/docs/configuration/terraform.html#specifying-required-provider-versions)
setting inside a `terraform` block:
use a [`required_providers`](terraform.html#specifying-required-provider-versions)
block inside a `terraform` block:
```hcl
terraform {

40
website/docs/configuration/providers.html.md
View File

@ -93,9 +93,9 @@ for installation instructions.
For more information, see
[the `terraform init` command](/docs/commands/init.html).
## `version`: Provider Versions
## Provider Versions
[inpage-versions]: #version-provider-versions
[inpage-versions]: #provider-versions
Providers are plugins released on a separate rhythm from Terraform itself, and
so they have their own version numbers. For production use, you should
@ -118,31 +118,23 @@ suggested below.
* provider.aws: version = "~> 1.0"
```
To constrain the provider version as suggested, add the `version` meta-argument
to the provider configuration block:
To constrain the provider version as suggested, add a `required_providers`
block inside a `terraform` block:
```hcl
provider "aws" {
version = "~> 1.0"
region = "us-east-1"
terraform {
required_providers {
aws = "~> 1.0"
}
}
```
This meta-argument applies to all providers.
[The `terraform providers` command](/docs/commands/providers.html) can be used
Use [the `terraform providers` command](/docs/commands/providers.html)
to view the specified version constraints for all providers used in the
current configuration.
The `version` argument value may either be a single explicit version or
a version constraint string. Constraint strings use the following syntax to
specify a _range_ of versions that are acceptable:
* `>= 1.2.0`: version 1.2.0 or newer
* `<= 1.2.0`: version 1.2.0 or older
* `~> 1.2.0`: any non-beta version `>= 1.2.0` and `< 1.3.0`, e.g. `1.2.X`
* `~> 1.2`: any non-beta version `>= 1.2.0` and `< 2.0.0`, e.g. `1.X.Y`
* `>= 1.0.0, <= 2.0.0`: any version between 1.0.0 and 2.0.0 inclusive
For more information on the `required_providers` block, see
[Specifying Required Provider Versions](https://www.terraform.io/docs/configuration/terraform.html#specifying-required-provider-versions).
When `terraform init` is re-run with providers already installed, it will
use an already-installed provider that meets the constraints in preference
@ -150,10 +142,12 @@ to downloading a new version. To upgrade to the latest acceptable version
of each provider, run `terraform init -upgrade`. This command also upgrades
to the latest versions of all Terraform modules.
Additional provider version requirements can be specified in the
[`required_providers`](/docs/configuration/terraform.html#specifying-required-provider-versions)
block inside the `terraform` configuration. Constraints are combined together
using logical AND.
Provider version constraints can also be specified using a `version` argument
within a `provider` block, but that simultaneously declares a new provider
configuration that may cause problems particularly when writing shared modules.
For that reason, we recommend using the `required_providers` block as described
above, and _not_ using the `version` argument within `provider` blocks.
`version` is still supported for compatibility with older Terraform versions.
## `alias`: Multiple Provider Instances

20
website/docs/configuration/terraform.html.md
View File

@ -103,12 +103,6 @@ to newer versions of Terraform without altering the module.
The `required_providers` setting is a map specifying a version constraint for
each provider required by your configuration.
This is one of several ways to define
[provider version constraints](./providers.html#provider-versions),
and is particularly suited to re-usable modules that expect a provider
configuration to be provided by their caller but still need to impose a
minimum version for that provider.
```hcl
terraform {
required_providers {
@ -117,7 +111,21 @@ terraform {
}
```
Version constraint strings within the `required_providers` block use the
same version constraint syntax as for
[the `required_version` argument](#specifying-a-required-terraform-version)
described above.
When a configuration contains multiple version constraints for a single
provider -- for example, if you're using multiple modules and each one has
its own constraint -- _all_ of the constraints must hold to select a single
provider version for the whole configuration.
Re-usable modules should constrain only the minimum allowed version, such
as `>= 1.0.0`. This specifies the earliest version that the module is
compatible with while leaving the user of the module flexibility to upgrade
to newer versions of the provider without altering the module.
Root modules should use a `~>` constraint to set both a lower and upper bound
on versions for each provider they depend on, as described in
[Provider Versions](providers.html#provider-versions).