Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 36 ยท Service Mesh Concepts

Envoy and the xDS APIs

Understand how Envoy is configured in Istio through xDS: listeners, routes, clusters and endpoints, and how to inspect them with istioctl proxy-config.

Istio's YAML is a friendly layer on top of Envoy's configuration model. When something behaves unexpectedly, you eventually need to look at what the proxy actually received. That requires four words: listener, route, cluster, endpoint. They are the same four concepts every time, and once you know them the istioctl proxy-config output stops looking like noise.

The four building blocks

  • Listener (LDS). A port the proxy listens on, with filters that decide what to do with the connection. In a sidecar, there are virtual listeners on 15001 (outbound) and 15006 (inbound), and the proxy picks a filter chain by the original destination port and protocol.
  • Route (RDS). For HTTP, a table that maps a virtual host (catalog.shop.svc.cluster.local) and a path or header match to a cluster. This is where your VirtualService rules end up.
  • Cluster (CDS). A named group of upstream endpoints with load balancing, connection pool and TLS settings. A DestinationRule shapes clusters. Istio names them like outbound|80|v1|catalog.shop.svc.cluster.local: direction, port, subset, host.
  • Endpoint (EDS). The actual pod IPs and ports behind a cluster, with health and locality. They come from Kubernetes endpoints and change constantly.

Together they are called xDS ("x Discovery Service"). A request flows through them left to right:

flowchart LR
    L["Listener<br/>(port, filters)"] --> R["Route<br/>(host, path, headers)"]
    R --> C["Cluster<br/>(policy, TLS)"]
    C --> E["Endpoint<br/>(pod IP:port)"]

Listener to route to cluster to endpoint: the path every proxied HTTP request follows.

A fifth API, SDS (secret discovery), delivers certificates and keys to the proxy, which is how workload certificates rotate without restarts.

Why dynamic matters

Envoy could be configured from a static file. Istio instead uses streaming gRPC: the proxy opens one connection to istiod, subscribes to resource types, and receives updates as they change. Istio normally uses the aggregated form (ADS) on one stream so updates are ordered correctly: a route must not point to a cluster that has not arrived yet. Updates are incremental where possible, so adding a pod does not resend the whole world. Each update is acknowledged (ACK) or rejected (NACK) by the proxy; a NACK usually means the generated config was invalid, and istioctl proxy-status shows it as stale.

Inspecting a proxy

All of these are read-only commands against a real cluster:

Terminal
istioctl proxy-config listeners  web-7d9c.shop
istioctl proxy-config routes     web-7d9c.shop --name 80
istioctl proxy-config clusters   web-7d9c.shop --fqdn catalog.shop.svc.cluster.local
istioctl proxy-config endpoints  web-7d9c.shop --cluster "outbound|80||catalog.shop.svc.cluster.local"

Use -o json for the complete Envoy configuration. The Envoy admin interface is also reachable from inside the pod on port 15000, for example kubectl exec ... -c istio-proxy -- curl localhost:15000/clusters.

A useful debugging recipe: start at the route (does the host and path match?), then the cluster (does the subset exist?), then the endpoints (are there healthy pods?). Empty endpoints for a cluster mean no pod matched the subset's labels.

A route and cluster resolver

This stand-in models route matching and endpoint selection on dictionaries. It uses simplified rules (first match wins, exact or prefix path), not the complete Envoy matching engine.

Python Stand-in: route matching to a cluster

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Stand-in: clusters and endpoints

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The second stand-in explains a real Envoy symptom: a cluster with zero healthy endpoints answers 503 with the flag UH (no healthy upstream) in the access log.

Common response flags

When you turn on access logs (Installing Istio with istioctl showed accessLogFile), each line carries flags that say why Envoy answered the way it did:

Flag Meaning
NR No route configured for the request
UH No healthy upstream endpoints
UF Upstream connection failure
UC Upstream connection terminated
URX Retry limit exceeded
UT Upstream request timeout
DC Downstream connection closed

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In what order does a proxied HTTP request use xDS resources?

    A listener accepts the connection, a route picks a cluster, the cluster chooses an endpoint.
  2. 2. A cluster named outbound|80|v2|catalog has no endpoints. What is the most likely cause?

    Subsets select pods by label; if nothing matches, the cluster is empty and requests get UH/503.
  3. 3. What does a NACK from a proxy indicate?

    Proxies ACK valid updates and NACK invalid ones; a NACK leaves the proxy on older config.
  4. 4. Which response flag means 'no route configured'?

    NR means no route matched. UH is no healthy upstream, UT is an upstream timeout.

Summary

  • Envoy config is built from listeners, routes, clusters and endpoints, plus secrets (SDS).
  • istiod streams these over ADS gRPC and the proxy ACKs or NACKs each update.
  • istioctl proxy-config shows each layer; debug from route to cluster to endpoint.
  • Response flags (NR, UH, UF, UT...) in access logs tell you why a request failed.
  • VirtualService feeds routes; DestinationRule feeds clusters.

Next: The Istio Resource Model