Configure forward proxying for API proxies

Forward proxies provide a single point through which multiple machines send requests to an external server. They can enforce security policies, log and analyze requests, and perform other actions so that requests adhere to your business rules.

Using a forward proxy in Apigee hybrid, you can intercept and manage all egress traffic from your Kubernetes cluster. This includes API proxy requests to Target Endpoints and communication with *.googleapis.com that the hybrid runtime makes for its debug and analytics pipeline and for policies like MessageLogging and the AI policies (such as SanitizeUserPrompt and SemanticCacheLookup).

To use an HTTP forward proxy between hybrid and the TargetEndpoint, you must configure the outbound proxy settings in your overrides file. These environment-scoped properties route target requests from hybrid to the HTTP forward proxy. You also need to ensure use.proxy is set to "true" for any TargetEndpoint that you want to go through an HTTP forward proxy. See the bottom of the page for instructions.

To configure a hybrid environment for forwarding proxying, add the envs.httpProxy property to your overrides file and apply it to the cluster. For example:

envs:
  - name: test
    httpProxy:
      scheme: HTTP
      host: 10.12.0.47
      port: 3128
      ...

For details on each of the envs.httpProxy configuration properties refer to the Configuration property reference.

Forward proxying is configured for an environment; all traffic going from API proxies in that environment to backend targets goes through the specified HTTP forward proxy. If the traffic for a specific target of an API proxy should go directly to the backend target, bypassing the forward proxy, then set the following property in the TargetEndpoint to override the HTTP forward proxy:

<Property name="use.proxy">false</Property>

For more information on setting the TargetEndpoint properties, including how to configure the connection to the target endpoint, see Endpoint properties reference.

Set use.proxy to "true" for any TargetEndpoint that you want to go through an HTTP forward proxy:

<Property name="use.proxy">true</Property>

If you have a firewall on the backend which is configured to expect Host Header always to include the backend server host name, while the Message Processor is sending the proxy server hostname, perform the following to configure this option:

Set the property use.proxy.host.header.with.target.uri to true in the TargetEndpoint as shown in the following example:

Sample TargetEndpoint configuration:

  <TargetEndpoint name="default">
    <HTTPTargetConnection>
      <URL>https://mocktarget.apigee.net/json</URL>
      <Properties>
        <Property name="use.proxy.host.header.with.target.uri">true</Property>
      </Properties>
    </HTTPTargetConnection>
  </TargetEndpoint>

For details on the use.proxy.host.header.with.target.uri property, see Endpoint properties reference.

AI policies and the forward proxy

The Model Armor policies (SanitizeUserPrompt and SanitizeModelResponse) and the semantic cache policies (SemanticCacheLookup and SemanticCachePopulate) make outbound calls while processing requests and responses. These include the Model Armor sanitization calls, and the Vertex AI text embeddings, Vector Search findNeighbors, and upsertDatapoints calls.

When a forward proxy is configured for the environment with envs.httpProxy, all of these calls are routed through the forward proxy by default, with no policy-level configuration required. This is true even for endpoints that are not under *.googleapis.com, such as the public Vector Search endpoint that SemanticCacheLookup calls.

These policy calls are treated the same as the runtime's trace and analytics traffic: setting envs[].managementCallsSkipProxy to true makes them skip the forward proxy and egress directly instead. This applies to all of the calls listed above. This is separate from a TargetEndpoint, whose forward-proxy behavior is controlled by its own use.proxy property.