github.com/rstandt/terraform@v0.12.32-0.20230710220336-b1063613405c/website/docs/configuration/providers.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Providers - Configuration Language"
     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  # Providers
    10  
    11  -> **Note:** This page is about Terraform 0.12 and later. For Terraform 0.11 and
    12  earlier, see
    13  [0.11 Configuration Language: Providers](../configuration-0-11/providers.html).
    14  
    15  While [resources](./resources.html) are the primary construct
    16  in the Terraform language, the _behaviors_ of resources rely on their
    17  associated resource types, and these types are defined by _providers_.
    18  
    19  Each provider offers a set of named resource types, and defines for each
    20  resource type which arguments it accepts, which attributes it exports,
    21  and how changes to resources of that type are actually applied to remote
    22  APIs.
    23  
    24  Most of the available providers correspond to one cloud or on-premises
    25  infrastructure platform, and offer resource types that correspond to each
    26  of the features of that platform.
    27  
    28  Providers usually require some configuration of their own to specify endpoint
    29  URLs, regions, authentication settings, and so on. All resource types belonging
    30  to the same provider will share the same configuration, avoiding the need to
    31  repeat this common information across every resource declaration.
    32  
    33  ## Provider Configuration
    34  
    35  A provider configuration is created using a `provider` block:
    36  
    37  ```hcl
    38  provider "google" {
    39    project = "acme-app"
    40    region  = "us-central1"
    41  }
    42  ```
    43  
    44  The name given in the block header (`"google"` in this example) is the name
    45  of the provider to configure. Terraform associates each resource type with
    46  a provider by taking the first word of the resource type name (separated by
    47  underscores), and so the "google" provider is assumed to be the provider for
    48  the resource type name `google_compute_instance`.
    49  
    50  The body of the block (between `{` and `}`) contains configuration arguments
    51  for the provider itself. Most arguments in this section are specified by
    52  the provider itself; in this example both `project` and `region`
    53  are specific to the `google` provider.
    54  
    55  The configuration arguments defined by the provider may be assigned using
    56  [expressions](./expressions.html), which can for example
    57  allow them to be parameterized by input variables. However, since provider
    58  configurations must be evaluated in order to perform any resource type action,
    59  provider configurations may refer only to values that are known before
    60  the configuration is applied. In particular, avoid referring to attributes
    61  exported by other resources unless their values are specified directly in the
    62  configuration.
    63  
    64  There are also two "meta-arguments" that are defined by Terraform itself
    65  and available for all `provider` blocks:
    66  
    67  - [`version`, for constraining the allowed provider versions][inpage-versions]
    68  - [`alias`, for using the same provider with different configurations for different resources][inpage-alias]
    69  
    70  Unlike many other objects in the Terraform language, a `provider` block may
    71  be omitted if its contents would otherwise be empty. Terraform assumes an
    72  empty default configuration for any provider that is not explicitly configured.
    73  
    74  ## Initialization
    75  
    76  Each time a new provider is added to configuration -- either explicitly via
    77  a `provider` block or by adding a resource from that provider -- Terraform
    78  must initialize the provider before it can be used. Initialization downloads
    79  and installs the provider's plugin so that it can later be executed.
    80  
    81  Provider initialization is one of the actions of `terraform init`. Running
    82  this command will download and initialize any providers that are not already
    83  initialized.
    84  
    85  Providers downloaded by `terraform init` are only installed for the current
    86  working directory; other working directories can have their own installed
    87  provider versions.
    88  
    89  Note that `terraform init` cannot automatically download providers that are not
    90  distributed by HashiCorp. See [Third-party Plugins](#third-party-plugins) below
    91  for installation instructions.
    92  
    93  For more information, see
    94  [the `terraform init` command](/docs/commands/init.html).
    95  
    96  ## Provider Versions
    97  
    98  [inpage-versions]: #provider-versions
    99  
   100  Providers are plugins released on a separate rhythm from Terraform itself, and
   101  so they have their own version numbers. For production use, you should
   102  constrain the acceptable provider versions via configuration, to ensure that
   103  new versions with breaking changes will not be automatically installed by
   104  `terraform init` in future.
   105  
   106  When `terraform init` is run _without_ provider version constraints, it
   107  prints a suggested version constraint string for each provider:
   108  
   109  ```
   110  The following providers do not have any version constraints in configuration,
   111  so the latest version was installed.
   112  
   113  To prevent automatic upgrades to new major versions that may contain breaking
   114  changes, it is recommended to add version = "..." constraints to the
   115  corresponding provider blocks in configuration, with the constraint strings
   116  suggested below.
   117  
   118  * provider.aws: version = "~> 1.0"
   119  ```
   120  
   121  To constrain the provider version as suggested, add a `required_providers`
   122  block inside a `terraform` block:
   123  
   124  ```hcl
   125  terraform {
   126    required_providers {
   127      aws = "~> 1.0"
   128    }
   129  }
   130  ```
   131  
   132  Use [the `terraform providers` command](/docs/commands/providers.html)
   133  to view the specified version constraints for all providers used in the
   134  current configuration.
   135  
   136  For more information on the `required_providers` block, see
   137  [Specifying Required Provider Versions](https://www.terraform.io/docs/configuration/terraform.html#specifying-required-provider-versions).
   138  
   139  When `terraform init` is re-run with providers already installed, it will
   140  use an already-installed provider that meets the constraints in preference
   141  to downloading a new version. To upgrade to the latest acceptable version
   142  of each provider, run `terraform init -upgrade`. This command also upgrades
   143  to the latest versions of all Terraform modules.
   144  
   145  Provider version constraints can also be specified using a `version` argument
   146  within a `provider` block, but that simultaneously declares a new provider
   147  configuration that may cause problems particularly when writing shared modules.
   148  For that reason, we recommend using the `required_providers` block as described
   149  above, and _not_ using the `version` argument within `provider` blocks.
   150  `version` is still supported for compatibility with older Terraform versions.
   151  
   152  ## `alias`: Multiple Provider Instances
   153  
   154  [inpage-alias]: #alias-multiple-provider-instances
   155  
   156  You can optionally define multiple configurations for the same provider, and
   157  select which one to use on a per-resource or per-module basis. The primary
   158  reason for this is to support multiple regions for a cloud platform; other
   159  examples include targeting multiple Docker hosts, multiple Consul hosts, etc.
   160  
   161  To include multiple configurations for a given provider, include multiple
   162  `provider` blocks with the same provider name, but set the `alias` meta-argument
   163  to an alias name to use for each additional configuration. For example:
   164  
   165  ```hcl
   166  # The default provider configuration
   167  provider "aws" {
   168    region = "us-east-1"
   169  }
   170  
   171  # Additional provider configuration for west coast region
   172  provider "aws" {
   173    alias  = "west"
   174    region = "us-west-2"
   175  }
   176  ```
   177  
   178  The `provider` block without `alias` set is known as the _default_ provider
   179  configuration. When `alias` is set, it creates an _additional_ provider
   180  configuration. For providers that have no required configuration arguments, the
   181  implied _empty_ configuration is considered to be the _default_ provider
   182  configuration.
   183  
   184  ### Referring to Alternate Providers
   185  
   186  When Terraform needs the name of a provider configuration, it always expects a
   187  reference of the form `<PROVIDER NAME>.<ALIAS>`. In the example above,
   188  `aws.west` would refer to the provider with the `us-west-2` region.
   189  
   190  These references are special expressions. Like references to other named
   191  entities (for example, `var.image_id`), they aren't strings and don't need to be
   192  quoted. But they are only valid in specific meta-arguments of `resource`,
   193  `data`, and `module` blocks, and can't be used in arbitrary expressions.
   194  
   195  ### Selecting Alternate Providers
   196  
   197  By default, resources use a default provider configuration inferred from the
   198  first word of the resource type name. For example, a resource of type
   199  `aws_instance` uses the default (un-aliased) `aws` provider configuration unless
   200  otherwise stated.
   201  
   202  To select an aliased provider for a resource or data source, set its `provider`
   203  meta-argument to a `<PROVIDER NAME>.<ALIAS>` reference:
   204  
   205  ```hcl
   206  resource "aws_instance" "foo" {
   207    provider = aws.west
   208  
   209    # ...
   210  }
   211  ```
   212  
   213  To select aliased providers for a child module, use its `providers`
   214  meta-argument to specify which aliased providers should be mapped to which local
   215  provider names inside the module:
   216  
   217  ```hcl
   218  module "aws_vpc" {
   219    source = "./aws_vpc"
   220    providers = {
   221      aws = aws.west
   222    }
   223  }
   224  ```
   225  
   226  Modules have some special requirements when passing in providers; see
   227  [Providers within Modules](./modules.html#providers-within-modules)
   228  for more details. In most cases, only _root modules_ should define provider
   229  configurations, with all child modules obtaining their provider configurations
   230  from their parents.
   231  
   232  ## Third-party Plugins
   233  
   234  Anyone can develop and distribute their own Terraform providers. (See
   235  [Writing Custom Providers](/docs/extend/writing-custom-providers.html) for more
   236  about provider development.) These third-party providers must be manually
   237  installed, since `terraform init` cannot automatically download them.
   238  
   239  Install third-party providers by placing their plugin executables in the user
   240  plugins directory. The user plugins directory is in one of the following
   241  locations, depending on the host operating system:
   242  
   243  Operating system  | User plugins directory
   244  ------------------|-----------------------
   245  Windows           | `%APPDATA%\terraform.d\plugins`
   246  All other systems | `~/.terraform.d/plugins`
   247  
   248  Once a plugin is installed, `terraform init` can initialize it normally. You must run this command from the directory where the configuration files are located.
   249  
   250  Providers distributed by HashiCorp can also go in the user plugins directory. If
   251  a manually installed version meets the configuration's version constraints,
   252  Terraform will use it instead of downloading that provider. This is useful in
   253  airgapped environments and when testing pre-release provider builds.
   254  
   255  ### Plugin Names and Versions
   256  
   257  The naming scheme for provider plugins is `terraform-provider-<NAME>_vX.Y.Z`,
   258  and Terraform uses the name to understand the name and version of a particular
   259  provider binary.
   260  
   261  If multiple versions of a plugin are installed, Terraform will use the newest
   262  version that meets the configuration's version constraints.
   263  
   264  Third-party plugins are often distributed with an appropriate filename already
   265  set in the distribution archive, so that they can be extracted directly into the
   266  user plugins directory.
   267  
   268  ### OS and Architecture Directories
   269  
   270  Terraform plugins are compiled for a specific operating system and architecture,
   271  and any plugins in the root of the user plugins directory must be compiled for
   272  the current system.
   273  
   274  If you use the same plugins directory on multiple systems, you can install
   275  plugins into subdirectories with a naming scheme of `<OS>_<ARCH>` (for example,
   276  `darwin_amd64`). Terraform uses plugins from the root of the plugins directory
   277  and from the subdirectory that corresponds to the current system, ignoring
   278  other subdirectories.
   279  
   280  Terraform's OS and architecture strings are the standard ones used by the Go
   281  language. The following are the most common:
   282  
   283  * `darwin_amd64`
   284  * `freebsd_386`
   285  * `freebsd_amd64`
   286  * `freebsd_arm`
   287  * `linux_386`
   288  * `linux_amd64`
   289  * `linux_arm`
   290  * `openbsd_386`
   291  * `openbsd_amd64`
   292  * `solaris_amd64`
   293  * `windows_386`
   294  * `windows_amd64`
   295  
   296  ## Provider Plugin Cache
   297  
   298  By default, `terraform init` downloads plugins into a subdirectory of the
   299  working directory so that each working directory is self-contained. As a
   300  consequence, if you have multiple configurations that use the same provider
   301  then a separate copy of its plugin will be downloaded for each configuration.
   302  
   303  Given that provider plugins can be quite large (on the order of hundreds of
   304  megabytes), this default behavior can be inconvenient for those with slow
   305  or metered Internet connections. Therefore Terraform optionally allows the
   306  use of a local directory as a shared plugin cache, which then allows each
   307  distinct plugin binary to be downloaded only once.
   308  
   309  To enable the plugin cache, use the `plugin_cache_dir` setting in
   310  [the CLI configuration file](/docs/commands/cli-config.html).
   311  For example:
   312  
   313  ```hcl
   314  # (Note that the CLI configuration file is _not_ the same as the .tf files
   315  #  used to configure infrastructure.)
   316  
   317  plugin_cache_dir = "$HOME/.terraform.d/plugin-cache"
   318  ```
   319  
   320  This directory must already exist before Terraform will cache plugins;
   321  Terraform will not create the directory itself.
   322  
   323  Please note that on Windows it is necessary to use forward slash separators
   324  (`/`) rather than the conventional backslash (`\`) since the configuration
   325  file parser considers a backslash to begin an escape sequence.
   326  
   327  Setting this in the configuration file is the recommended approach for a
   328  persistent setting. Alternatively, the `TF_PLUGIN_CACHE_DIR` environment
   329  variable can be used to enable caching or to override an existing cache
   330  directory within a particular shell session:
   331  
   332  ```bash
   333  export TF_PLUGIN_CACHE_DIR="$HOME/.terraform.d/plugin-cache"
   334  ```
   335  
   336  When a plugin cache directory is enabled, the `terraform init` command will
   337  still access the plugin distribution server to obtain metadata about which
   338  plugins are available, but once a suitable version has been selected it will
   339  first check to see if the selected plugin is already available in the cache
   340  directory. If so, the already-downloaded plugin binary will be used.
   341  
   342  If the selected plugin is not already in the cache, it will be downloaded
   343  into the cache first and then copied from there into the correct location
   344  under your current working directory.
   345  
   346  When possible, Terraform will use hardlinks or symlinks to avoid storing
   347  a separate copy of a cached plugin in multiple directories. At present, this
   348  is not supported on Windows and instead a copy is always created.
   349  
   350  The plugin cache directory must _not_ be the third-party plugin directory
   351  or any other directory Terraform searches for pre-installed plugins, since
   352  the cache management logic conflicts with the normal plugin discovery logic
   353  when operating on the same directory.
   354  
   355  Please note that Terraform will never itself delete a plugin from the
   356  plugin cache once it's been placed there. Over time, as plugins are upgraded,
   357  the cache directory may grow to contain several unused versions which must be
   358  manually deleted.