github.com/jd3nn1s/terraform@v0.9.6-0.20170906225847-13878347b7a1/website/docs/configuration/providers.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Configuring Providers"
     4  sidebar_current: "docs-config-providers"
     5  description: |-
     6    Providers are responsible in Terraform for managing the lifecycle of a resource: create, read, update, delete.
     7  ---
     8  
     9  # Provider Configuration
    10  
    11  Providers are responsible in Terraform for managing the lifecycle
    12  of a [resource](/docs/configuration/resources.html): create,
    13  read, update, delete.
    14  
    15  Every resource in Terraform is mapped to a provider based
    16  on longest-prefix matching. For example the `aws_instance`
    17  resource type would map to the `aws` provider (if that exists).
    18  
    19  Most providers require some sort of configuration to provide
    20  authentication information, endpoint URLs, etc. Provider configuration
    21  blocks are a way to set this information globally for all
    22  matching resources.
    23  
    24  This page assumes you're familiar with the
    25  [configuration syntax](/docs/configuration/syntax.html)
    26  already.
    27  
    28  ## Example
    29  
    30  A provider configuration looks like the following:
    31  
    32  ```hcl
    33  provider "aws" {
    34    access_key = "foo"
    35    secret_key = "bar"
    36    region     = "us-east-1"
    37  }
    38  ```
    39  
    40  ## Description
    41  
    42  The `provider` block configures the provider of the given `NAME`.
    43  Multiple provider blocks can be used to configure multiple providers.
    44  
    45  Terraform matches providers to resources by matching two criteria.
    46  Both criteria must be matched for a provider to manage a resource:
    47  
    48  - They must share a common prefix. Longest matching prefixes are tried first.
    49    For example, `aws_instance` would choose the `aws` provider.
    50  
    51  - The provider must report that it supports the given resource type. Providers
    52    internally tell Terraform the list of resources they support.
    53  
    54  Within the block (the `{ }`) is configuration for the resource.
    55  The configuration is dependent on the type, and is documented
    56  [for each provider](/docs/providers/index.html).
    57  
    58  ## Initialization
    59  
    60  Each time a new provider is added to configuration -- either explicitly via
    61  a `provider` block or by adding a resource from that provider -- it's necessary
    62  to initialize that provider before use. Initialization downloads and installs
    63  the provider's plugin and prepares it to be used.
    64  
    65  Provider initialization is one of the actions of `terraform init`. Running
    66  this command will download and initialize any providers that are not already
    67  initialized.
    68  
    69  For more information, see
    70  [the `terraform init` command](/docs/commands/init.html).
    71  
    72  ## Provider Versions
    73  
    74  Providers are released on a separate rhythm from Terraform itself, and thus
    75  have their own version numbers. For production use, it is recommended to
    76  constrain the acceptable provider versions via configuration, to ensure that
    77  new versions with breaking changes will not be automatically installed by
    78  `terraform init` in future.
    79  
    80  When `terraform init` is run _without_ provider version constraints, it
    81  prints a suggested version constraint string for each provider:
    82  
    83  ```
    84  The following providers do not have any version constraints in configuration,
    85  so the latest version was installed.
    86  
    87  To prevent automatic upgrades to new major versions that may contain breaking
    88  changes, it is recommended to add version = "..." constraints to the
    89  corresponding provider blocks in configuration, with the constraint strings
    90  suggested below.
    91  
    92  * provider.aws: version = "~> 1.0"
    93  ```
    94  
    95  To constrain the provider version as suggested, add a `version` argument to
    96  the provider configuration block:
    97  
    98  ```hcl
    99  provider "aws" {
   100    version = "~> 1.0"
   101  
   102    access_key = "foo"
   103    secret_key = "bar"
   104    region     = "us-east-1"
   105  }
   106  ```
   107  
   108  This special argument applies to _all_ providers.
   109  [`terraform providers`](/docs/commands/providers.html) can be used to
   110  view the specified version constraints for all providers used in the
   111  current configuration.
   112  
   113  When `terraform init` is re-run with providers already installed, it will
   114  use an already-installed provider that meets the constraints in preference
   115  to downloading a new version. To upgrade to the latest acceptable version
   116  of each provider, run `terraform init -upgrade`. This command also upgrades
   117  to the latest versions of all Terraform modules.
   118  
   119  ## Multiple Provider Instances
   120  
   121  You can define multiple instances of the same provider in order to support
   122  multiple regions, multiple hosts, etc. The primary use case for this is
   123  utilizing multiple cloud regions. Other use cases include targeting multiple
   124  Docker hosts, multiple Consul hosts, etc.
   125  
   126  To define multiple provider instances, repeat the provider configuration
   127  multiple times, but set the `alias` field and name the provider. For
   128  example:
   129  
   130  ```hcl
   131  # The default provider
   132  provider "aws" {
   133    # ...
   134  }
   135  
   136  # West coast region
   137  provider "aws" {
   138    alias  = "west"
   139    region = "us-west-2"
   140  }
   141  ```
   142  
   143  After naming a provider, you reference it in resources with the `provider`
   144  field:
   145  
   146  ```hcl
   147  resource "aws_instance" "foo" {
   148    provider = "aws.west"
   149  
   150    # ...
   151  }
   152  ```
   153  
   154  If a provider isn't specified, then the default provider configuration
   155  is used (the provider configuration with no `alias` set). The value of the
   156  `provider` field is `TYPE.ALIAS`, such as "aws.west" above.
   157  
   158  ## Syntax
   159  
   160  The full syntax is:
   161  
   162  ```text
   163  provider NAME {
   164    CONFIG ...
   165    [alias = ALIAS]
   166  }
   167  ```
   168  
   169  where `CONFIG` is:
   170  
   171  ```text
   172  KEY = VALUE
   173  
   174  KEY {
   175    CONFIG
   176  }
   177  ```
   178  
   179  ## Interpolation
   180  Providers support [interpolation syntax](/docs/configuration/interpolation.html) allowing dynamic configuration at run time.
   181  
   182  ```hcl
   183  provider "aws" {
   184    region = "${var.aws_region}"
   185  }
   186  ```
   187  
   188  -> **NOTE:** Because providers are one of the first things loaded when Terraform parses the graph, it is not possible to use the output from modules or resources as inputs to the provider. At this time, only [variables](/docs/configuration/variables.html) and [data sources](/docs/configuration/data-sources.html), including [remote state](/docs/providers/terraform/d/remote_state.html) may be used in an interpolation inside a provider stanza.