How-to Configure Provider Network Mirroring for Agent-Based Execution in HCP Terraform

Avatar
Yashi Chauhan
  • Updated

Introduction

This Knowledge Base (KB) article explains how to configure Terraform provider network mirrors when running HCP Terraform workspaces in Agent execution mode, especially in scenarios where the same configuration previously worked in Local execution mode.

Expected Outcome

After completing this guide, you will be able to:

  • Configure a provider network mirror (for example, JFrog Artifactory) for Terraform
  • Run HCP Terraform workspaces using Agent-based execution with provider mirroring enabled
  • Ensure Terraform Agents can authenticate to both the network mirror and app.terraform.io
  • Control provider source resolution without direct access to registry.terraform.io

Prerequisites 

  •  HCP Terraform organization
  • Terraform workspace configured for Agent execution mode
  • Terraform Agents deployed (Docker or VM-based)
  • Access to a provider network mirror Artifactory. (for example, JFrog Artifactory)
  • User or team API token for HCP Terraform

Procedure

1. Configure Artifactory as a Terraform Provider Network Mirror. 

  • In Artifactory, configure a repository that serves Terraform providers using the network mirror layout. Refer to JFrog documentation for creating a Terraform provider repository.
  • Generate an access token in Artifactory with permissions to read from the Terraform provider repository. This token will be supplied to Terraform via environment variables. You will get the token and initial setup as shown in below screenshot.

2. Configure Terraform .terraformrc file for Network Mirroring. Add the credentials block for the Artifactory and for the app.terraform.io authentication. Please find the sample configuration below:

  • #Note: Use a HCP Terraform user or team API token as authentication is required for network mirroring
credentials "mirrortesting.jfrog.io" {
#you can hardcode the token like below if you don't want to use env varibales.
token = "cmVmdGtuOjA------qcE5FcHE2SnhwNWhT"  
}

#below is the example is you want environment variables instead of hardcoding.
credentials "app.terraform.io" {
token = "${TFE_TOKEN}"
}

provider_installation {
direct {
exclude = ["registry.terraform.io/*/*"]
}

network_mirror {
url = "https://[JFrogPlatformURL]/artifactory/api/terraform/<REPOSITORY-KEY>/providers/"
}
}

3. Build or Configure the Terraform Agent Image. Ensure the .terraformrc file is present inside the agent filesystem, for example:

  • /home/tfc-agent/.terraformrc
  • This can be done by: Baking the file into a custom agent image or Mounting it as a file at runtime.

4. Configure Environment Variables for the runs in HCP Terraform.

  • Please find the below screenshot for your reference. 
    ARTIFACTORY_TOKEN=<artifactory-token> as this is hardcoded for my case, we don't need to add an environment variable.

    TFE_TOKEN=<hcp-terraform-user-or-team-token>
    TF_CLI_CONFIG_FILE=/path/to/.terraformrc

5. Update the Workspace to Use Agent Execution Mode
  • Navigate to the workspace in HCP Terraform
  • Open Settings → General
  • Set Execution Mode to Agent
  • Select the appropriate Agent Pool
  • Save the changes

6. Initiate a terraform run and validate your provider settings.

Additional Information

 
 

Articles in this section

See more

Related articles