Envoy

What this wiki covers

This wiki explains how the Envoy source tree is organised and how its major subsystems fit together. It is aimed at engineers who want to read, modify, or extend the Envoy code itself, not at operators looking for configuration reference (which lives at envoyproxy.io).

Start here:

• Architecture — the layered model: listener → filter chains → cluster manager → upstream
• Getting started — building, testing and running Envoy from source
• Glossary — Envoy-specific vocabulary (xDS, EDS, HCM, LDS, etc.)

Then dive into specific lenses:

• Systems — the long-lived components inside an Envoy process (listener manager, cluster manager, HTTP connection manager, router, stats, runtime, admin, hot restart…)
• Features — cross-cutting capabilities (xDS, HTTP filters, transport sockets, access logging, tracing, load balancing, dynamic modules)
• Apps — the deployable binaries: envoy-static, envoy-contrib, and Envoy Mobile
• API — the xDS protobuf API in api/
• Reference — configuration, dependencies, build system

What Envoy actually does

At its core Envoy is an event-driven proxy:

1. A listener binds a socket and accepts connections.
2. A chain of listener filters inspects the new connection (TLS SNI, original_dst, proxy protocol, …).
3. A chain of network filters runs the L4 protocol — typically the HTTP connection manager which itself runs a chain of L7 HTTP filters.
4. The terminal filter (the router) selects an upstream cluster managed by the cluster manager.
5. A load balancer picks a host, a connection pool picks a connection, a transport socket wraps the bytes, and the request flies upstream.

Around that core: a thread-local world that avoids locks on the hot path, an admin interface for operators, stats and tracing for observability, and hot restart for zero-downtime upgrades.

The whole configuration surface — listeners, clusters, routes, secrets, runtime — is delivered over xDS, Envoy's gRPC-based discovery protocol.

Top-level repository layout

Directory	Purpose
api/	xDS protobuf data-plane API definitions
envoy/	Public abstract interface headers ("core" Envoy)
source/common/	Implementation of core Envoy that is not server-specific
source/server/	Server lifecycle, options, listener manager, admin
source/exe/	The envoy-static main() entrypoint and signal handling
source/extensions/	Pluggable extensions: filters, clusters, transport sockets, tracers…
contrib/	Contrib extensions (looser guarantees, separate envoy-contrib binary)
mobile/	Envoy Mobile — Android/iOS/C library
test/	Unit, integration, fuzz and benchmark tests
bazel/	Bazel rules, toolchains, third-party repository bindings
tools/	Code-format, proto-format, dependency, release tooling
ci/	CI scripts and Docker images

The canonical layout reference is REPO_LAYOUT.md.

Where the wiki goes from here

If you are new to the codebase, the recommended reading order is:

1. Architecture
2. Threading model
3. HTTP connection manager
4. Cluster manager
5. Whichever subsystem or extension you actually need to touch.