Mastering Envoy: A Comprehensive Guide to Architecture and Configuration

Envoy is a lightweight L7 proxy and communication bus designed for large‑scale modern SOA (service‑oriented architecture) deployments. It is small, high‑performance, and fulfills many needs with a single piece of software, eliminating the need to combine multiple tools.

The author has previously shared scattered Envoy usage guides; this article consolidates them into a systematic Chinese handbook sourced from the official Envoy documentation, community articles, and the author’s own notes, providing a reference and practical summary for users starting from scratch.

Documentation address: https://fuckcloudnative.io/envoy-handbook/

Envoy Architecture

Envoy’s architecture is illustrated below:

When Envoy receives a request, it first passes through a FilterChain where L3/L4/L7 filters perform fine‑grained processing. The request is then routed to a target cluster, load‑balanced to a specific endpoint, and finally forwarded.

Each stage can be configured statically or discovered dynamically via the xDS API. The “x” functions like the “X” in XaaS, representing a generic service (IaaS, PaaS, SaaS, etc.).

Configuration Structure

The overall Envoy configuration consists of the following sections:

{
  "node": "{...}",
  "static_resources": "{...}",
  "dynamic_resources": "{...}",
  "cluster_manager": "{...}",
  "hds_config": "{...}",
  "flags_path": "...",
  "stats_sinks": [],
  "stats_config": "{...}",
  "stats_flush_interval": "{...}",
  "watchdog": "{...}",
  "tracing": "{...}",
  "runtime": "{...}",
  "layered_runtime": "{...}",
  "admin": "{...}",
  "overload_manager": "{...}",
  "enable_dispatcher_stats": "...",
  "header_prefix": "...",
  "stats_server_version_override": "{...}",
  "use_tcp_for_dns_lookups": "..."
}

node : Identifier for the Envoy instance; used by the management server to distinguish different proxies.

static_resources : Defines static configuration required by Envoy core, comprising Listeners, Clusters, and Secrets.

dynamic_resources : Defines dynamic configuration fetched via xDS; static and dynamic resources can coexist.

cluster_manager : Manages all upstream clusters, handling load balancing, health checks, and connection establishment.

hds_config : Dynamic configuration for health‑check service discovery.

stats_sinks : Plugins for exporting metrics (e.g., Prometheus via /stats/prometheus).

stats_config : Metrics configuration.

stats_flush_interval : Interval for flushing metrics.

watchdog : Built‑in watchdog that increments counters when Envoy becomes unresponsive and can trigger shutdown.

tracing : Distributed tracing settings.

runtime : Runtime configuration (deprecated).

layered_runtime : Hierarchical runtime configuration, loadable statically or via RTDS.

admin : Management interface.

overload_manager : Overload filter configuration.

header_prefix : Prefix added to header fields (e.g., setting X-Foo changes x-envoy-retry-on to x-foo-retry-on).

use_tcp_for_dns_lookups : Forces DNS queries over TCP; can be overridden per Cluster.

Filters

Envoy runs a series of inbound/outbound Listeners. Inbound listeners proxy inbound traffic, outbound listeners proxy outbound traffic. The core of a Listener is its FilterChain, where each filter controls traffic processing.

Filters are divided into two categories:

Network Filters : Operate at L3/L4, handling raw network connections.

HTTP Filters : Operate at L7, managed by the HTTP connection manager to process HTTP1/HTTP2/gRPC requests.

Beyond the HTTP connection manager, Envoy also provides a special network filter called the Thrift Proxy, which manages Router and Rate Limit filters for Thrift RPC traffic.

Listener Filters run before the FilterChain, allowing manipulation of connection metadata without modifying Envoy core code (e.g., applying a UDP Listener Filter when the listening address uses UDP).

The filter architecture is illustrated below: