Use Case
The use of custom and community providers in Terraform Cloud and Terraform Enterprise is outlined in our Custom and Community Providers documentation. There are two options; place the provider binary in the repository (Terraform Cloud or Terraform Enterprise) or build a custom Terraform bundle (Terraform Enterprise).
Procedure
Using Git submodules for commonly used providers
When the same provider is used across many repositories, we recommend using Git submodules to avoid the need to place custom providers in each of your configuration repositories. To do so, use the following steps:
- Create a separate repository for your custom provider (the “provider repository”).
- Compile a
linux_amd64
binary for your provider and make it executable usingchmod +x
. - Upload the binary to the root of your provider repository.
- Both Terraform Cloud and Terraform Enterprise check for custom providers in a path relative to the location where Terraform is run. Navigate to the root of your configuration repository, or the Terraform Working Directory.
- Add a submodule to the configuration repository that references the provider repository with the following command, replacing
$ORGANIZATION
and$REPOSITORY
with the VCS organization and repository that the provider is in:
Note: Since there is no way to pass HTTPS credentials during a Terraform run, the following method assumes that the user is cloning a publicly available repository. If you are instead using a repository that is not publicly available, the user must instead provide SSH keys in the VCS connection settings and clone over SSH.
$ git submodule add \
https://github.com/$ORGANIZATION/$REPOSITORY.git \
terraform.d/plugins/linux_amd64
Workspaces with custom providers must have Include submodules on clone enabled in order for the custom or community provider to be downloaded. This option can be found in a Workspace’s settings under “Version Control”.
Note: When a provider binary is updated, the submodule in any configuration repository that references it will also need to be updated.
Using a custom Terraform bundle
When using Terraform Enterprise, it is also possible to include custom and community providers in a custom Terraform bundle. The steps to set up the terraform-bundle
CLI tool are outside of the scope of this document, so the below steps will assume that terraform-bundle
has already been compiled and is in the $PATH
.
- Within the
providers
block of theterraform-bundle.hcl
configuration file, add the custom provider with the following format.
providers {
my-custom-provider = ["1.0"]
}
-
Create a
./plugins
subdirectory in the directory thatterraform-bundle
will be run in. Optionally, you can use the-plugin-dir
flag to specify a location of where to find the provider. -
Place the custom or community provider in the
./plugins
directory. To be recognized, custom providers must have a name following the form ofterraform-provider-<NAME>_v<VERSION>
. In addition, ensure that the provider is built using the same operating system and architecture used for Terraform Enterprise. Typically this will belinux_amd64
.
Additional Information
Eventually, these steps will not be necessary, and will instead be replaced with Providers in the Terraform Registry. This feature will first be available to Terraform Cloud users, with work planned to later introduce it to Terraform Enterprise.