How To Set Up Provider Installation in Terraform Enterprise – HashiCorp Help Center

Introduction

Terraform CLI version 0.13 and later offers methods for provider installation beyond the default public Terraform Registry. To override the default provider installation method, you must define a provider_installation block in the Terraform CLI configuration file.

In Terraform Enterprise, the CLI configuration file is dynamically generated for each run and contains internal information required by the system. Because this file is managed internally, you cannot edit it directly to add the provider_installation block.

This article provides two methods to configure the provider_installation block in Terraform Enterprise, depending on your version and configuration.

Use Case

This procedure applies to Terraform Enterprise users who require non-default provider installation methods, such as sourcing providers from a network mirror or a local filesystem mirror.

Procedure

There are two methods to configure provider installation depending on your Terraform Enterprise version and run execution mode.

Method 1: Using a Custom Worker Image (TFE versions before v202302-1)

For older Terraform Enterprise instances that use the default build workers, you must use a custom worker image with an initialization script.

Create a custom worker image. The image must meet the defined requirements for custom build workers. You can add additional tools or scripts to this image as needed.
Create an initialization script. This script appends the required provider_installation block to the dynamically generated Terraform configuration file at /tmp/cli.tfrc. The following example configures the network mirror installation method. Create this script at /usr/local/bin/init_custom_worker.sh within your custom image.
```
#!/bin/bash
cat >> /tmp/cli.tfrc <<EOF
provider_installation {
  network_mirror {
    url = "https://providers.tfe-example.com/artifactory/terraform-providers/"
  }
}
EOF
```
Add the initialize script to the image. Ensure the script follows the strict requirements for file path and permissions.
Configure Terraform Enterprise. In the installer dashboard (port 8800), navigate to Settings > Terraform Build Worker Image and select Provide the location of a custom image. Enter the location of your custom image. An application restart is required for the change to take effect.

Method 2: Using tfc-agent Hooks (TFE versions v202302-1 and later)

If your Terraform Enterprise workspaces execute runs using tfc-agent, which is the default run pipeline since version v202302-1, you must use agent hooks to modify the CLI configuration.

Create a directory structure for the custom agent image.

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

Create a Dockerfile. This file builds upon the official tfc-agent image and adds your custom 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 hook scripts. Create pre-plan and pre-apply hook scripts to write the provider_installation block to the user's .terraformrc file before terraform init runs. Create the file hooks/terraform-pre-plan with the following content, adjusting the configuration for your environment.
```
#!/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
```

Copy the script and make both executable.

$ cp ~/custom_tfc_agent/hooks/terraform-pre-plan ~/custom_tfc_agent/hooks/terraform-pre-apply
$ chmod +x ~/custom_tfc_agent/hooks/*

Build and configure the agent image. Build the Docker image and push it to your container registry. Pull the image to your Terraform Enterprise nodes and configure the TFE_RUN_PIPELINE_IMAGE setting to use your new image tag.

Additional Information