Envoy Proxy
In plain English
Plain definition
Envoy Proxy is a layer 7 proxy that runs beside each service or at the edge, handling routing, load balancing, TLS and health checks from listeners, filter chains and clusters; its admin interface must stay on localhost, and config changes should pass envoy --mode validate first.
Envoy Proxy is a layer 7 proxy that runs as its own process beside each application, or at the network edge. Applications send traffic to localhost; Envoy does the routing, load balancing, retries, TLS, health checking and statistics for them. Before deploying a changed configuration, run it through envoy --mode validate -c: the command prints OK and exits 0, or prints the errors and exits 1, and it opens no network connections.
Envoy Proxy in plain terms
Envoy is a go-between. Instead of every service carrying its own networking library, each sends its traffic through a local Envoy, which decides where each request goes and records what happened. As a separate process it works the same for any language and upgrades without rebuilding the services.
How it works inside one process
Downstream hosts connect to Envoy; upstream hosts receive connections from it. A listener is a named network location, such as a port, that clients connect to. A cluster is a group of similar upstream hosts, found through service discovery, with a load balancing policy picking one per request.
At its core Envoy is an L3/L4 proxy. Each listener picks a filter chain for a new connection, and its network filters do the work: TCP proxying, TLS client authentication, or HTTP connection management, which adds HTTP filters for routing and rate limiting. A main thread handles configuration updates and the admin interface; worker threads, set with --concurrency, carry the traffic, and each connection stays on one worker for its life.
Where you meet it in operations
Envoy turns up as a service mesh sidecar, as an edge proxy terminating TLS, and in front of gRPC services. Two behaviours catch people out:
- The admin interface can shut the server down and exposes stats, cluster names and certificate details. Bind it to localhost, or a secure network at most, and restrict its paths with
allow_paths. - A fully static configuration reloads only through hot restart. The new process takes over the listen sockets; the old one drains for
--drain-time-s(default 600 seconds) and is shut down after--parent-shutdown-time-s(default 900). Connections are not handed over: they finish or are closed.
Where it fits beside a control plane
Envoy is the data plane. A control plane feeds it configuration through the discovery APIs (listeners through LDS, routes through RDS, clusters through CDS, endpoints through EDS), so changes arrive without a restart. Because Envoy can balance individual gRPC requests, not only TCP connections, it is a common answer when long-lived gRPC connections stick to one backend (see fixing gRPC load balancing behind L4 proxies). Some meshes move layer 7 handling out of per-pod sidecars, as ambient mesh L7 policy without sidecars explains.
Example of a first look at a running Envoy
With the admin listener on 127.0.0.1:9901, three read-only requests answer the first questions:
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9901/ready
curl -s http://127.0.0.1:9901/listeners
curl -s http://127.0.0.1:9901/clusters
/ready returns 200 when the server is LIVE and 503 otherwise. /listeners shows each listener and the address it is bound to. /clusters lists every cluster with its discovered hosts and per-host counters such as cx_connect_fail and rq_timeout; a cluster with no hosts points at service discovery.
What Envoy is often confused with
Envoy is a proxy, not a whole service mesh. Without a control plane it works from static files, can discover hosts only through DNS and reloads only by hot restart, which still closes any long-lived connection left on the old process.
Related terms
- xDS: the family of discovery APIs a control plane uses to configure Envoy.
- Outlier detection: passive health checking that removes hosts behaving unlike the rest of a cluster from load balancing.
- Service mesh: a fleet of proxies such as Envoy plus the control plane that configures them.
Sources and further reading
Start with the Envoy documentation’s “What is Envoy”, “Terminology” and “Administration interface” pages, then the rest of our Envoy Proxy coverage.
Checking an Envoy configuration change
- Run
envoy --mode validate -c new-config.yamlwith the same Envoy version as production, and stop if it does not print OK. - Save the current file, or the output of
/config_dump, as your rollback copy. Envoy tries to redact private keys and passwords from the dump, but store it as a secret. - After the change, confirm
/readyreturns 200 and/clusterslists the expected hosts. If not, restore the saved configuration by the same route you deployed it: a hot restart with the old file, or the previous version from the control plane.
Authoritative Sources
Technology documentation
What is Envoy
Terminology
Threading model
Listeners
Cluster manager
xDS configuration API overview
Hot restart
Command line options
Run Envoy
Administration interface
Outlier detection
About this page
Credited to
Dates
Published
Corrections
No corrections are listed for this page. Some review sweeps corrected pages without naming each one; those are in the corrections log.
Was this useful?
Reports go to the site owner and are used to correct pages. Corrections are listed at /corrections.