Reverse proxy configuration

A reverse proxy is the piece of infrastructure with the highest ratio of "looks simple" to "has surprising semantics". Two lines of configuration decide whether a path prefix is stripped, whether a WebSocket survives, whether a failed backend is retried, and whether the application ever learns who the client was.

This cluster covers the five reverse proxies most teams actually run, with an emphasis on the behaviour that differs between them rather than a restatement of each manual.

Choosing#

nginx vs HAProxy vs Envoy vs Caddy vs Traefik is the decision page. The short form:

• nginx if you also serve static content and want a configuration language your whole team already reads.
• HAProxy if load balancing correctness, L4 work and runtime control without reloads matter most.
• Envoy if you need dynamic configuration, first class gRPC and deep observability, and can afford the operational surface.
• Caddy if you want automatic HTTPS and the smallest possible operational footprint.
• Traefik if your routing should be derived from container or Kubernetes metadata rather than written by hand.

Per proxy#

nginx as a reverse proxy is the longest of these, because nginx has the most defaults that surprise people and the most configuration that has to be written by hand. The others follow the same shape: HAProxy, Envoy, Caddy and Traefik.

The behaviours that catch everyone#

• Path prefix handling. nginx proxy_pass and the trailing slash is the canonical example, and the proxy_pass simulator will tell you what your own configuration does. Once the prefix is stripped, running an app under a subpath covers how the application gets it back: X-Forwarded-Prefix per framework, or a base path, plus the redirects, cookies and links the proxy still has to fix. When a redirect comes back with :8080 in it, or with http:// behind TLS, why nginx redirects carry the wrong port or scheme separates the redirects nginx builds from the ones the backend sends and shows which of absolute_redirect, port_in_redirect and proxy_redirect fixes each.
• TLS to the backend. When Apache sits behind the proxy, why Apache returns 421 Misdirected Request after 2.4.64 explains the SNI check that started refusing proxies which send no server name, the nginx, HAProxy and Caddy lines that fix it, and the connection reuse that breaks the fix again.
• Protocol upgrades. WebSockets and gRPC both need explicit configuration in some proxies and none at all in others.
• Failure handling. Health checks and upstream failover covers the gap between "the backend is down" and "the proxy noticed". When there is nothing left to fail over to, showing a custom error or maintenance page when the backend is down explains why nginx needs only error_page 502 504 and not proxy_intercept_errors, why HAProxy's dead-server status is 503, and which mechanism catches a backend's own 500 in HAProxy, Caddy and Traefik.
• State. Sticky sessions explains when affinity is a legitimate optimisation and when it is a bug you have decided to keep.
• Migration. ingress-nginx is retired, and what replaces proxy-body-size, proxy-read-timeout and the other proxy annotations maps each one to ingress2gateway's output, Gateway API, Envoy Gateway and Traefik, including the routes that drop from a 60 second timeout to 15.
• Authentication. nginx auth_request vs Traefik ForwardAuth vs Caddy forward_auth explains why the login redirect from Authelia or authentik works in two of them and returns a 500 in nginx.