Request Forwarding

You can configure HCP Terraform Agents to handle HTTP and HTTPS request forwarding on behalf of HCP Terraform. This enables HCP Terraform to access services in private networks without requiring direct inbound network access.

Only specific features and use cases use agent request forwarding to fulfill requests.

Request Forwarding Architecture

Request forwarding is an additional function that you can enable on a per-agent basis. Agents are deployed into private networks where they have direct access to the target private services, such as private version control systems or other APIs. Agents register with HCP Terraform via outbound-only connections. HCP Terraform holds these connections open and uses them to transmit requests and responses between the target API and HCP Terraform.

Forwarded Request Routing

Request forwarding requires the use of agent pools. Each agent pool may have multiple agents registered with request forwarding enabled. The agent pool is then selected by the user in HCP Terraform as the target for various features which require access to private network resources. This creates the mapping from HCP Terraform resources (such as VCS connections) to a pool of agents capable of accessing the target API.

Agent Configuration

To enable request forwarding, start the agent with the -request-forwarding flag, or set the environment variable TFC_AGENT_REQUEST_FORWARDING=true. When the agent starts, you will see the following log messages:

[INFO]  core: Request forwarding is enabled
[INFO]  grpc_connector: Connected to broker, awaiting requests

These log messages indicate that the agent has successfully connected to HCP Terraform and is ready to start forwarding requests.

Optionally accept ingress jobs to access a private VCS

If you want to use a private VCS provider, you must configure your HCP Terraform agent to support private VCS by allowing access to those private repositories. To learn more, refer to Connect to Private VCS Providers.

Requirements and Limitations

Agent version 1.15.0+ is required to use request forwarding.

We recommend that you allocate at least 250MB of additional system memory specifically for request forwarding. This is in addition to the minimum system requirements.

Forwarded requests are limited to a 10MB response body. This limit comfortably supports all HCP Terraform operations while providing protection against unbounded responses.

All forwarded requests are subject to a request timeout. The default timeout is 60 seconds, but this value is tuned for specific features and use cases and may be set slightly higher or lower depending on the type of request being made.

Agents must be able to connect to HCP Terraform outbound over the internet, as well as to private infrastructure targets for request forwarding via HTTP and HTTPS.

Performance and Scaling

Each agent may handle multiple requests simultaneously. In many cases, a single agent may provide sufficient throughput to handle all forwarded requests. It is recommended that 2 or more agents with request forwarding enabled are deployed for each pool which will leverage request forwarding features. Running multiple request forwarding agents provides better fault tolerance and distribution of requests.

We recommend that you monitor the memory and CPU utilization on your agents with request forwarding enabled to determine if you need to deploy additional agents. Refer to runtime metrics for more details.

Since an agent may handle more than one forwarded request simultaneously, both horizontal (number of agents) and vertical (system resources per agent host) scaling vectors are important.

Egress Proxy Support

If your agents require an egress proxy to reach HCP Terraform over the internet, you can set the HTTPS_PROXY environment variable with your proxy's address when starting the agent. Your proxy software must support the HTTP CONNECT protocol, which the agent will use to establish a secure tunnel through the proxy to HCP Terraform.

Security considerations

The agent application secures forwarded requests by ensuring that requests may only be forwarded through the agent which originate from HCP Terraform. The agent guarantees this by requiring an authenticated session to be established prior to forwarding any requests.

Because forwarded requests and responses may contain sensitive information, such as API tokens to 3rd party vendors and PII, we recommend that production use cases use dedicated agents to handle request forwarding functionality. This ensures that no other processes executing user code will be running within the same process space and avoids certain attack vectors.

To dedicate an agent to request forwarding only, set the accepted workload types to none. This disables all workloads except for request forwarding from being executed.