website: Revise the "Providers" configuration docs section
These revisions reflect this sub-section's new earlier placement in the sub-section list, leading to a more guide-like style for the initial sections. Also includes some minor copy-editing to align terminology with that introduced in the prior commit for the "Resources" docs page.
This commit is contained in:
Martin Atkins
parent
6fa6a0d110
commit
a6cf796873
|
|
@ -6,61 +6,71 @@ description: |-
|
|||
Providers are responsible in Terraform for managing the lifecycle of a resource: create, read, update, delete.
|
||||
---
|
||||
|
||||
# Provider Configuration
|
||||
# Providers
|
||||
|
||||
Providers are responsible in Terraform for managing the lifecycle
|
||||
of a [resource](/docs/configuration/resources.html): create,
|
||||
read, update, delete.
|
||||
While [resources](/docs/configuration/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_.
|
||||
|
||||
Most providers require some sort of configuration to provide
|
||||
authentication information, endpoint URLs, etc. Where explicit configuration
|
||||
is required, a `provider` block is used within the configuration as
|
||||
illustrated in the following sections.
|
||||
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.
|
||||
|
||||
By default, resources are matched with provider configurations by matching
|
||||
the start of the resource name. For example, a resource of type
|
||||
`vsphere_virtual_machine` is associated with a provider called `vsphere`.
|
||||
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.
|
||||
|
||||
This page assumes you're familiar with the
|
||||
[configuration syntax](/docs/configuration/syntax.html)
|
||||
already.
|
||||
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.
|
||||
|
||||
## Example
|
||||
## Provider Configuration
|
||||
|
||||
A provider configuration looks like the following:
|
||||
A provider configuration is created using a `provider` block:
|
||||
|
||||
```hcl
|
||||
provider "aws" {
|
||||
access_key = "foo"
|
||||
secret_key = "bar"
|
||||
region = "us-east-1"
|
||||
provider "google" {
|
||||
project = "acme-app"
|
||||
region = "us-central1"
|
||||
}
|
||||
```
|
||||
|
||||
## Description
|
||||
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`.
|
||||
|
||||
A `provider` block represents a configuration for the provider named in its
|
||||
header. For example, `provider "aws"` above is a configuration for the
|
||||
`aws` provider.
|
||||
The body of the block (between `{` and `}`) contains configuration arguments
|
||||
for the provider itself. Most arguments in this section are specified by
|
||||
the provider itself, and indeed in this example both `project` and `region`
|
||||
are specific to the `google` provider.
|
||||
|
||||
Within the block body (between `{ }`) is configuration for the provider.
|
||||
The configuration is dependent on the type, and is documented
|
||||
[for each provider](/docs/providers/index.html).
|
||||
The configuration arguments defined by the provider may be assigned using
|
||||
[expressions](/docs/configuration/expressions.html), which can for example
|
||||
allow them to be parameterized by input variables. However, since provider
|
||||
configurations must be evaluated in order to perform any resource type action,
|
||||
provider configurations may refer only to values that are known before
|
||||
the configuration is applied. In particular, avoid referring to attributes
|
||||
exported by other resources unless their values are specified directly in the
|
||||
configuration.
|
||||
|
||||
The arguments `alias` and `version`, if present, are special arguments
|
||||
handled by Terraform Core for their respective features described above. All
|
||||
other arguments are defined by the provider itself.
|
||||
A small number of "meta-arguments" are defined by Terraform Core itself and
|
||||
available for all `provider` blocks. These will be described in the following
|
||||
sections.
|
||||
|
||||
A `provider` block may be omitted if its body would be empty. Using a resource
|
||||
in configuration implicitly creates an empty provider configuration for it
|
||||
unless a `provider` block is explicitly provided.
|
||||
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
|
||||
|
||||
Each time a new provider is added to configuration -- either explicitly via
|
||||
a `provider` block or by adding a resource from that provider -- it's necessary
|
||||
to initialize that provider before use. Initialization downloads and installs
|
||||
the provider's plugin and prepares it to be used.
|
||||
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.
|
||||
|
||||
Provider initialization is one of the actions of `terraform init`. Running
|
||||
this command will download and initialize any providers that are not already
|
||||
|
|
@ -79,8 +89,8 @@ For more information, see
|
|||
|
||||
## Provider Versions
|
||||
|
||||
Providers are released on a separate rhythm from Terraform itself, and thus
|
||||
have their own version numbers. For production use, it is recommended to
|
||||
Providers are plugins released on a separate rhythm from Terraform itself, and
|
||||
so they have their own version numbers. For production use, you should
|
||||
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.
|
||||
|
|
@ -100,27 +110,25 @@ suggested below.
|
|||
* provider.aws: version = "~> 1.0"
|
||||
```
|
||||
|
||||
To constrain the provider version as suggested, add a `version` argument to
|
||||
the provider configuration block:
|
||||
To constrain the provider version as suggested, add the `version` meta-argument
|
||||
to the provider configuration block:
|
||||
|
||||
```hcl
|
||||
provider "aws" {
|
||||
version = "~> 1.0"
|
||||
|
||||
access_key = "foo"
|
||||
secret_key = "bar"
|
||||
region = "us-east-1"
|
||||
}
|
||||
```
|
||||
|
||||
This special argument applies to _all_ providers.
|
||||
[`terraform providers`](/docs/commands/providers.html) can be used to
|
||||
view the specified version constraints for all providers used in the
|
||||
This meta-argument applies to all providers.
|
||||
[The `terraform providers` command](/docs/commands/providers.html) can be used
|
||||
to view the specified version constraints for all providers used in the
|
||||
current configuration.
|
||||
|
||||
The `version` attribute value may either be a single explicit version or
|
||||
a version constraint expression. Constraint expressions use the following
|
||||
syntax to specify a _range_ of versions that are acceptable:
|
||||
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
|
||||
|
|
@ -136,19 +144,19 @@ to the latest versions of all Terraform modules.
|
|||
|
||||
## Multiple Provider Instances
|
||||
|
||||
You can define multiple configurations for the same provider in order to support
|
||||
multiple regions, multiple hosts, etc. The primary use case for this is
|
||||
using multiple cloud regions. Other use-cases include targeting multiple
|
||||
Docker hosts, multiple Consul hosts, etc.
|
||||
You can optionally define multiple configurations for the same provider
|
||||
to allow managing objects in multiple regions, on multiple hosts, etc. The
|
||||
primary reason is multiple regions for a cloud platform. Other examples include
|
||||
targeting multiple Docker hosts, multiple Consul hosts, etc.
|
||||
|
||||
To include multiple configurations for a given provider, include multiple
|
||||
`provider` blocks with the same provider name, but set the `alias` field to an
|
||||
instance name to use for each additional instance. For example:
|
||||
`provider` blocks with the same provider name, but set the `alias` meta-argument
|
||||
to an alias name to use for each additional configuration. For example:
|
||||
|
||||
```hcl
|
||||
# The default provider configuration
|
||||
provider "aws" {
|
||||
# ...
|
||||
region = "us-east-1"
|
||||
}
|
||||
|
||||
# Additional provider configuration for west coast region
|
||||
|
|
@ -158,10 +166,10 @@ provider "aws" {
|
|||
}
|
||||
```
|
||||
|
||||
A `provider` block with out `alias` set is known as the _default_ provider
|
||||
The `provider` block without `alias` set is known as the _default_ provider
|
||||
configuration. When `alias` is set, it creates an _additional_ provider
|
||||
configuration. For providers that have no required configuration arguments, the
|
||||
implied _empty_ configuration is also considered to be a _default_ provider
|
||||
implied _empty_ configuration is considered to be the _default_ provider
|
||||
configuration.
|
||||
|
||||
Resources are normally associated with the default provider configuration
|
||||
|
|
@ -169,49 +177,26 @@ inferred from the resource type name. For example, a resource of type
|
|||
`aws_instance` uses the _default_ (un-aliased) `aws` provider configuration
|
||||
unless otherwise stated.
|
||||
|
||||
The `provider` argument within any `resource` or `data` block overrides this
|
||||
default behavior and allows an additional provider configuration to be
|
||||
The `provider` meta-argument within any `resource` or `data` block overrides
|
||||
this default behavior and allows an additional provider configuration to be
|
||||
selected using its alias:
|
||||
|
||||
```hcl
|
||||
resource "aws_instance" "foo" {
|
||||
provider = "aws.west"
|
||||
provider = aws.west
|
||||
|
||||
# ...
|
||||
}
|
||||
```
|
||||
|
||||
The value of the `provider` argument is always the provider name and an
|
||||
alias separated by a period, such as `"aws.west"` above.
|
||||
The value of the `provider` meta-argument is always the provider name and an
|
||||
alias separated by a period, such as `aws.west` above.
|
||||
|
||||
Provider configurations may also be passed from a parent module into a
|
||||
child module, as described in
|
||||
[_Providers within Modules_](/docs/modules/usage.html#providers-within-modules).
|
||||
|
||||
## Interpolation
|
||||
|
||||
Provider configurations may use [interpolation syntax](/docs/configuration/interpolation.html)
|
||||
to allow dynamic configuration:
|
||||
|
||||
```hcl
|
||||
provider "aws" {
|
||||
region = "${var.aws_region}"
|
||||
}
|
||||
```
|
||||
|
||||
Interpolation is supported only for the per-provider configuration arguments.
|
||||
It is not supported for the special `alias` and `version` arguments.
|
||||
|
||||
Although in principle it is possible to use any interpolation expression within
|
||||
a provider configuration argument, providers must be configurable to perform
|
||||
almost all operations within Terraform, and so it is not possible to use
|
||||
expressions whose value cannot be known until after configuration is applied,
|
||||
such as the id of a resource.
|
||||
|
||||
It is always valid to use [input variables](/docs/configuration/variables.html)
|
||||
and [data sources](/docs/configuration/data-sources.html) whose configurations
|
||||
do not in turn depend on as-yet-unknown values. [Local values](/docs/configuration/locals.html)
|
||||
may also be used, but currently may cause errors when running `terraform destroy`.
|
||||
In most cases, only _root modules_ should define provider configurations, with
|
||||
all child modules obtaining their provider configurations from their parents.
|
||||
|
||||
## Third-party Plugins
|
||||
|
||||
|
|
@ -331,7 +316,7 @@ When possible, Terraform will use hardlinks or symlinks to avoid storing
|
|||
a separate copy of a cached plugin in multiple directories. At present, this
|
||||
is not supported on Windows and instead a copy is always created.
|
||||
|
||||
The plugin cache directory must *not* be the third-party plugin directory
|
||||
The plugin cache directory must _not_ be the third-party plugin directory
|
||||
or any other directory Terraform searches for pre-installed plugins, since
|
||||
the cache management logic conflicts with the normal plugin discovery logic
|
||||
when operating on the same directory.
|
||||
|
|
|
|||
Loading…
Reference in New Issue