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

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 2018-05-05 14:34:43 -07:00
parent 6fa6a0d110
commit a6cf796873
1 changed files with 73 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -6,61 +6,71 @@ description: |-
Providers are responsible in Terraform for managing the lifecycle of a resource: create, read, update, delete. 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 While [resources](/docs/configuration/resources.html) are the primary construct
of a [resource](/docs/configuration/resources.html): create, in the Terraform language, the _behaviors_ of resources rely on their
read, update, delete. associated resource types, and these types are defined by _providers_.
Most providers require some sort of configuration to provide Each provider offers a set of named resource types, and defines for each
authentication information, endpoint URLs, etc. Where explicit configuration resource type which arguments it accepts, which attributes it exports,
is required, a `provider` block is used within the configuration as and how changes to resources of that type are actually applied to remote
illustrated in the following sections. APIs.
By default, resources are matched with provider configurations by matching Most of the available providers correspond to one cloud or on-premises
the start of the resource name. For example, a resource of type infrastructure platform, and offer resource types that correspond to each
`vsphere_virtual_machine` is associated with a provider called `vsphere`. of the features of that platform.
This page assumes you're familiar with the Providers usually require some configuration of their own to specify endpoint
[configuration syntax](/docs/configuration/syntax.html) URLs, regions, authentication settings, and so on. All resource types belonging
already. 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 ```hcl
provider "aws" { provider "google" {
access_key = "foo" project = "acme-app"
secret_key = "bar" region = "us-central1"
region = "us-east-1"
} }
``` ```
## 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 The body of the block (between `{` and `}`) contains configuration arguments
header. For example, `provider "aws"` above is a configuration for the for the provider itself. Most arguments in this section are specified by
`aws` provider. 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 arguments defined by the provider may be assigned using
The configuration is dependent on the type, and is documented [expressions](/docs/configuration/expressions.html), which can for example
[for each provider](/docs/providers/index.html). 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 A small number of "meta-arguments" are defined by Terraform Core itself and
handled by Terraform Core for their respective features described above. All available for all `provider` blocks. These will be described in the following
other arguments are defined by the provider itself. sections.
A `provider` block may be omitted if its body would be empty. Using a resource Unlike many other objects in the Terraform language, a `provider` block may
in configuration implicitly creates an empty provider configuration for it be omitted if its contents would otherwise be empty. Terraform assumes an
unless a `provider` block is explicitly provided. empty default configuration for any provider that is not explicitly configured.
## Initialization ## Initialization
Each time a new provider is added to configuration -- either explicitly via 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 a `provider` block or by adding a resource from that provider -- Terraform
to initialize that provider before use. Initialization downloads and installs must initialize the provider before it can be used. Initialization downloads
the provider's plugin and prepares it to be used. and installs the provider's plugin so that it can later be executed.
Provider initialization is one of the actions of `terraform init`. Running Provider initialization is one of the actions of `terraform init`. Running
this command will download and initialize any providers that are not already this command will download and initialize any providers that are not already
@ -79,8 +89,8 @@ For more information, see
## Provider Versions ## Provider Versions
Providers are released on a separate rhythm from Terraform itself, and thus Providers are plugins released on a separate rhythm from Terraform itself, and
have their own version numbers. For production use, it is recommended to so they have their own version numbers. For production use, you should
constrain the acceptable provider versions via configuration, to ensure that constrain the acceptable provider versions via configuration, to ensure that
new versions with breaking changes will not be automatically installed by new versions with breaking changes will not be automatically installed by
`terraform init` in future. `terraform init` in future.
@ -100,27 +110,25 @@ suggested below.
* provider.aws: version = "~> 1.0" * provider.aws: version = "~> 1.0"
``` ```
To constrain the provider version as suggested, add a `version` argument to To constrain the provider version as suggested, add the `version` meta-argument
the provider configuration block: to the provider configuration block:
```hcl ```hcl
provider "aws" { provider "aws" {
version = "~> 1.0" version = "~> 1.0"
access_key = "foo"
secret_key = "bar"
region = "us-east-1" region = "us-east-1"
} }
``` ```
This special argument applies to _all_ providers. This meta-argument applies to all providers.
[`terraform providers`](/docs/commands/providers.html) can be used to [The `terraform providers` command](/docs/commands/providers.html) can be used
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` attribute value may either be a single explicit version or The `version` argument value may either be a single explicit version or
a version constraint expression. Constraint expressions use the following a version constraint string. Constraint strings use the following syntax to
syntax to specify a _range_ of versions that are acceptable: 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 newer
* `<= 1.2.0`: version 1.2.0 or older * `<= 1.2.0`: version 1.2.0 or older
@ -136,19 +144,19 @@ to the latest versions of all Terraform modules.
## Multiple Provider Instances ## Multiple Provider Instances
You can define multiple configurations for the same provider in order to support You can optionally define multiple configurations for the same provider
multiple regions, multiple hosts, etc. The primary use case for this is to allow managing objects in multiple regions, on multiple hosts, etc. The
using multiple cloud regions. Other use-cases include targeting multiple primary reason is multiple regions for a cloud platform. Other examples include
Docker hosts, multiple Consul hosts, etc. targeting multiple Docker hosts, multiple Consul hosts, etc.
To include multiple configurations for a given provider, include multiple To include multiple configurations for a given provider, include multiple
`provider` blocks with the same provider name, but set the `alias` field to an `provider` blocks with the same provider name, but set the `alias` meta-argument
instance name to use for each additional instance. For example: to an alias name to use for each additional configuration. For example:
```hcl ```hcl
# The default provider configuration # The default provider configuration
provider "aws" { provider "aws" {
# ... region = "us-east-1"
} }
# Additional provider configuration for west coast region # 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. When `alias` is set, it creates an _additional_ provider
configuration. For providers that have no required configuration arguments, the 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. configuration.
Resources are normally associated with 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 `aws_instance` uses the _default_ (un-aliased) `aws` provider configuration
unless otherwise stated. unless otherwise stated.
The `provider` argument within any `resource` or `data` block overrides this The `provider` meta-argument within any `resource` or `data` block overrides
default behavior and allows an additional provider configuration to be this default behavior and allows an additional provider configuration to be
selected using its alias: selected using its alias:
```hcl ```hcl
resource "aws_instance" "foo" { resource "aws_instance" "foo" {
provider = "aws.west" provider = aws.west
# ... # ...
} }
``` ```
The value of the `provider` argument is always the provider name and an The value of the `provider` meta-argument is always the provider name and an
alias separated by a period, such as `"aws.west"` above. alias separated by a period, such as `aws.west` above.
Provider configurations may also be passed from a parent module into a Provider configurations may also be passed from a parent module into a
child module, as described in child module, as described in
[_Providers within Modules_](/docs/modules/usage.html#providers-within-modules). [_Providers within Modules_](/docs/modules/usage.html#providers-within-modules).
In most cases, only _root modules_ should define provider configurations, with
## Interpolation all child modules obtaining their provider configurations from their parents.
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`.
## Third-party Plugins ## 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 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. 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 or any other directory Terraform searches for pre-installed plugins, since
the cache management logic conflicts with the normal plugin discovery logic the cache management logic conflicts with the normal plugin discovery logic
when operating on the same directory. when operating on the same directory.