github.com/ben-turner/terraform@v0.11.8-0.20180503104400-0cc9e050ecd4/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 Most providers require some sort of configuration to provide 16 authentication information, endpoint URLs, etc. Where explicit configuration 17 is required, a `provider` block is used within the configuration as 18 illustrated in the following sections. 19 20 By default, resources are matched with provider configurations by matching 21 the start of the resource name. For example, a resource of type 22 `vsphere_virtual_machine` is associated with a provider called `vsphere`. 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 A `provider` block represents a configuration for the provider named in its 43 header. For example, `provider "aws"` above is a configuration for the 44 `aws` provider. 45 46 Within the block body (between `{ }`) is configuration for the provider. 47 The configuration is dependent on the type, and is documented 48 [for each provider](/docs/providers/index.html). 49 50 The arguments `alias` and `version`, if present, are special arguments 51 handled by Terraform Core for their respective features described above. All 52 other arguments are defined by the provider itself. 53 54 A `provider` block may be omitted if its body would be empty. Using a resource 55 in configuration implicitly creates an empty provider configuration for it 56 unless a `provider` block is explicitly provided. 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 The `version` attribute value may either be a single explicit version or 114 a version constraint expression. Constraint expressions use the following 115 syntax to specify a _range_ of versions that are acceptable: 116 117 * `>= 1.2.0`: version 1.2.0 or newer 118 * `<= 1.2.0`: version 1.2.0 or older 119 * `~> 1.2.0`: any non-beta version `>= 1.2.0` and `< 1.3.0`, e.g. `1.2.X` 120 * `~> 1.2`: any non-beta version `>= 1.2.0` and `< 2.0.0`, e.g. `1.X.Y` 121 * `>= 1.0.0, <= 2.0.0`: any version between 1.0.0 and 2.0.0 inclusive 122 123 When `terraform init` is re-run with providers already installed, it will 124 use an already-installed provider that meets the constraints in preference 125 to downloading a new version. To upgrade to the latest acceptable version 126 of each provider, run `terraform init -upgrade`. This command also upgrades 127 to the latest versions of all Terraform modules. 128 129 ## Multiple Provider Instances 130 131 You can define multiple configurations for the same provider in order to support 132 multiple regions, multiple hosts, etc. The primary use case for this is 133 using multiple cloud regions. Other use-cases include targeting multiple 134 Docker hosts, multiple Consul hosts, etc. 135 136 To include multiple configurations for a given provider, include multiple 137 `provider` blocks with the same provider name, but set the `alias` field to an 138 instance name to use for each additional instance. For example: 139 140 ```hcl 141 # The default provider configuration 142 provider "aws" { 143 # ... 144 } 145 146 # Additional provider configuration for west coast region 147 provider "aws" { 148 alias = "west" 149 region = "us-west-2" 150 } 151 ``` 152 153 A `provider` block with out `alias` set is known as the _default_ provider 154 configuration. When `alias` is set, it creates an _additional_ provider 155 configuration. For providers that have no required configuration arguments, the 156 implied _empty_ configuration is also considered to be a _default_ provider 157 configuration. 158 159 Resources are normally associated with the default provider configuration 160 inferred from the resource type name. For example, a resource of type 161 `aws_instance` uses the _default_ (un-aliased) `aws` provider configuration 162 unless otherwise stated. 163 164 The `provider` argument within any `resource` or `data` block overrides this 165 default behavior and allows an additional provider configuration to be 166 selected using its alias: 167 168 ```hcl 169 resource "aws_instance" "foo" { 170 provider = "aws.west" 171 172 # ... 173 } 174 ``` 175 176 The value of the `provider` argument is always the provider name and an 177 alias separated by a period, such as `"aws.west"` above. 178 179 Provider configurations may also be passed from a parent module into a 180 child module, as described in 181 [_Providers within Modules_](/docs/modules/usage.html#providers-within-modules). 182 183 ## Interpolation 184 185 Provider configurations may use [interpolation syntax](/docs/configuration/interpolation.html) 186 to allow dynamic configuration: 187 188 ```hcl 189 provider "aws" { 190 region = "${var.aws_region}" 191 } 192 ``` 193 194 Interpolation is supported only for the per-provider configuration arguments. 195 It is not supported for the special `alias` and `version` arguments. 196 197 Although in principle it is possible to use any interpolation expression within 198 a provider configuration argument, providers must be configurable to perform 199 almost all operations within Terraform, and so it is not possible to use 200 expressions whose value cannot be known until after configuration is applied, 201 such as the id of a resource. 202 203 It is always valid to use [input variables](/docs/configuration/variables.html) 204 and [data sources](/docs/configuration/data-sources.html) whose configurations 205 do not in turn depend on as-yet-unknown values. [Local values](/docs/configuration/locals.html) 206 may also be used, but currently may cause errors when running `terraform destroy`. 207 208 ## Third-party Plugins 209 210 At present Terraform can automatically install only the providers distributed 211 by HashiCorp. Third-party providers can be manually installed by placing 212 their plugin executables in one of the following locations depending on the 213 host operating system: 214 215 * On Windows, in the sub-path `terraform.d/plugins` beneath your user's 216 "Application Data" directory. 217 * On all other systems, in the sub-path `.terraform.d/plugins` in your 218 user's home directory. 219 220 `terraform init` will search this directory for additional plugins during 221 plugin initialization. 222 223 The naming scheme for provider plugins is `terraform-provider-NAME_vX.Y.Z`, 224 and Terraform uses the name to understand the name and version of a particular 225 provider binary. Third-party plugins will often be distributed with an 226 appropriate filename already set in the distribution archive so that it can 227 be extracted directly into the plugin directory described above. 228 229 ## Provider Plugin Cache 230 231 By default, `terraform init` downloads plugins into a subdirectory of the 232 working directory so that each working directory is self-contained. As a 233 consequence, if you have multiple configurations that use the same provider 234 then a separate copy of its plugin will be downloaded for each configuration. 235 236 Given that provider plugins can be quite large (on the order of hundreds of 237 megabytes), this default behavior can be inconvenient for those with slow 238 or metered Internet connections. Therefore Terraform optionally allows the 239 use of a local directory as a shared plugin cache, which then allows each 240 distinct plugin binary to be downloaded only once. 241 242 To enable the plugin cache, use the `plugin_cache_dir` setting in 243 [the CLI configuration file](https://www.terraform.io/docs/commands/cli-config.html). 244 For example: 245 246 ```hcl 247 # (Note that the CLI configuration file is _not_ the same as the .tf files 248 # used to configure infrastructure.) 249 250 plugin_cache_dir = "$HOME/.terraform.d/plugin-cache" 251 ``` 252 253 This directory must already exist before Terraform will cache plugins; 254 Terraform will not create the directory itself. 255 256 Please note that on Windows it is necessary to use forward slash separators 257 (`/`) rather than the conventional backslash (`\`) since the configuration 258 file parser considers a backslash to begin an escape sequence. 259 260 Setting this in the configuration file is the recommended approach for a 261 persistent setting. Alternatively, the `TF_PLUGIN_CACHE_DIR` environment 262 variable can be used to enable caching or to override an existing cache 263 directory within a particular shell session: 264 265 ```bash 266 export TF_PLUGIN_CACHE_DIR="$HOME/.terraform.d/plugin-cache" 267 ``` 268 269 When a plugin cache directory is enabled, the `terraform init` command will 270 still access the plugin distribution server to obtain metadata about which 271 plugins are available, but once a suitable version has been selected it will 272 first check to see if the selected plugin is already available in the cache 273 directory. If so, the already-downloaded plugin binary will be used. 274 275 If the selected plugin is not already in the cache, it will be downloaded 276 into the cache first and then copied from there into the correct location 277 under your current working directory. 278 279 When possible, Terraform will use hardlinks or symlinks to avoid storing 280 a separate copy of a cached plugin in multiple directories. At present, this 281 is not supported on Windows and instead a copy is always created. 282 283 The plugin cache directory must *not* be the third-party plugin directory 284 or any other directory Terraform searches for pre-installed plugins, since 285 the cache management logic conflicts with the normal plugin discovery logic 286 when operating on the same directory. 287 288 Please note that Terraform will never itself delete a plugin from the 289 plugin cache once it's been placed there. Over time, as plugins are upgraded, 290 the cache directory may grow to contain several unused versions which must be 291 manually deleted.