Skip to main content
KBY Technologies Logo
cd ../lexicon
sys/docs/lexicon/xds-protocol-envoy-discovery-service-api.md
Lexicon Entry

xDS Protocol (Envoy Discovery Service API)

xDS is the family of gRPC/REST discovery APIs (LDS, RDS, CDS, EDS, SDS) that decouple a data-plane proxy's runtime configuration from static files, allowing a control plane to push listener, route, cluster, and endpoint state incrementally and consistently. It is the mechanism that makes dynamic service mesh and API gateway behavior possible without proxy restarts.

Practical example

Istio's istiod watches Kubernetes Service/EndpointSlice objects, translates scale-up events into EDS deltas, and pushes them over ADS to every sidecar's Envoy instance, updating live traffic routing within seconds without pod restarts.

xDS originated with Envoy but has since become a de-facto standard implemented by Istio, Contour, Gloo, AWS App Mesh, and gRPC’s own client-side load balancing. The protocol defines a set of discovery services, each responsible for one layer of the proxy’s config graph: LDS (Listener Discovery, what ports/filters to bind), RDS (Route Discovery, virtual hosts and match rules), CDS (Cluster Discovery, upstream service definitions), EDS (Endpoint Discovery, the actual IP:port members of a cluster), and SDS (Secret Discovery, TLS certs/keys). These form a dependency chain: a Listener references Routes, Routes reference Clusters, Clusters reference Endpoints — and the control plane must push updates in the correct order to avoid dangling references, which is why Envoy defines ADS (Aggregated Discovery Service) to multiplex all resource types over a single gRPC stream with ordering guarantees.

The critical engineering nuance is the update model. Basic State-of-the-World (SotW) xDS requires the control plane to resend the full resource set on every change, which does not scale past thousands of clusters/endpoints. Incremental xDS (Delta xDS) solves this by sending only added/removed/updated resources plus explicit resource names the client already has, drastically reducing bandwidth and CPU on both sides for large fleets. Consistency is enforced via the version_info and nonce fields in the DiscoveryRequest/DiscoveryResponse exchange — a client ACKs a version it successfully applied, or NACKs with an error detail, and the control plane must handle proxies that are stuck on stale versions without breaking traffic for the fleet.

Update atomicity across resource types is the primary operational hazard. Because CDS, RDS, and EDS are logically separate streams (even when aggregated), a race where a route references a cluster not yet installed causes traffic black-holing until the missing resource lands — this is why Envoy’s make-before-break ordering rule mandates CDS/EDS updates precede RDS updates that reference them, and teardown happens in reverse. Control planes like Istio’s istiod compute this dependency graph per-proxy (per Envoy identity via SNI/xDS node ID) and generate scoped configuration snapshots, which is also the basis for canary and multi-tenant isolation at the mesh layer.

Architecturally, xDS is what allows a mesh to treat configuration as a continuously reconciled desired state rather than a deployment artifact: control planes watch Kubernetes Endpoints/Services, translate them into xDS resources, and push diffs — conceptually similar to a Kubernetes controller reconcile loop but targeting proxy memory instead of etcd. This has direct FinOps and reliability consequences: a control plane outage does not immediately break traffic (Envoy caches last-known-good config), but stale EDS during a scale-up event can route to terminated pods, and xDS push storms during mass rollouts are a common source of control-plane CPU exhaustion at scale.