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:
| Connection | How the client IP is carried | Required configuration |
|---|---|---|
| Load balancer → gateway | PROXY protocol | Gateway client IP preservation |
| Gateway → HTTP application | X-Forwarded-For header | Trusted proxies in the application |
| Gateway → TCP application, such as MQTT | PROXY protocol, when configured | Gateway 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
- Send requests from two networks with different public egress IPs.
- Compare
req.ip,req.socket.remoteAddress, andX-Forwarded-Forin application logs for those requests. - Confirm that
req.ipidentifies the callers, while the socket peer remains a gateway address. Different callers behind the same NAT can legitimately share an IP.
| Observation | What to check |
|---|---|
X-Forwarded-For differs, but req.ip stays equal to the gateway IP | Trusted-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 wrong | Whether the logger reads the socket address instead of the framework's resolved address |
| The header is missing or contains only an intermediary address | Gateway 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.