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:
parent
7c110f9cf8
commit
f8a32f0b83
|
@ -203,8 +203,8 @@ provider configuration first.
|
||||||
### Provider Version Constraints in Modules
|
### Provider Version Constraints in Modules
|
||||||
|
|
||||||
To declare that a module requires particular versions of a specific provider,
|
To declare that a module requires particular versions of a specific provider,
|
||||||
use the [`required_providers`](/docs/configuration/terraform.html#specifying-required-provider-versions)
|
use a [`required_providers`](terraform.html#specifying-required-provider-versions)
|
||||||
setting inside a `terraform` block:
|
block inside a `terraform` block:
|
||||||
|
|
||||||
```hcl
|
```hcl
|
||||||
terraform {
|
terraform {
|
||||||
|
|
|
@ -93,9 +93,9 @@ for installation instructions.
|
||||||
For more information, see
|
For more information, see
|
||||||
[the `terraform init` command](/docs/commands/init.html).
|
[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
|
Providers are plugins released on a separate rhythm from Terraform itself, and
|
||||||
so they have their own version numbers. For production use, you should
|
so they have their own version numbers. For production use, you should
|
||||||
|
@ -118,31 +118,23 @@ suggested below.
|
||||||
* provider.aws: version = "~> 1.0"
|
* provider.aws: version = "~> 1.0"
|
||||||
```
|
```
|
||||||
|
|
||||||
To constrain the provider version as suggested, add the `version` meta-argument
|
To constrain the provider version as suggested, add a `required_providers`
|
||||||
to the provider configuration block:
|
block inside a `terraform` block:
|
||||||
|
|
||||||
```hcl
|
```hcl
|
||||||
provider "aws" {
|
terraform {
|
||||||
version = "~> 1.0"
|
required_providers {
|
||||||
|
aws = "~> 1.0"
|
||||||
region = "us-east-1"
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
This meta-argument applies to all providers.
|
Use [the `terraform providers` command](/docs/commands/providers.html)
|
||||||
[The `terraform providers` command](/docs/commands/providers.html) can be used
|
|
||||||
to view the specified version constraints for all providers used in the
|
to view the specified version constraints for all providers used in the
|
||||||
current configuration.
|
current configuration.
|
||||||
|
|
||||||
The `version` argument value may either be a single explicit version or
|
For more information on the `required_providers` block, see
|
||||||
a version constraint string. Constraint strings use the following syntax to
|
[Specifying Required Provider Versions](https://www.terraform.io/docs/configuration/terraform.html#specifying-required-provider-versions).
|
||||||
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
|
|
||||||
|
|
||||||
When `terraform init` is re-run with providers already installed, it will
|
When `terraform init` is re-run with providers already installed, it will
|
||||||
use an already-installed provider that meets the constraints in preference
|
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
|
of each provider, run `terraform init -upgrade`. This command also upgrades
|
||||||
to the latest versions of all Terraform modules.
|
to the latest versions of all Terraform modules.
|
||||||
|
|
||||||
Additional provider version requirements can be specified in the
|
Provider version constraints can also be specified using a `version` argument
|
||||||
[`required_providers`](/docs/configuration/terraform.html#specifying-required-provider-versions)
|
within a `provider` block, but that simultaneously declares a new provider
|
||||||
block inside the `terraform` configuration. Constraints are combined together
|
configuration that may cause problems particularly when writing shared modules.
|
||||||
using logical AND.
|
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
|
## `alias`: Multiple Provider Instances
|
||||||
|
|
||||||
|
|
|
@ -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
|
The `required_providers` setting is a map specifying a version constraint for
|
||||||
each provider required by your configuration.
|
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
|
```hcl
|
||||||
terraform {
|
terraform {
|
||||||
required_providers {
|
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
|
Re-usable modules should constrain only the minimum allowed version, such
|
||||||
as `>= 1.0.0`. This specifies the earliest version that the module is
|
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
|
compatible with while leaving the user of the module flexibility to upgrade
|
||||||
to newer versions of the provider without altering the module.
|
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).
|
||||||
|
|
Loading…
Reference in New Issue