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.