This is an initial draft of documentation for this new feature of the
CLI configuration. This is mainly intended as a placeholder for now,
because there are other documentation updates pending for the new provider
namespacing and installation scheme and we'll likely want to revise these
docs to better complement the broader documentation once it's written.
Anyone can develop and distribute their own Terraform providers. (See
[Writing Custom Providers](/docs/extend/writing-custom-providers.html) for more
about provider development.) These third-party providers must be manually
installed, since `terraform init` cannot automatically download them.
Install third-party providers by placing their plugin executables in the user
plugins directory. The user plugins directory is in one of the following
locations, depending on the host operating system:
Operating system | User plugins directory
------------------|-----------------------
Windows | `%APPDATA%\terraform.d\plugins`
All other systems | `~/.terraform.d/plugins`
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.
Providers distributed by HashiCorp can also go in the user plugins directory. If
a manually installed version meets the configuration's version constraints,
Terraform will use it instead of downloading that provider. This is useful in
airgapped environments and when testing pre-release provider builds.
### Plugin Names and Versions
The naming scheme for provider plugins is `terraform-provider-<NAME>_vX.Y.Z`,
and Terraform uses the name to understand the name and version of a particular
provider binary.
If multiple versions of a plugin are installed, Terraform will use the newest
version that meets the configuration's version constraints.
Third-party plugins are often distributed with an appropriate filename already
set in the distribution archive, so that they can be extracted directly into the
user plugins directory.
### OS and Architecture Directories
Terraform plugins are compiled for a specific operating system and architecture,
and any plugins in the root of the user plugins directory must be compiled for
the current system.
If you use the same plugins directory on multiple systems, you can install
plugins into subdirectories with a naming scheme of `<OS>_<ARCH>` (for example,
`darwin_amd64`). Terraform uses plugins from the root of the plugins directory
and from the subdirectory that corresponds to the current system, ignoring
other subdirectories.
Terraform's OS and architecture strings are the standard ones used by the Go
language. The following are the most common:
* `darwin_amd64`
* `freebsd_386`
* `freebsd_amd64`
* `freebsd_arm`
* `linux_386`
* `linux_amd64`
* `linux_arm`
* `openbsd_386`
* `openbsd_amd64`
* `solaris_amd64`
* `windows_386`
* `windows_amd64`
about provider development.)
The main way to distribute a provider is via a provider registry, and the main
provider registry is
[part of the public Terraform Registry](https://registry.terraform.io/browse/providers),
along with public shared modules.
Providers distributed via a public registry to not require any special
additional configuration to use, once you know their source addresses. You can
specify both official and third-party source addresses in the
`required_providers` block in your module:
```hcl
terraform {
required_providers {
# An example third-party provider. Not actually available.
example = {
source = "example.com/examplecorp/example"
}
}
}
```
Installing directly from a registry is not appropriate for all situations,
though. If you are running Terraform from a system that cannot access some or
all of the necessary origin registries, you can configure Terraform to obtain
providers from a local mirror instead. For more information, see
Martin Atkins
6 years ago