Skip to main content

Real Client IP

If your application logs the same internal IP for different callers, it may be recording the gateway's address. The original client IP can still be present in the HTTP request headers.

How the address reaches your application​

Traffic passes through a load balancer and an Envoy gateway before reaching your container:

Client → Load balancer → Envoy gateway → Application

Each connection has its own peer address. Preserving the client IP at the gateway and reading it in your application are separate settings:

ConnectionHow the client IP is carriedRequired configuration
Load balancer → gatewayPROXY protocolGateway client IP preservation
Gateway → HTTP applicationX-Forwarded-For headerTrusted proxies in the application
Gateway → TCP application, such as MQTTPROXY protocol, when configuredGateway forwarding and a compatible application listener

The gateway's client IP setting lets it identify callers for access rules and logs. Your container's socket still sees Envoy as its peer. For HTTP, configure your framework to resolve the client address from trusted forwarding headers. Envoy documents this forwarding behavior in its PROXY protocol settings.

HTTP applications: Express and NestJS​

Express defaults to trust proxy: false: req.ip then reports the socket peer. Configure trusted proxies before registering request logging and rate-limit middleware. The resolved address is available through req.ip; req.socket.remoteAddress continues to identify the immediate peer. See Express behind proxies.

For an application that reads HTTP_TRUSTED_PROXIES, set a comma-separated list of trusted proxy IPs or CIDRs in its environment variables. The following addresses are documentation examples; replace them with the proxies authorized for your gateway:

HTTP_TRUSTED_PROXIES=192.0.2.10/32,192.0.2.11/32

HTTP_TRUSTED_PROXIES is an application convention, not a built-in SailOps or Express setting. Adding the variable only works if your code reads it. For Express, one implementation is:

const trustedProxies = (process.env.HTTP_TRUSTED_PROXIES ?? '')
.split(',')
.map(value => value.trim())
.filter(Boolean);

app.set('trust proxy', trustedProxies.length > 0 ? trustedProxies : false);

For NestJS using the Express adapter, use the same list and replace the last line with:

app.getHttpAdapter().getInstance().set(
'trust proxy',
trustedProxies.length > 0 ? trustedProxies : false,
);

Redeploy the application after changing its environment. Use req.ip for client-address logging and per-client limits.

Choosing trusted proxies​

Use the gateway proxies' backend-facing addresses, not the public load balancer address. Include every replica. Individual pod IPs can change after rescheduling, so a list copied from current pods needs maintenance. Contact support to confirm suitable proxy addresses or dedicated ranges for your environment.

Do not trust the whole cluster network or set trust proxy to true just to make the logs change. Restrict trust to the proxies that actually forward requests. If a CDN or another proxy is present, validate the full forwarding chain before extending that trust.

Express's uniquelocal preset does not include 100.64.0.0/10, which may contain gateway pod addresses. Confirm the actual source addresses instead of assuming a private-address preset covers them.

Verify the result​

  1. Send requests from two networks with different public egress IPs.
  2. Compare req.ip, req.socket.remoteAddress, and X-Forwarded-For in application logs for those requests.
  3. Confirm that req.ip identifies the callers, while the socket peer remains a gateway address. Different callers behind the same NAT can legitimately share an IP.
ObservationWhat to check
X-Forwarded-For differs, but req.ip stays equal to the gateway IPTrusted-proxy configuration, environment loaded by the running application, and whether every gateway replica is included
req.ip is correct, but the logged client address is wrongWhether the logger reads the socket address instead of the framework's resolved address
The header is missing or contains only an intermediary addressGateway client IP preservation and any CDN or additional proxy on the request path

For gateway-side diagnosis, provide support with the project, gateway, request timestamp and request ID when available. Correlating the same request across gateway and application logs shows where the address changes.

MQTT and other TCP protocols​

Raw MQTT over TCP has no X-Forwarded-For header. An HTTP trusted-proxy setting has no effect on it.

Preserving the address at the gateway only covers the load-balancer-to-gateway connection. To pass it on to a TCP application, Envoy must also send PROXY protocol to the backend, and the receiving listener must support and trust that protocol. Envoy controls this separately through backend PROXY protocol settings.

Coordinate this configuration with support and check your broker's compatibility first. Sending a PROXY header to a listener that expects MQTT bytes immediately can break connections.