|
| 1 | +--- |
| 2 | +page_title: Terraform Cloud Agents - Request Forwarding |
| 3 | +description: >- |
| 4 | + Access private network resources using agents with request forwarding. |
| 5 | +--- |
| 6 | + |
| 7 | +# Request Forwarding |
| 8 | + |
| 9 | +You can configure Terraform Cloud Agents to handle HTTP and HTTPS |
| 10 | +request forwarding on behalf of Terraform Cloud. This enables Terraform Cloud to access |
| 11 | +services in private networks without requiring direct inbound network access. |
| 12 | + |
| 13 | +Only specific features and use cases will use agent request forwarding to |
| 14 | +fulfill requests. |
| 15 | + |
| 16 | +-> **Note:** Refer to [Terraform Cloud pricing](https://www.hashicorp.com/products/terraform/pricing) for details on which features can use request forwarding. |
| 17 | + |
| 18 | +## Request Forwarding Architecture |
| 19 | + |
| 20 | +Request forwarding is an additional function that you can enable on a per-agent |
| 21 | +basis. Agents are deployed into private networks where they have direct access |
| 22 | +to the target private services, such as private version control systems or other APIs. |
| 23 | +Agents register with Terraform Cloud via outbound-only connections. Terraform Cloud |
| 24 | +holds these connections open and uses them to transmit requests and responses |
| 25 | +between the target API and Terraform Cloud. |
| 26 | + |
| 27 | + |
| 28 | + |
| 29 | +## Forwarded Request Routing |
| 30 | + |
| 31 | +Request forwarding requires the use of [agent pools](/terraform/cloud-docs/agents/agent-pools). |
| 32 | +Each agent pool may have multiple agents registered with request forwarding enabled. The agent pool is |
| 33 | +then selected by the user in Terraform Cloud as the target for various features |
| 34 | +which require access to private network resources. This creates the mapping from |
| 35 | +Terraform Cloud resources (such as VCS connections) to a pool of agents capable |
| 36 | +of accessing the target API. |
| 37 | + |
| 38 | +## Agent Configuration |
| 39 | + |
| 40 | +To enable request forwarding, start the agent with the `-request-forwarding` |
| 41 | +flag, or set the environment variable `TFC_AGENT_REQUEST_FORWARDING=true`. When |
| 42 | +the agent starts, you will see the following log messages: |
| 43 | + |
| 44 | +``` |
| 45 | +[INFO] core: Request forwarding is enabled |
| 46 | +[INFO] grpc_connector: Connected to broker, awaiting requests |
| 47 | +``` |
| 48 | + |
| 49 | +These log messages indicate that the agent has successfully connected to Terraform Cloud |
| 50 | +and is ready to start forwarding requests. |
| 51 | + |
| 52 | +## Requirements and Limitations |
| 53 | + |
| 54 | +Agent version 1.15.0+ is required to use request forwarding. |
| 55 | + |
| 56 | +We recommend that you allocate at least 250MB of additional system memory specifically |
| 57 | +for request forwarding. This is in addition to the minimum |
| 58 | +[system requirements](/terraform/cloud-docs/agents/requirements). |
| 59 | + |
| 60 | +Forwarded requests are limited to a 10MB response body. This limit comfortably |
| 61 | +supports all Terraform Cloud operations while providing protection against |
| 62 | +unbounded responses. |
| 63 | + |
| 64 | +All forwarded requests are subject to a request timeout. The default timeout is |
| 65 | +60 seconds, but this value is tuned for specific features and use cases and may |
| 66 | +be set slightly higher or lower depending on the type of request being made. |
| 67 | + |
| 68 | +Agents must be able to connect to Terraform Cloud outbound over the internet, as |
| 69 | +well as to private infrastructure targets for request forwarding via HTTP and HTTPS. |
| 70 | + |
| 71 | +## Performance and Scaling |
| 72 | + |
| 73 | +Each agent may handle multiple requests simultaneously. In many cases, a single |
| 74 | +agent may provide sufficient throughput to handle all forwarded requests. It is |
| 75 | +recommended that 2 or more agents with request forwarding enabled are deployed |
| 76 | +for each pool which will leverage request forwarding features. Running multiple |
| 77 | +request forwarding agents provides better fault tolerance and distribution of |
| 78 | +requests. |
| 79 | + |
| 80 | +We recommend that you monitor the memory and CPU utilization on your agents with |
| 81 | +request forwarding enabled to determine if you need to deploy additional agents. Refer to |
| 82 | +[runtime metrics](/terraform/cloud-docs/agents/metrics#runtime-metrics) for more details. |
| 83 | + |
| 84 | +Since an agent may handle more than one forwarded request simultaneously, both horizontal |
| 85 | +(number of agents) and vertical (system resources per agent host) scaling vectors are important. |
| 86 | + |
| 87 | +## Egress Proxy Support |
| 88 | + |
| 89 | +If your agents require an egress proxy to reach Terraform Cloud over the internet, you can set the |
| 90 | +`HTTPS_PROXY` environment variable with your proxy's address when starting the agent. Your |
| 91 | +proxy software must support the [HTTP CONNECT](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/CONNECT) protocol, |
| 92 | +which the agent will use to establish a secure tunnel through the proxy to Terraform Cloud. |
| 93 | + |
| 94 | +## Security considerations |
| 95 | + |
| 96 | +The agent application secures forwarded requests by ensuring that requests may |
| 97 | +only be forwarded through the agent which originate from Terraform Cloud. The agent |
| 98 | +guarantees this by requiring an authenticated session to be established prior to forwarding any requests. |
| 99 | + |
| 100 | +Because forwarded requests and responses may contain sensitive information, |
| 101 | +such as API tokens to 3rd party vendors and PII, we recommend |
| 102 | +that production use cases use dedicated agents to handle request |
| 103 | +forwarding functionality. This ensures that no other processes executing user |
| 104 | +code will be running within the same process space and avoids certain |
| 105 | +attack vectors. |
| 106 | + |
| 107 | +To dedicate an agent to request forwarding only, set the [accepted |
| 108 | +workload types](/terraform/cloud-docs/agents/agents#accept) to `none`. This |
| 109 | +disables all workloads except for request forwarding from being executed. |
0 commit comments