Terraform 0.13 has an entirely new provider installer that allows for greater control over individual provider installation methods. The breaking change is a new, required, subdirectory hierarchy for provider binaries.
Terraform v0.12 Provider Installer
The key differences between Terraform v0.12 and v0.13 are the directory hierarchy. Terraform v0.12 would look for a provider binary under the following directories:
- Filesystem
- Terraform Registry
- Windows:
%APPDATA%\terraform.d\plugins - All others:
~/.terraform.d/plugins - Location of the terraform binary (/usr/local/bin, for example)
terraform.d/plugins/<OS>_<ARCH>For airgapped installations; seeterraform-bundle
Terraform queries the Registry for providers:
- if a compatible provider is not found locally
- unless the
-upgradeflag is set
-plugin-dir: disables registry lookup; only search that directory (note: still searches.terraform/pluginsfor already-installed providers)plugin-cache-dir: search and install providers to the configured directory. Terraform will search other locations, including the registry, as usual.-upgrade: query the registry for all providers required by the local configuration and install the latest matching version.
Default:
.terraform/plugins
Options:
-plugin-cache-dir: does not change search paths; installs providers into the specified directory
A major implication of the provider source work is that terraform can no longer assume that provider types are unique: a user could have multiple provides with the same type in a given configuration. To support this, terraform now requires the all provider binaries are in a specific directory hierarchy corresponding with the source:
$BASEDIR/$SOURCEHOST/$NAMESPACE/$TYPE/$VERSION/$OS_$ARCH/
- Filesystem
- Terraform Registry
Default:
.terraform.d/pluginsrelative to the CLI configuration directory (configurable, defaults to$HOME/)terraform.d/pluginsin the current working directory (documented interraform-bundleas a place to put plugins as a way to include them in bundles uploaded to Terraform Cloud).terraform/pluginsrelative to configuration for any already-installed plugins
OS-specific paths:
- Windows:
%APPDATA%/HashiCorp/Terraform/plugins - Mac OS X:
~/Library/Application Support/io.terraform/pluginsand/Library/Application Support/io.terraform/plugins - Linux and other Unix-like systems: Terraform implements the
XDG Base Directory
specification and appends
terraform/pluginsto all of the specified data directories. Without any XDG environment variables set, Terraform will use~/.local/share/terraform/plugins,/usr/local/share/terraform/plugins, and/usr/share/terraform/plugins.
-plugin-dircommand-line flag: only that directory will be searched (no registry lookup). Command-line options override CLI configuration file options.plugin-cache-dir: search and install providers to the configured directory. Terraform will search other locations, including the registry, as usual.-upgrade: query the registry for all providers required by the local configuration and install the latest matching version.
Same use-facing behavior as 0.12: terraform queries the registry to find providers.
If a provider is found in one of the search paths, terraform will not query the registry for that provider (unless the -upgrade command line flag is used).
We've added a CLI configuration setting, provider_installtion, to let users declare plugin search locations for all configurations on a given workstation. This setting overrides the default behavior.
filesystem_mirror: used to declare custom local filesystemsdirect: used to configure the registry provider search behaviornetwork_mirror: used to declare custom network filesystems [targeting future 0.13.* release]
Default:
.terraform/plugins/$SOURCEHOST/$NAMESPACE/$TYPE/$VERSION/$OS_$ARCH/
Options:
-plugin-cache-dircommand-line flag: does not change search behavior, just install: plugins will be downloaded into, and installed from, the cache dirplugin_cache_dirCLI config setting: same as above.