Envoy: Cloud-Native Edge and Service Proxy

What Envoy is

Envoy is an open-source L7 proxy and communication bus written in C++ and designed, in the words of its documentation, for large modern service oriented architectures. The repository README sums it up as a cloud-native high-performance edge, middle and service proxy. The project was built around one stated belief: the network should be transparent to applications, and when network or application problems do occur it should be easy to determine where they came from. Envoy hosts its code at github.com/envoyproxy/envoy under the Apache-2.0 licence, and the README notes that the project is hosted by the Cloud Native Computing Foundation (CNCF).

The core idea is an out of process architecture. Instead of linking a networking library into every service, you run Envoy as a self-contained process alongside each application server. Applications talk to localhost, and the collection of Envoys forms a transparent communication mesh that handles service discovery, load balancing, retries, TLS, observability and the rest. The docs give two reasons this beats the library approach: it works with any application language, so one deployment can bridge Java, C++, Go, PHP and Python services, and it can be deployed and upgraded across an entire infrastructure without the pain of rolling a library upgrade through every codebase.

The same binary works as a sidecar, a middle proxy, or a front/edge proxy. The audience is platform and infrastructure teams building service meshes, API gateways and ingress layers, and developers who build control planes or products on top of Envoy's data plane.

How Envoy works

Listeners, filter chains and the HTTP connection manager

At its core Envoy is an L3/L4 network proxy. Configuration defines any number of listeners in a single process; the docs generally recommend one Envoy per machine. Envoy supports both TCP and UDP listeners. Each TCP listener has a set of filter chains, and one chain is selected per connection based on its filter_chain_match criteria. A chain is made of network-level (L3/L4) filters, and optional listener filters run before them to inspect or adjust connection metadata.

HTTP gets its own layer. The built-in HTTP connection manager is a network filter that turns raw bytes into HTTP messages and events (headers, body data, trailers) and handles access logging, tracing, header manipulation, routing and statistics. It natively supports HTTP/1.1, HTTP/2 and HTTP/3, including WebSockets. The docs say Envoy's HTTP support was designed first and foremost as an HTTP/2 multiplexing proxy: a codec API translates every wire protocol into a protocol-agnostic stream model, so most of the code does not care whether a stream arrived on HTTP/1.1, HTTP/2 or HTTP/3. Inside the connection manager sits an HTTP filter stack with decoder, encoder and decoder/encoder filters. Filters can stop and resume iteration, and their order in the http_filters list matters.

Cluster manager, service discovery and health checking

On the upstream side, the cluster manager owns every configured upstream cluster. Filters ask it for either an L3/L4 connection or a handle to an HTTP connection pool, and the cluster manager hides which hosts are healthy, how load is balanced, and whether the upstream speaks HTTP/1.1, HTTP/2 or HTTP/3. New or updated clusters are "warmed" (initial discovery plus an optional first health check pass) before they serve traffic, and updated clusters are swapped in atomically.

Service discovery types include static hosts, strict DNS (every returned IP is a host, resolved continuously and asynchronously), logical DNS (only the first IP is used when a new connection is needed, which the docs call optimal for large web services behind round-robin DNS), original destination, and the Endpoint Discovery Service (EDS). Envoy never resolves DNS synchronously in the forwarding path, and it treats discovery as eventually consistent, combining discovery data with active health checking rather than relying on fully consistent stores such as ZooKeeper, etcd or Consul. Health checks can be HTTP, gRPC, L3/L4, Redis or Thrift Passive health checking is available through outlier detection.

Threading model

Envoy uses a "single process, multiple threads" architecture. A main thread handles coordination work such as xDS configuration updates, stats flushing and the admin interface; a configurable number of worker threads (set with --concurrency) do the listening, filtering and forwarding; and a file flusher thread writes access logs so disk I/O does not block request processing. Once a listener accepts a connection, it stays bound to one worker for its lifetime, which keeps the hot path parallel and largely lock-free. The docs recommend matching worker threads to hardware threads for most workloads.

Configuration: static files or xDS

Envoy can run from a fully static configuration, where you list listeners, filter chains and clusters in a file and rely on DNS for dynamic hosts and hot restart for reloads. For more dynamic setups, Envoy consumes a layered family of gRPC/REST discovery APIs collectively called xDS: EDS for endpoints, CDS for clusters, RDS for HTTP routes, LDS for whole listeners, SDS for certificates and keys, RTDS for runtime layers and ECDS for extension configuration. Aggregated xDS (ADS) carries every resource type over a single gRPC stream when update ordering matters. With LDS in the mix, the docs say almost every aspect of Envoy can be configured dynamically, and hot restart is only needed for rare changes such as admin or tracing settings, certificate rotation or binary updates.

Key features

• Pluggable L3/L4 filter chains. Network filters cover TCP and UDP proxying, HTTP, TLS client certificate authentication and protocol-aware filters for Redis, MongoDB and Postgres.
• HTTP L7 filter layer. HTTP filters handle tasks such as buffering, rate limiting, routing and sniffing Amazon DynamoDB traffic, without needing to know the underlying protocol version.
• HTTP/1.1, HTTP/2 and HTTP/3. Envoy bridges any combination of client and server protocols in either direction; the overview page describes HTTP/3 support, added in 1.19.0, as alpha.
• Load balancing and resilience. Automatic retries, circuit breaking, global rate limiting via an external rate limiting service, request shadowing, outlier detection and zone-aware routing are built in.
• xDS dynamic configuration. Listeners, routes, clusters, endpoints, secrets, runtime and extension configs can all be served by a control plane, including over a single ADS stream or the delta protocol.
• Observability. Envoy emits downstream, upstream and server statistics as counters, gauges and histograms, supports pluggable stats sinks with tags, exposes stats on the admin port, and supports distributed tracing through third-party providers.
• Extensibility. Beyond C++ extensions, Envoy has two dynamic filter extensions that load code at runtime: Lua and WASM.

Getting started

The install docs say the project publishes pre-built Docker images for amd64 and arm64, and that on macOS you can install natively with Homebrew:

$ brew update
$ brew install envoy

The docs call the distroless image variant the most efficient and secure way to run Envoy in a container. The install page also notes that the old apt repository at apt.envoyproxy.io is not currently maintained, and points Linux users to the Docker images or the static binaries on the GitHub releases page instead.

Once installed, check the version and start Envoy with the demo configuration from the quick start guide. The -c (or --config-path) flag points at the initial config file:

$ envoy --version
$ envoy -c envoy-demo.yaml

The Docker variant of the quick start publishes ports 9901 and 10000. Confirm that Envoy is proxying on port 10000 with:

$ curl -v localhost:10000

The quick start also shows how to layer an override on top of the main configuration with --config-yaml. Save this snippet as envoy-override.yaml to move the admin interface to port 9902:

admin:
  address:
    socket_address:
      address: 127.0.0.1
      port_value: 9902

Then start the server with both files:

$ envoy -c envoy-demo.yaml --config-yaml "$(cat envoy-override.yaml)"

Overrides append to YAML lists, so they cannot change existing listeners or clusters. Validate mode checks a config without opening network connections:

$ envoy --mode validate -c my-envoy-config.yaml

On Kubernetes, the install docs point to Envoy Gateway, which runs Envoy as an ingress gateway using the Gateway API and is installed with Helm. The Helm example in the docs references a v0.0.0-latest development chart, so pin a released Envoy Gateway version from that project's own documentation for anything beyond a quick experiment.

Use cases

• Service mesh data plane. Run Envoy next to every service so that applications talk to localhost while Envoy handles discovery, load balancing, retries, circuit breaking, TLS and per-hop statistics. The docs recommend HTTP/2 between all Envoys to build a mesh of persistent, multiplexed connections.
• Edge proxy and API gateway. Terminate TLS, accept HTTP/1.1, HTTP/2 and HTTP/3 from clients, and route by path, host or header to backend clusters, with the same observability you use inside the mesh.
• gRPC load balancing. Use Envoy as the routing and load balancing layer for gRPC services, which ride on HTTP/2, with optional listener connection balancing for workloads with a few very long lived connections.
• Building a control plane or product. Teams that want centralized traffic management can implement the xDS APIs and push listeners, routes, clusters and secrets to fleets of Envoys, using EDS to avoid the connection-pool draining that CDS-only updates cause.

How Envoy compares

The comparison Envoy's own documentation makes is with the library approach to service-to-service communication, where every service embeds an RPC or networking library. Envoy's argument is that an out-of-process proxy works for every language and can be upgraded independently of the applications. The trade-off is one more process to run and operate on every host.

Against general-purpose reverse proxies and load balancers such as NGINX or HAProxy, the useful question is operating model. Envoy was built around a protocol-agnostic HTTP/2 stream model, eventually consistent discovery, detailed per-hop statistics and xDS APIs designed to be driven by a control plane; static file configuration works, but much of its design assumes dynamic configuration. Benchmark with your own traffic.

Envoy itself is the data plane. On Kubernetes the project points to Envoy Gateway for Gateway API-based ingress; elsewhere, dynamic setups need a management server that implements xDS, so look at existing control planes before writing one.

Things to know before adopting

• Defaults are tuned for the service mesh, not the edge. The edge best-practices page says Envoy is a production-ready edge proxy but that its defaults target the service mesh case. For edge use it recommends, among other settings, restricting the admin endpoint, configuring the overload manager, 32 KiB listener and cluster buffer limits, use_remote_address set to true, connection and stream timeouts, a limit of 100 concurrent HTTP/2 and HTTP/3 streams, and path normalization when RBAC or path-based routing is used.
• Availability is your job to configure. The threat model states plainly that the project does not consider Envoy's default settings safe from an availability perspective. Operators must explicitly configure watermarks, the overload manager, circuit breakers and other resource controls, and the security team will not act on disclosures that only relate to a lack of safe defaults.
• Not every extension is hardened for untrusted traffic. Core components are considered hardened against untrusted downstream and upstream peers, but extensions are classified individually: some are hardened against both, some only against untrusted downstreams, some require trusted peers on both sides, and some have an unknown security posture. Alpha features are only supported in trusted deployments, and contrib extensions are not officially covered by the threat model or the security team. Lua and WASM filters assume the loaded code is trusted, and the docs describe WASM as still in development. Check each extension's posture before exposing it to the internet.
• The admin interface is out of scope for security. Issues exploitable only through the admin interface are not treated as security issues; securing it so untrusted actors cannot reach it is the operator's responsibility. The quick start warns that binding it to 0.0.0.0 inside Docker may give unintended control of the server.
• Dynamic configuration needs a control plane. Static configs plus DNS and hot restart work, but xDS features require you to run or adopt one or more gRPC/REST management servers. The control plane is treated as trusted in the threat model, though Envoy is expected to be resilient to malicious configuration content such as tenant-supplied regexes.
• Hot restart has limits. Existing connections are not transferred to the new process; they must finish during the drain period or be closed. If concurrency decreases across a restart, some queued connections in the old process may be dropped. Hot restart is not supported on Windows.
• Platform support. The project supports amd64 and arm64 for its Linux builds and images. Official Windows support ended on August 31, 2023 due to a lack of resources, and Windows builds are excluded from CI, release and security processes. The README states that ppc64le builds are best-effort and not covered by the security policy.
• Building from source is a Bazel project. Envoy builds with Bazel (the docs recommend Bazelisk installed as bazel) and a hermetic Clang toolchain that Bazel downloads. The build is modular, so extensions can be toggled with Bazel flags, and the build image needs 4-5GB of disk. The bundled dependency pins are described as suitable only for development and testing and may not carry the latest security patches.
• Release cadence and support window. Major releases ship quarterly from main (scheduled for the 15th day of each quarter). Versions released in the last 12 months get backported security, stability and selected bug fixes, and security releases follow a three-monthly cycle around the midpoint between majors. The release table lists 1.40.0 shipping on 2026/10/13 with an end of life of 2027/10/13. The project considers main release-candidate quality and notes that many organizations deploy it, but the security policy advises at least five days of soak time (seven for a stronger guarantee) before rolling out binaries cut from main.

Project activity

As of November 2026 the repository has about 29,200 stars and more than 5,700 forks. It was created in August 2016, is written mainly in C++ and is licensed under Apache-2.0. The README says the project is hosted by the CNCF. The README also lists a 2018 third-party security audit by Cure53 and a 2021 audit of the fuzzing infrastructure by Ada Logics, and the project runs continuous fuzzing through OSS-Fuzz. Vulnerabilities go through GitHub Security Advisories or the envoy-security list.

Source code and issues are at github.com/envoyproxy/envoy, the documentation lives at envoyproxy.io, and the release process and schedule are documented in RELEASES.md.