Enabling Proxy Protocol for Embedded Container Service installation

Use Proxy Protocol to resolve client IP address masking in Private Cloud (PVC) deployments on Cloudera Embedded Container Service.

In a default CDP-PVC setup on Cloudera Embedded Container Service, backend data services register internal IP addresses, such as the IP of the local load balancer or NGINX ingress, in the internal Cloudera AI database instead of the actual client IP.

When a request passes through a Cloudera Data Services on premises load balancer or Ingress Gateway, the proxy terminates the original TCP connection and initiates a new one. This process rewrites the network packet source header to the internal IP of the proxy, removing the true identity of the caller.

About Proxy Protocol

Proxy Protocol operates at the Transport Layer (TCP) and preserves client connection information without requiring TLS termination.

Proxy Protocol functions by prepending a single line of text containing metadata (source IP, destination IP, and ports) to the beginning of the TCP stream before any application data such as HTTP requests is transmitted.

The following charts describe request flows with and without Proxy Protocol:

Default request flow without Proxy Protocol

[ User ]
  └─ Client IP: 203.0.113.10 (Packet Source: 203.0.113.10)
        │
        ▼
[ On-premise LB ] (User Controlled)
  └─ Internal IP: 10.0.0.50  (Rewrites Packet Source to: 10.0.0.50)
        │
        ▼
[ cloudera-gateway ] (istio-gateway)
  └─ Internal IP: 10.65.213.250 (Receives TCP from LB; original IP is lost)
        │
        ▼
[ nginx ]
  └─ Internal IP: 192.168.1.10
        │
        ▼
[ data service ]
  └─ Registers Source as: 192.168.1.10 (NGINX Ingress IP)

Updated request flow with Proxy Protocol enabled

[ User ]
  └─ Client IP: 203.0.113.10 (Initiates HTTPS connection)
        │
        ▼
[ On-premise LB ]
  └─ Prepends Proxy Header to TCP stream: 
     [PROXY TCP4 203.0.113.10 10.0.0.50 443 8443 \r\n][Encrypted HTTPS Blob]
        │
        ▼
[ cloudera-gateway ] (Runs in TLS Passthrough Mode)
  └─ Reads the PROXY line to identify the user, then forwards the stream intact:
     [PROXY TCP4 203.0.113.10 10.0.0.50 443 8443 \r\n][Encrypted HTTPS Blob]
        │
        ▼
[ nginx ] (Holds TLS Keys)
  └─ Reads "PROXY" header (extracts 203.0.113.10), decrypts the TLS blob, and processes HTTP.
        │
        ▼
[ data service ]
  └─ Successfully reads and logs actual Client IP: 203.0.113.10

Component Requirements and Configuration

For Proxy Protocol to function as expected, every single proxy component in the request path must support and have it enabled.

Table 2. Component Reference information
Component	Responsible entity	Description
On-premise Load Balancer	User	Must be explicitly enabled by the end-user platform team.
`cloudera-gateway`	Managed (Helm)	Supports Dual Mode (can accept both Proxy Protocol traffic and standard traffic simultaneously).
`nginx`	Managed (Helm)	Strict Mode only. Does not support dual mode; must strictly receive Proxy Protocol traffic once turned on.

Because cloudera-gateway features a dual mode, it could technically be enabled by default without breaking any process. However, because NGINX prioritizes speed, security, and predictable behavior, it expects precise configuration syntax and exact adherence to HTTP standards. This is a highly sensitive infrastructure change, the entire feature is disabled by default and must be turned on explicitly.

Script location

An automated script is provided within the Cloudera Embedded Container Service parcel to safely toggle this configuration across the cluster components.

/opt/cloudera/parcels/ECS/istio/cloudera-gateway/proxy-protocol/proxy-protocol.sh

Enable Command

To activate Proxy Protocol across cloudera-gateway and nginx, execute:

/opt/cloudera/parcels/ECS/istio/cloudera-gateway/proxy-protocol/proxy-protocol.sh --enable

Disable Command

To roll back and return to standard TCP routing, execute:

/opt/cloudera/parcels/ECS/istio/cloudera-gateway/proxy-protocol/proxy-protocol.sh --disable

As an end-user, perform the following:

Enable Proxy Protocol by using the script.
Enable Proxy Protocol for the user enabled proxy instances.