How To Set Up Provider Installation in Terraform Enterprise

Avatar
Darrell F. Williams
  • Updated

Introduction

Terraform CLI version 0.13 and later offers methods for provider installation in addition to the default provider registry. In order to override the default provider installation method, a provider_installation block must be set in the Terraform configuration file.

In Terraform Enterprise, the configuration file is dynamically generated for each run and contains internal information required by Terraform Enterprise. Since the configuration file is managed internally and dynamically, it is not possible to edit the configuration file to add the provider_installation block directly. This article provides the steps to configure the provider_installation block in Terraform Enterprise.

Use Case

This article is applicable to Terraform Enterprise users who require non-default provider installation methods.

Procedure A: Terraform Enterprise custom worker image (build workers, <v202302-1)

  1. In order to add provider_installation into the generated Terraform configuration file, a custom worker image is required. The most important consideration when creating a custom worker image is ensuring it meets the defined requirements. As long as the requirements are met, additional tools or scripts may be added as needed.

  2. Create an initialization script for the custom worker image which contains the logic to append the required provider_installation block into the generated Terraform configuration file (located at /tmp/cli.tfrc). The example below is the script for configuring the network mirror installation method.

     # /usr/local/bin/init_custom_worker.sh

 #!/bin/bash

 cat >> /tmp/cli.tfrc <<EOF
 provider_installation {
   network_mirror {
     url = "https://providers.tfe-example.com/artifactory/terraform-providers/"
   }
 }
 EOF
  3. Add the initialize script created in the previous step to the custom worker image. Please note that there are strict requirements and notes around the file path and permissions of the script.
  4. Make sure that Terraform Enterprise is configured to use the custom worker image by opening the installer dashboard at port 8800 of the installation and choosing Settings > Terraform Build Worker Image > Provide the location of a custom image. Please note that an application restart is required for the custom worker image configuration to take effect.

 

Procedure B: tfc-agent (HCP Terraform Agents, >=v202302-1)

If your Terraform Enterprise organization/workspaces execute runs via agents (tfc-agent), the default run pipeline since v202302-1, you can’t use the worker “initialize script” mechanism. Instead, use agent hooks (both pre-plan and pre-apply) to ensure the CLI config contains your provider_installation block before Terraform runs init.

Create a custom tfc-agent image with hooks

Create a directory structure as shown below. Please visit the provider installation page for further information of the Terraform configuration file.

mkdir -p ~/custom_tfc_agent/hooks
cd ~/custom_tfc_agent

Create a Dockerfile based on the official agent image with an ADD directive to copy the hooks directory to /home/tfc-agent/.tfc-agent/hooks

FROM hashicorp/tfc-agent:latest
USER root
# (Optional) install packages/tools, add certs, etc.
ADD --chown=tfc-agent:tfc-agent hooks /home/tfc-agent/.tfc-agent/hooks
USER tfc-agent

Add pre-plan and pre-apply hook scripts to write provider_installation

Agent hooks run at specific points in the run; pre-plan and pre-apply run before terraform init.

Create hooks/terraform-pre-plan and copy it to hooks/terraform-pre-apply with the following content (adjust the configuration for your purposes):

#!/bin/bash

cat <<EOF >> $HOME/.terraformrc
provider_installation {
  network_mirror {
    url = "https://mirror.example.com/repository/providers/"
    include = ["example.com/*/*"]
  }
  direct {
    exclude = ["example.com/*/*"]
  }
}
EOF

Then, make the scripts executable.

chmod +x ~/custom_tfc_agent/hooks/*

Finally, build the image and push it to your container registry. If this will be used for remote runs in Terraform Enterprise, pull the image to your Terraform Enterprise nodes and configure the TFE_RUN_PIPELINE_IMAGE setting in Terraform Enterprise with the image tag.

Additional Information

Articles in this section

See more

Related articles