From a6cf79687326d02efa657a381cdad3cf425042e2 Mon Sep 17 00:00:00 2001 From: Martin Atkins Date: Sat, 5 May 2018 14:34:43 -0700 Subject: [PATCH] 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. --- website/docs/configuration/providers.html.md | 165 +++++++++---------- 1 file changed, 75 insertions(+), 90 deletions(-) diff --git a/website/docs/configuration/providers.html.md b/website/docs/configuration/providers.html.md index 2a4154da3b..28e4dcfdd5 100644 --- a/website/docs/configuration/providers.html.md +++ b/website/docs/configuration/providers.html.md @@ -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 - -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. - -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 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 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. + +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.