How do Nginx and Envoy model reverse proxy configuration?

Nginx config is a file that you edit and reload. Envoy config is typed state, defined as protobuf messages, that a control plane can push over an API. Many later trade-offs come from this difference.

Nginx uses nested contexts. An http block contains server blocks that match on port and hostname. Each server holds location blocks that match request paths. A proxy_pass directive points traffic at an upstream block, which lists the backend servers. Directives inherit downward, and some modules run logic inside location blocks. As a result, the file reads like a script that is evaluated per request.

Envoy breaks the same concepts into separate, referenceable resources:

Concern Nginx Envoy
Bind address/port listen in server Listener
Protocol handling Implicit in http context Filter chain with HTTP connection manager
Host and path matching server_name, location Route configuration: virtual hosts and routes
Backend group upstream Cluster
Backend addresses server lines in upstream Endpoints (load assignment)

Take a simple reverse proxy that sends /api on port 80 to two backends:

  • Nginx: one server, one location, and one upstream with two server lines.
  • Envoy: a listener, an HTTP connection manager filter that refers to a route configuration by name, a route that names a cluster, and a cluster that holds two endpoints.

Each Envoy piece has a schema and can be replaced on its own, so the config reads like a data structure rather than a program. That separation is what makes per-resource API updates possible.

The cost is verbosity. Envoy needs explicit fields that Nginx leaves as defaults, and resources are linked by name. A static Envoy config for the example above is several times longer than the Nginx version. For this reason, most teams generate Envoy config from templates or a control plane instead of writing it by hand.

# Nginx equivalent, for comparison:
#   upstream api_backend { server 10.0.0.11:8080; server 10.0.0.12:8080; }
#   server { listen 80; location /api { proxy_pass  } }
static_resources:
  listeners:
  - name: listener_http                      # nginx: listen 80
    address:
      socket_address: { address: 0.0.0.0, port_value: 80 }
    filter_chains:                           # protocol handling is explicit
    - filters:
      - name: envoy.filters.network.http_connection_manager
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
          stat_prefix: ingress_http
          route_config:                      # inline here; with RDS it is fetched by this name
            name: local_route
            virtual_hosts:
            - name: api
              domains: ["*"]                 # nginx: server_name
              routes:
              - match: { prefix: "/api" }    # nginx: location /api
                route: { cluster: api_backend }   # linked to the cluster by name
          http_filters:
          - name: envoy.filters.http.router  # forwards the request to the chosen cluster
            typed_config:
              "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
  clusters:
  - name: api_backend                        # nginx: upstream api_backend
    type: STATIC
    lb_policy: ROUND_ROBIN                   # default, stated explicitly
    load_assignment:                         # endpoints: nginx's server lines
      cluster_name: api_backend
      endpoints:
      - lb_endpoints:
        - endpoint: { address: { socket_address: { address: 10.0.0.11, port_value: 8080 } } }
        - endpoint: { address: { socket_address: { address: 10.0.0.12, port_value: 8080 } } }

A static Envoy v3 config for the /api reverse proxy, with comments mapping each listener, filter chain, route and cluster to the three-line Nginx version shown at the top.

How does an Nginx reload work, and what happens to long-lived connections?

When the master process receives a reload signal (nginx -s reload sends SIGHUP), it re-reads and parses the entire configuration. If parsing succeeds, it opens any new listening sockets, forks a fresh set of workers with the new config, and tells the old workers to shut down gracefully. Old workers stop accepting new connections, close idle keepalive connections, and finish requests already in flight. If parsing fails, the master logs the error and keeps the old workers running.

That fallback is why you run nginx -t before every reload. The reload command only sends a signal, so it can report success while the error appears only in the error log. Your deployment then thinks the change is live when it is not. A broken config left on disk also fails the next full restart, when there are no old workers to fall back on. Gate the reload on a successful nginx -t so a failed change stops the deploy where you can see it.

Graceful shutdown waits for connections to close, and WebSockets, gRPC streams, and long polls may stay open for hours. Each reload can leave a generation of old workers holding these connections. They use memory and keep routing to the old upstreams. With frequent reloads, these generations pile up. worker_shutdown_timeout caps how long an old worker can drain. After the timeout, Nginx closes the remaining connections, and clients must reconnect.

Reloads are cheap but not free. Every reload re-parses the config, re-resolves upstream hostnames, and throws away per-worker state such as upstream keepalive pools.

#!/usr/bin/env bash
# Safe reload: validate first, signal only if the config parses.
# Assumes a standard install with nginx on PATH and the default config path.
set -euo pipefail

# 1. Validate the full config tree (includes, certs, upstream syntax).
#    'nginx -s reload' only sends SIGHUP to the master and can return 0
#    even when the master later rejects the config, so check it here.
if ! nginx -t; then
  echo "nginx -t failed; not reloading. Old workers keep serving." >&2
  exit 1
fi

# 2. Signal the master: re-read config, fork new workers,
#    and tell old workers to drain gracefully.
nginx -s reload

# 3. Count old workers still draining long-lived connections
#    (WebSockets, gRPC streams, long polls). Each reload can leave
#    another generation of them behind, holding memory and old config.
sleep 5
draining=$(ps -eo args | grep -c '[n]ginx: worker process is shutting down' || true)
echo "old workers still draining: ${draining}"

# To bound how long old workers can drain, set this in the main context
# of nginx.conf. After the timeout, Nginx closes remaining connections
# and clients must reconnect:
#
#   worker_shutdown_timeout 30s;

A deploy step that blocks the reload on a successful nginx -t, sends the reload signal, and then counts old worker processes that are still draining long-lived connections, with worker_shutdown_timeout shown as the setting that caps how long they can stay.

How does Envoy's dynamic configuration work with xDS?

Envoy avoids that whole-config rebuild by splitting configuration into two layers. The bootstrap is a static file read once at startup. It defines the node identity, the admin interface, and how to reach the management server. Everything else can arrive as dynamic resources over xDS, the family of gRPC or REST discovery APIs.

API Delivers Referenced by
LDS Listeners (ports, filter chains) Bootstrap
RDS Route tables (hosts, paths, retries) HTTP connection manager in a listener
CDS Upstream clusters (LB policy, timeouts) Bootstrap
EDS Endpoint IPs and health for a cluster Cluster
SDS TLS certificates and keys Listener or cluster TLS context

Updates flow one way: control plane → LDS/CDS → RDS/EDS → SDS. Each resource type updates on its own. Rotating a certificate through SDS or adding endpoints through EDS changes nothing else, so existing connections and pools stay intact. The minimal bootstrap shown separately declares one static cluster for the xDS server and points lds_config and cds_config at it, usually through ADS.

Changing or removing a listener is more disruptive. Envoy builds the new listener, sends new connections to it, and puts the old one into draining. Existing connections there get the drain period to finish before Envoy closes them.

Hot restart is a separate mechanism, used for binary or bootstrap changes. A new process takes over the listening sockets from the old one, the old process drains, and then it exits once the parent shutdown time expires. If that window is shorter than your longest streams, those connections are cut off as abruptly as they would be by a hard Nginx stop.

# envoy.yaml: static bootstrap, read once at startup.
# Changing this file requires a hot restart; LDS/CDS resources do not.
# Drain timing is set on the command line, e.g.:
#   envoy -c envoy.yaml --drain-time-s 60 --parent-shutdown-time-s 90
node:
  id: edge-proxy-01          # identity the control plane uses to pick config
  cluster: edge-proxies
admin:
  address:
    socket_address: { address: 127.0.0.1, port_value: 9901 }
dynamic_resources:
  ads_config:                # one gRPC stream carries all xDS types, in order
    api_type: GRPC
    transport_api_version: V3
    grpc_services:
      - envoy_grpc: { cluster_name: xds_cluster }
  lds_config:                # listeners arrive over ADS
    resource_api_version: V3
    ads: {}
  cds_config:                # clusters arrive over ADS; RDS/EDS/SDS are referenced from them
    resource_api_version: V3
    ads: {}
static_resources:
  clusters:
    - name: xds_cluster      # the only static cluster: how to reach the control plane
      type: STRICT_DNS
      connect_timeout: 1s
      typed_extension_protocol_options:
        envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
          "@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions
          explicit_http_config:
            http2_protocol_options: {}   # gRPC requires HTTP/2
      load_assignment:
        cluster_name: xds_cluster
        endpoints:
          - lb_endpoints:
              - endpoint:
                  address:
                    socket_address: { address: xds.internal.example, port_value: 18000 }

A minimal Envoy v3 bootstrap that defines a node identity, a local admin interface and one static xDS cluster, and pulls all listeners and clusters from the management server over ADS, with hot-restart drain flags noted in the comments.

What does running a control plane cost in practice?

Envoy avoids that drain-and-exit cycle for routine changes, but only because something else now owns configuration: an xDS server. You either adopt an existing control plane or build one, typically on a library that implements the xDS protocol. Either way, your team now runs a stateful service that every proxy depends on.

The protocol has real semantics. Each xDS response carries a version_info and a nonce. Envoy ACKs a response by echoing that version and nonce back. It NACKs a response by returning the previously accepted version along with an error detail. Your server must track what each proxy has actually accepted, not just what it sent. Otherwise you cannot tell a fleet that is converged from one that is quietly running stale config.

Outages degrade gracefully, but bad pushes do not. If the control plane is unreachable, Envoy keeps serving with its last accepted configuration. It cannot learn about new endpoints or routes until the connection returns, but it does not fall over. A logic bug in the control plane is a different matter. A reload pipeline usually touches hosts in batches, so a bad change stops after the first batch fails. A control plane can push the same wrong route table to every proxy within seconds. That risk needs three defenses:

  • Validate generated resources before they are served.
  • Stage rollouts by proxy group so a bad change reaches a subset first.
  • Alert on the update_rejected counters Envoy exposes for each subscription.

Weigh it honestly. A control plane is ongoing engineering work. It pays off when endpoint churn and config change rates are high enough that templating, validating, and reloading Nginx across a fleet already consumes comparable effort. At low change rates, the reload pipeline is usually the cheaper system to own.

How do Nginx and Envoy handle service discovery and endpoint churn?

the cheaper option. Endpoint churn is where the two designs diverge most.

This comparison assumes open source Nginx without commercial editions or third-party modules. In that baseline, Nginx cannot change upstream membership through an API. Commercial editions and some third-party modules add that capability, but they change the operational model and are out of scope here.

That leaves two options. The first is DNS re-resolution. You configure a resolver and put the hostname in a variable used by proxy_pass, which makes Nginx resolve the name at request time and honor the TTL or a valid= override. This works, but it bypasses the named upstream block, so you lose that block's balancing settings and keepalive pool. Freshness also depends on DNS TTLs and on whether your DNS reflects readiness. The second option is a template-and-reload loop: a watcher renders new upstream lists and triggers a reload.

Illustrative estimate with assumed inputs. Suppose there are 60 services, each deployed 4 times a day, with one debounced reload per deploy. That is 240 reloads a day, about 10 an hour. If WebSocket connections last 60 minutes and worker_shutdown_timeout is generous, roughly 10 generations of draining workers coexist at any time, each holding memory and its own connections. Autoscaling events add more reloads on top of this.

Envoy's EDS avoids this cost. The control plane pushes a new endpoint set, and the cluster's load balancer updates in place. Listeners stay in place and connections are not drained.

Both proxies can make a failing backend worse. A proxy_next_upstream setting or an Envoy retry policy, which is often added by a mesh control plane, multiplies attempts against already-degraded hosts. To prevent that, cap retries with proxy_next_upstream_tries in Nginx or with retry budgets in Envoy.

# Open source Nginx: DNS re-resolution instead of reloads, with bounded retries.
# Main context: cap how long draining workers from older reloads stay alive.
worker_shutdown_timeout 10m;

events {}

http {
    server {
        listen 80;

        # Re-resolve names at request time; override long DNS TTLs to 10s.
        resolver 10.0.0.2 valid=10s;
        resolver_timeout 2s;

        location /api/ {
            # A variable in proxy_pass forces runtime resolution through the
            # resolver. Trade-off: this bypasses any named upstream block, so
            # its balancing settings and keepalive pool do not apply.
            set $orders_backend orders.internal.example;
            proxy_pass

            # Retry only on connection errors and timeouts, not on HTTP 5xx,
            # so a degraded backend is not hit again for every failing request.
            proxy_next_upstream error timeout;

            # At most 2 attempts in total (original plus one retry), within 5s.
            proxy_next_upstream_tries 2;
            proxy_next_upstream_timeout 5s;

            proxy_connect_timeout 1s;
            proxy_read_timeout 30s;
        }
    }
}

An open source Nginx config that picks up endpoint changes through runtime DNS re-resolution instead of reloads, caps retries with proxy_next_upstream_tries and proxy_next_upstream_timeout, and limits worker draining time with worker_shutdown_timeout.

Which proxy gives better metrics, logging and debugging?

Nginx open source exposes very few metrics on its own. The stub_status module reports active connections, accepted and handled connections, total requests, and reading/writing/waiting counts. Those numbers show load, but they do not show which upstream is failing. For per-upstream latency or error rates you have to derive metrics from access logs. Your log_format must include $status, $request_time, $upstream_addr and $upstream_response_time, and a log shipper or exporter then turns those lines into metrics. $upstream_response_time can contain several comma-separated values when Nginx retried. Your parser has to handle that, or retried requests will skew the numbers.

Envoy emits stats per listener, per cluster and per route without extra tooling. These include response code classes (upstream_rq_5xx), upstream request time histograms, retry counters, and circuit breaker open gauges, and /stats/prometheus serves them in Prometheus format. The detail has a cost. Each new cluster or route adds many series, so endpoint churn and generated routes can overload Prometheus. Use stats matchers to drop the series you don't need, and use tag extraction to turn names into labels.

Envoy access logs use format strings such as %RESPONSE_FLAGS%. That field explains why Envoy itself failed a request, for example no healthy upstream or an upstream timeout. When tracing is configured, Envoy also generates and propagates request IDs and trace headers. Your services still have to forward those headers for traces to connect across hops.

Need Nginx Envoy
Built-in metrics stub_status counters Per-listener, per-cluster and per-route stats
Upstream latency Parsed from $upstream_response_time in logs Histograms
Failure reason Inferred from status codes and logs %RESPONSE_FLAGS%
Config inspection nginx -T /config_dump, /clusters, /stats

nginx -T prints the configuration as written on disk. Envoy's /config_dump shows what the proxy actually received over xDS, which makes it the place to start when debugging a control plane. Bind the Envoy admin port to localhost or a protected interface and never expose it publicly. Its endpoints reveal internal topology, and some of them can change the proxy's state or shut it down.

When should you choose Nginx, Envoy, or an alternative?

The choice comes down to how often your topology changes and who will be on call for the proxy.

Factor Nginx fits better Envoy fits better
Topology change rate Upstreams change weekly or less Endpoints change many times per hour
Team size One small team owns the proxy Platform team can own a control plane
Traffic mix Static files, caching, HTTP/1.1 APIs gRPC, HTTP/2 end to end, service mesh
Metrics need Edge-level request and error rates Uniform per-service, per-route stats
Failure surface Config files plus a reload Control plane availability and correctness

Nginx saves engineering time when the config fits in a reviewed file and reloads are rare. Most engineers already know how it behaves, and its caching and static file serving need no extra components. Avoid it when you are scripting frequent reloads to track endpoints. Reload-driven churn multiplies worker generations and makes connection draining hard to reason about.

Envoy pays off when hundreds of services need identical retry, timeout and telemetry behaviour, and when endpoints come and go faster than a file-based workflow can track. Avoid it if nobody can own the control plane. A hand-written static Envoy config gives you the complexity without the dynamic benefits.

There are middle paths. Nginx with add-on modules or commercial features can add API-driven upstream updates and richer metrics without moving to a new proxy. If your platform already runs a control plane, for example one bundled with your orchestrator or mesh, using Envoy under it removes most of the operating cost of running one yourself.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to nginx vs envoy reverse proxy, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Changing a shared variable is one edit and one review instead of editing every service's .env by hand.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.