Trace a single HTTP request through Envoy's configuration objects, from the TCP port it arrives on to the backend instance that finally serves it. Which object handles each step, and what does each one own?

## The four objects Everything Envoy does — whether hand-written YAML or config generated by a control plane — reduces to four object types: **listeners**, **filter chains (with filters)**, **routes**, and **clusters**. Knowing the boundary between them is what lets you debug a proxy you did not configure yourself. ## 1. The listener: where bytes arrive A listener binds a socket, usually an `address.socket_address` with an `address` and a `port_value`. It is a *downstream* object: it accepts connections from clients. A listener may first run `listener_filters`, which peek at the beginning of the connection before any real processing — the TLS inspector reads the ClientHello for SNI and ALPN, the HTTP inspector detects the protocol version. Their job is to produce facts that the next step can match on. The listener then chooses one of its `filter_chains`. Each chain may carry a `filter_chain_match` (destination port, `server_names`, `transport_protocol`, `application_protocols`, source IP) and its own `transport_socket` — which is where TLS actually terminates, if it terminates here at all. ## 2. The filter chain: network filters A chain's `filters` are **network (L4) filters**. They see a byte stream, not requests. `envoy.filters.network.tcp_proxy` simply shovels bytes to a cluster — that is an L4 proxy and there is no route object involved at all. For HTTP you instead install `envoy.filters.network.http_connection_manager`. ## 3. http_connection_manager: bytes become requests HCM is the object that makes Envoy an L7 proxy. It owns the downstream codec (HTTP/1.1, HTTP/2, and HTTP/3 where enabled), request framing, `stat_prefix`, header handling such as `use_remote_address`, and the **HTTP filter chain**. HTTP filters operate on headers, body and trailers of one request: `envoy.filters.http.ext_authz` calls an external authorization service, `envoy.filters.http.lua` and `envoy.filters.http.wasm` run custom logic, and `envoy.filters.http.router` is the terminal filter that actually forwards the request upstream. Filters before the router can mutate, reject or pause a request; nothing after the router runs, because the router ends the chain. ## 4. route_config: choosing a destination *name* HCM carries either an inline `route_config` or a reference resolved dynamically. A route configuration holds `virtual_hosts`; each has a `domains` list matched against the request authority (the `Host` header or `:authority` pseudo-header), and an ordered `routes` list. Each route has a `match` (`prefix`, `path`, `safe_regex`, plus optional header and query matchers) and an action — most often `route: { cluster: <name> }`, but also `weighted_clusters`, `redirect` or `direct_response`. The critical detail: the route names a cluster **by string**. It does not know an IP, a port, or how many backends exist. ## 5. The cluster: the upstream group A cluster is the *upstream* object. It owns: - how membership is discovered — the `type` field: `STATIC`, `STRICT_DNS`, `LOGICAL_DNS`, `EDS`, `ORIGINAL_DST`; - the endpoints themselves, via `load_assignment` for static and DNS clusters; - `lb_policy` (`ROUND_ROBIN`, `LEAST_REQUEST`, `RING_HASH`, `MAGLEV`, `RANDOM`); - connection behaviour such as `connect_timeout`, upstream protocol options and TLS to the backend via its own `transport_socket`. When the router hands the request to a cluster, the cluster's load balancer picks one healthy endpoint and the request goes out on a connection from that cluster's pool. ```yaml routes: - match: { prefix: "/api/" } route: { cluster: service_backend } # a NAME, not an address ``` ## Why the split is designed this way Routes change for product reasons (a new path, a header-based split); cluster membership changes constantly for infrastructure reasons (a pod restarted, an instance scaled in). Keeping them in separate objects means endpoint churn never rewrites your routing rules, and route changes never disturb connection pools. It is also why the two are delivered by different discovery services. ## Reading a failure through the model The model tells you where to look. Connection refused at the socket means listener or filter-chain selection. A 404 that Envoy generated itself means no virtual host domain or no route matched. A 503 means routing succeeded but the cluster had no healthy endpoint or the upstream connection failed. Each symptom belongs to exactly one object.