How to Configure HCP Terraform Agent with Proxy and Custom CA Certificate

Steps

Introduction

This article explains how to configure an HCP Terraform Agent to run behind an outbound proxy and trust a custom Certificate Authority (CA) certificate. This configuration is required in environments where outbound internet traffic must pass through a corporate proxy that performs TLS inspection or requires a custom CA certificate.

The guide also explains how to validate that outbound traffic from the agent is successfully routed through the proxy.

Use Case

Organizations with restricted network environments often require all outbound traffic to go through a corporate proxy. In such cases:

• Direct internet egress is blocked.

• Proxy servers handle outbound requests.

• TLS inspection may require clients to trust an internal CA certificate.

To allow the HCP Terraform Agent to communicate with Terraform Cloud, the proxy configuration and CA certificate must be provided to the agent container.

Procedure

Step 1: Export Required Environment Variables

Set the agent token and agent name before running the container.

export TFC_AGENT_TOKEN="your_agent_token"
export TFC_AGENT_NAME="agent-name"

Step 2: Run the HCP Terraform Agent Container With Proxy Configuration

Run the container with the proxy environment variables and mount the CA certificate.

docker run -d \
--name tfc-agent \
--platform=linux/amd64 \
-e TFC_AGENT_TOKEN=$TFC_AGENT_TOKEN \
-e TFC_AGENT_NAME=$TFC_AGENT_NAME \
-e TFC_AGENT_LOG_LEVEL=TRACE \
-e HTTP_PROXY=http://proxy-host:port \
-e HTTPS_PROXY=http://proxy-host:port \
-e NO_PROXY="127.0.0.1,localhost" \
-e SSL_CERT_FILE=/home/tfc-agent/proxy-ca.pem \
-e REQUESTS_CA_BUNDLE=/home/tfc-agent/proxy-ca.pem \
-v /path/to/proxy-ca.pem:/home/tfc-agent/proxy-ca.pem \
hashicorp/tfc-agent:latest

Step 3: Ensure Required Terraform Cloud Domains Are Whitelisted

Your network ACL or proxy must allow outbound connectivity to required Terraform Cloud endpoints as mentioned in the networking requirements -  https://developer.hashicorp.com/terraform/cloud-docs/agents/requirements#networking

Step 4: Validate Proxy Connectivity Using curl

Once the container is running, validate connectivity through the proxy using the Terraform Cloud API.

curl -v --proxy "$HTTP_PROXY" \
--cacert /home/ec2-user/bundle.crt \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/vnd.api+json" \
https://app.terraform.io/api/v2/account/details

To confirm that the proxy is used, look for the following indicators in the verbose curl output:

* Connected to <proxy-host> port <port>
* Establish HTTP proxy tunnel to app.terraform.io:443
> CONNECT app.terraform.io:443 HTTP/1.1
< HTTP/1.1 200 Connection established

These messages indicate the request is being tunneled through the proxy. You can also try validating it in agent logs.

Additional Information

• Terraform Cloud Agent Documentation: https://developer.hashicorp.com/terraform/cloud-docs/agents 

• Networking Requirements: https://developer.hashicorp.com/terraform/cloud-docs/agents/requirements#networking

• If you're still experiencing issues, please contact HCP Terraform Support by submitting a ticket through our support portal