Using custom and community providers in Terraform Cloud and Enterprise

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:

1. Create a separate repository for your custom provider (the “provider repository”).
2. Compile a linux_amd64 binary for your provider and make it executable using chmod +x.
3. Upload the binary to the root of your provider repository.
4. 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.
5. 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.

1. Within the providers block of the terraform-bundle.hcl configuration file, add the custom provider with the following format.

     providers {
       my-custom-provider = ["1.0"]
      }

1. Create a ./plugins subdirectory in the directory that terraform-bundle will be run in. Optionally, you can use the -plugin-dir flag to specify a location of where to find the provider.

2. Place the custom or community provider in the ./plugins directory. To be recognized, custom providers must have a name following the form of terraform-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 be linux_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.