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

website: "Provider Requirements" documentation 

We previously covered everything about using providers on a single page,
but that was getting unwieldy already and we now have a lot more to
discuss with v0.13 introducing a new source address syntax and some other
concepts.

Here we split the provider-related content into two parts: "Provider
Requirements" covers how to find and declare dependencies on providers,
and then "Provider Configuration" (formerly just "Providers") then focuses
primarily on how to write zero or more provider configurations for a
particular provider.

Because "Provider Requirements" is now presented before "Provider
Configuration" in the navigation, I've also moved some of the introductory
content about providers in general onto the "Requirements" page. The
first paragraph of that content is duplicated onto the "Configuration"
page for discoverability, but we now link to the requirements page to get
the full story.
This commit is contained in:
Martin Atkins 2020-06-17 18:17:17 -07:00
parent b1eb9dcfcf
commit dc8fd14c1e
3 changed files with 339 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

299
website/docs/configuration/provider-requirements.html.md Normal file
View File

@ -0,0 +1,299 @@
---
layout: "docs"
page_title: "Provider Requirements - Configuration Language"
---
## Provider Requirements
-> **Note:** If you are using Terraform 0.11 or
earlier, see
[0.11 Configuration Language: Provider Versions](../configuration-0-11/providers.html#provider-versions) instead.
Terraform relies on plugins called "providers" to interact with remote systems.
Each provider offers a set of named
[resource types](resources.html#resource-types-and-arguments), and defines for
each resource type which arguments it accepts, which attributes it exports, and
how changes to resources of that type are actually applied to remote APIs.
You can discover publicly-available providers
[via the Terraform Registry](https://registry.terraform.io/browse/providers).
Which providers you will use will depend on which remote cloud services you are
intending to configure. Additionally, some Terraform providers provide
local-only functionality which is useful to integrate functionality offered by
different providers, such as generating random numbers to help construct
unique resource names.
Once you've selected one or more providers, use a `required_providers` block to
declare them so that Terraform will make them available for use. A provider
dependency consists of both a source location and a version constraint:
```hcl
terraform {
required_providers {
mycloud = {
source = "mycorp/mycloud"
version = "~> 1.0"
}
}
}
```
The `required_providers` block must be nested inside a
[`terraform` block](terraform.html). The `terraform` block can include other
settings too, but we'll only focus on `required_providers` here.
The keys inside the `required_providers` block represent each provider's
[local name](#local-names), which is the unique identifier for a provider within
a particular module. Each item inside the `required_providers` block is an
object expecting the following arguments:
* `source` - the global [source address](#source-addresses) for the
provider you intend to use, such as `hashicorp/aws`.
* `version` - a [version constraint](#version-constraints) specifying
which subset of available provider versions the module is compatible with.
-> **Note:** The `required_providers` object syntax described above was added in Terraform v0.13. Previous versions of Terraform used a single string instead of an object, with the string specifying only a version constraint. For example, `mycloud = "~> 1.0"`. Explicit provider source addresses are supported only in Terraform v0.13 and later.
### Source Addresses
A provider _source address_ both globally identifies a particular provider and
specifies the primary location from which Terraform can download it.
Source addresses consist of three parts delimited by slashes (`/`), as
follows:
* **Hostname**: the hostname of the Terraform registry that indexes the provider.
You can omit the hostname portion and its following slash if the provider
is hosted on [the public Terraform Registry](https://registry.terraform.io/),
whose hostname is `registry.terraform.io`.
* **Namespace**: an organizational namespace within the specified registry.
For the public Terraform Registry and Terraform Cloud's private registry,
this represents the organization that is publishing the provider. This field
may have other meanings for other registry hosts.
* **Type**: The provider type name, which must be unique within a particular
namespace on a particular registry host.
For example,
[the official HTTP provider](https://registry.terraform.io/providers/hashicorp/http)
belongs to the `hashicorp` namespace on `registry.terraform.io`, so its
source address can be written as either `registry.terraform.io/hashicorp/http`
or, more commonly, just `hashicorp/http`.
-> **Note**: As a concession for backward compatibility with earlier versions of
Terraform, the `source` argument is actually optional. If you omit it, Terraform
will construct an implied source address by appending the local name to the prefix
`hashicorp/`. For example, a provider dependency with local name `http` that
does not have an explicit `source` will be treated as equivalent to
`hashicorp/http`. We recommend using explicit source addresses for all providers
in modules that require Terraform 0.13 or later, so a future reader of your
module can clearly see exactly which provider is required, without needing to
first understand this default behavior.
### Local Names
Full [source addresses](#source-addresses) are verbose, so the Terraform
language uses them only when declaring dependencies. We associate each required
provider with a module-specific _local name_, which is a short identifier that
will refer to the associated source address within declarations inside a
particular module.
```hcl
terraform {
required_providers {
mycloud = {
source = "mycorp/mycloud"
version = "~> 1.0"
}
}
}
```
The above example declares `mycloud` as the local name for `mycorp/mycloud`
(which is short for `registry.terraform.io/mycorp/mycloud`) in the current
module only. That means we will refer to this provider as `mycloud` elsewhere
in the module, such as in a `provider "mycloud"` block used to create a
[provider configuration](providers.html):
```hcl
provider "mycloud" {
# ...
}
```
We strongly recommend setting the local name of a provider to match the "type"
portion of its source address, as in the above example. Consistent use of the
provider's canonical type can help avoid the need for readers of the rest of
the module to refer to the `required_providers` block to understand which
provider the module is using.
The one situation where it is reasonable to use a different local name is the
relatively-rare case of having two providers in the same module that have the
same type name. In that case, Terraform requires choosing a unique local name
for each one. In that situation, we recommend to combine the namespace with
the type name to produce a compound local name to disambiguate:
```hcl
terraform {
required_providers {
# In the rare situation of using two providers that
# have the same type name -- "http" in this example --
# use a compound local name to distinguish them.
hashicorp_http = {
source = "hashicorp/http"
version = "~> 2.0"
}
mycorp_http = {
source = "mycorp/http"
version = "~> 1.0"
}
}
}
# References to these providers elsewhere in the
# module will use these compound local names.
provider "mycorp_http" {
# ...
}
```
### Version Constraints
A [source address](#source-addresses) uniquely identifies a particular
provider, but each provider can have one or more distinct _versions_, allowing
the functionality of the provider to evolve over time. Each provider dependency
you declare should have a [version constraint](./version-constraints.html)
given in the `version` argument.
Each module should at least declare the minimum provider version it is known
to work with, using the `>=` version constraint syntax:
```
terraform {
required_providers {
mycloud = {
source = "hashicorp/aws"
version = ">= 1.0"
}
}
}
```
A module intended to be used as the root of a configuration -- that is, as the
directory where you'd run `terraform apply` -- should also specify the
_maximum_ provider version it is intended to work with, to avoid accidental
upgrading when new versions are released. The `~>` operator is a convenient
shorthand for allowing only patch releases within a specific minor release:
```
terraform {
required_providers {
mycloud = {
source = "hashicorp/aws"
version = "~> 1.0.4"
}
}
}
```
_Do not_ use the `~>` or other maximum-version constraints for modules you
intend to reuse across many configurations. All of the version constraints
across all modules in a configuration must work collectively to select a
single version to use, so many modules all specifying maximum version
constraints would require those upper limits to all be updated simultaneously
if one module begins requiring a newer provider version.
The `version` argument is optional. If you omit it, Terraform will accept
_any_ version of the provider as compatible. That's risky for a provider
distributed by a third-party, because they may release a version containing
breaking changes at any time and prevent you from making progress until you
update your configuration. We strongly recommend always specifying a version
constraint, as described above, for every provider your module depends on.
### Built-in Providers
While most Terraform providers are distributed separately as plugins, there
is currently one provider that is built in to Terraform itself, which
provides
[the `terraform_remote_state` data source](/docs/providers/terraform/d/remote_state.html).
Because this provider is built in to Terraform, you don't need to declare it
in the `required_providers` block in order to use its features. However, for
consistency it _does_ have a special provider source address, which is
`terraform.io/builtin/terraform`. This address may sometimes appear in
Terraform's error messages and other output in order to unambiguously refer
to the built-in provider, as opposed to a hypothetical third-party provider
with the type name "terraform".
There is also an existing provider with the source address
`hashicorp/terraform`, which is an older version of the now-built-in provider
that was used by older versions of Terraform. `hashicorp/terraform` is not
compatible with Terraform v0.11 or later and should never be declared in a
`required_providers` block.
### In-house Providers
Some organizations develop their own providers to allow interacting with
proprietary systems, and wish to use these providers from Terraform without
publishing them on the public Terraform Registry.
One option for distributing such a provider is to run an in-house _private_
registry, by implementing
[the provider registry protocol](/docs/internals/provider-registry-protocol.html).
Running an additional service just to distribute a single provider internally
may be undesirable though, so Terraform also supports
[other provider installation methods](https://github.com/hashicorp/terraform/blob/master/website/docs/commands/cli-config.html.markdown#provider-installation),
including placing provider plugins directly in specific directories in the
local filesystem, via _filesystem mirrors_.
All providers must have a [source address](#source-addresses) that includes
(or implies) the hostname of a host registry, but for an in-house provider that
you intend only to distribute from a local filesystem directory you can choose
an artificial hostname in a domain your organization controls and use that to
mark your in-house providers.
For example, if your corporate domain were `example.com` then you might choose
to use `terraform.example.com` as your artificial hostname, even if that
hostname doesn't actually resolve in DNS. You can then choose any namespace and
type you wish to represent your in-house provider under that hostname, giving
a source address like `terraform.example.com/examplecorp/ourcloud`:
```hcl
terraform {
required_providers {
mycloud = {
source = "terraform.example.com/examplecorp/ourcloud"
version = ">= 1.0"
}
}
}
```
To make version 1.0.0 of this provider available for installation from the
local filesystem, choose one of the
[implied local mirror directories](/docs/commands/cli-config.html#implied-local-mirror-directories)
and create a directory structure under it like this:
```
terraform.example.com/examplecorp/ourcloud/1.0.0
```
Under that `1.0.0` directory, create one additional directory representing the
platform where you are running Terraform, such as `linux_amd64` for Linux on
an AMD64/x64 processor, and then place the provider plugin executable and any
other needed files in that directory.
The provider plugin executable file might therefore be at the following path,
on a Windows system for the sake of example:
```
terraform.example.com/examplecorp/ourcloud/1.0.0/windows_amd64/terraform-provider-ourcloud.exe
```
If you later decide to switch to using a real private provider registry, rather
than an artifical local hostname, you can deploy the registry server at
`terraform.example.com` and retain the same namespace and type names, in which
case your existing modules will require no changes to locate the same provider
using your registry server instead.

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

@ -1,34 +1,30 @@
---
layout: "docs"
page_title: "Providers - Configuration Language"
page_title: "Provider Configuration - Configuration Language"
sidebar_current: "docs-config-providers"
description: |-
Providers are responsible in Terraform for managing the lifecycle of a resource: create, read, update, delete.
---
# Providers
# Provider Configuration
-> **Note:** This page is about Terraform 0.12 and later. For Terraform 0.11 and
earlier, see
[0.11 Configuration Language: Providers](../configuration-0-11/providers.html).
While [resources](./resources.html) are the primary construct
in the Terraform language, the _behaviors_ of resources rely on their
associated resource types, and these types are defined by _providers_.
Terraform relies on plugins called "providers" to interact with remote systems.
Each provider offers a set of named
[resource types](resources.html#resource-types-and-arguments), and defines for
each resource type which arguments it accepts, which attributes it exports, and
how changes to resources of that type are actually applied to remote APIs.
Each provider offers a set of named resource types, and defines for each
resource type which arguments it accepts, which attributes it exports,
and how changes to resources of that type are actually applied to remote
APIs.
Before you can use a particular provider, you must declare a dependency on it
using [provider requirements syntax](./provider-requirements.html).
Most of the available providers correspond to one cloud or on-premises
infrastructure platform, and offer resource types that correspond to each
of the features of that platform.
Providers usually require some configuration of their own to specify endpoint
URLs, regions, authentication settings, and so on. All resource types belonging
to the same provider will share the same configuration, avoiding the need to
repeat this common information across every resource declaration.
Some providers require additional configuration to specify information such
as endpoint URLs and regions. A _provider configuration_ allows specifying that
information once and then reusing it for many resources in the same
configuration.
## Provider Configuration
@ -41,14 +37,12 @@ provider "google" {
}
```
The name given in the block header (`"google"` in this example) is the name
of the provider to configure. Terraform associates each resource type with
a provider by taking the first word of the resource type name (separated by
underscores), and so the "google" provider is assumed to be the provider for
the resource type name `google_compute_instance`.
The name given in the block header (`"google"` in this example) is the
[local name](./provider-requirements.html#local-names) of the provider
to configure.
The body of the block (between `{` and `}`) contains configuration arguments
for the provider itself. Most arguments in this section are specified by
for the provider itself. Most arguments in this section are defined by
the provider itself; in this example both `project` and `region`
are specific to the `google` provider.
@ -71,24 +65,20 @@ Unlike many other objects in the Terraform language, a `provider` block may
be omitted if its contents would otherwise be empty. Terraform assumes an
empty default configuration for any provider that is not explicitly configured.
## Initialization
## Installation
Each time a new provider is added to configuration -- either explicitly via
a `provider` block or by adding a resource from that provider -- Terraform
must initialize the provider before it can be used. Initialization downloads
and installs the provider's plugin so that it can later be executed.
a `provider` block or by adding a resource from that provider without an
associated `provider` block -- Terraform must install the provider before
it can be used. Installation locates and downloads the provider's plugin so
that it can be executed later.
Provider initialization is one of the actions of `terraform init`. Running
this command will download and initialize any providers that are not already
initialized.
this command will install any providers that are not already installed.
Providers downloaded by `terraform init` are only installed for the current
working directory; other working directories can have their own installed
provider versions.
Note that `terraform init` cannot automatically download providers that are not
distributed by HashiCorp. See [Third-party Plugins](#third-party-plugins) below
for installation instructions.
provider plugins, which may be of differing versions.
For more information, see
[the `terraform init` command](/docs/commands/init.html).
@ -103,51 +93,22 @@ constrain the acceptable provider versions via configuration, to ensure that
new versions with breaking changes will not be automatically installed by
`terraform init` in future.
When `terraform init` is run _without_ provider version constraints, it
prints a suggested version constraint string for each provider:
For more information on specifying version constraints, see
[Provider Requirements](./provider-requirements.html).
```
The following providers do not have any version constraints in configuration,
so the latest version was installed.
To prevent automatic upgrades to new major versions that may contain breaking
changes, it is recommended to add version = "..." constraints to the
corresponding provider blocks in configuration, with the constraint strings
suggested below.
* provider.aws: version = "~> 1.0"
```
To constrain the provider version as suggested, add a `required_providers`
block inside a `terraform` block:
```hcl
terraform {
required_providers {
aws = "~> 1.0"
}
}
```
Use [the `terraform providers` command](/docs/commands/providers.html)
to view the specified version constraints for all providers used in the
current configuration.
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
When you re-run `terraform init` with providers already installed, Terraform
will use an already-installed provider that meets the constraints in preference
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.
to the latest versions of all remote Terraform modules.
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.
In versions of Terraform prior to Terraform 0.12, provider version constraints
could be specified using a `version` argument within a `provider` block, which
would simultaneously declare a new provider requirement _and_ provider
configuration, but that overloading can cause problems particularly when
writing shared modules. For that reason, we recommend always omitting the
`version` argument within `provider` blocks, and specifying version
constraints instead using [Provider Requirements](./provider-requirements.html).
## `alias`: Multiple Provider Instances
@ -240,25 +201,9 @@ provider registry is
[part of the public Terraform Registry](https://registry.terraform.io/browse/providers),
along with public shared modules.
Providers distributed via a public registry to not require any special
additional configuration to use, once you know their source addresses. You can
specify both official and third-party source addresses in the
`required_providers` block in your module:
```hcl
terraform {
required_providers {
# An example third-party provider. Not actually available.
example = {
source = "example.com/examplecorp/example"
}
}
}
```
Installing directly from a registry is not appropriate for all situations,
though. If you are running Terraform from a system that cannot access some or
all of the necessary origin registries, you can configure Terraform to obtain
all of the necessary registry hosts, you can configure Terraform to obtain
providers from a local mirror instead. For more information, see
[Provider Installation](../commands/cli-config.html#provider-installation)
in the CLI configuration documentation.

3
website/layouts/docs.erb
View File

@ -18,6 +18,9 @@
<a href="/docs/configuration/resources.html">Resources</a>
</li>
<li>
<a href="/docs/configuration/provider-requirements.html">Provider Requirements</a>
</li>
<li>
<a href="/docs/configuration/providers.html">Provider Configuration</a>