Request Forwarding
You can configure Terraform Cloud Agents to handle HTTP and HTTPS request forwarding on behalf of Terraform Cloud. This enables Terraform Cloud to access services in private networks without requiring direct inbound network access.
Only specific features and use cases will use agent request forwarding to fulfill requests.
Note: Refer to Terraform Cloud pricing for details on which features can use request forwarding.
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 Terraform Cloud via outbound-only connections. Terraform Cloud holds these connections open and uses them to transmit requests and responses between the target API and Terraform Cloud.
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 Terraform Cloud as the target for various features which require access to private network resources. This creates the mapping from Terraform Cloud 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:
These log messages indicate that the agent has successfully connected to Terraform Cloud and is ready to start forwarding requests.
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 Terraform Cloud 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 Terraform Cloud 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 Terraform Cloud 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 Terraform Cloud.
Security considerations
The agent application secures forwarded requests by ensuring that requests may only be forwarded through the agent which originate from Terraform Cloud. 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.