envoy-xds

A small, typed Envoy xDS control plane in Python. Reads YAML, compiles it into Envoy CDS/EDS/RDS/LDS resources, and serves them to Envoy fleets over ADS (gRPC).

Features

• Typed desired state (Pydantic) — bad YAML can't reach Envoy.
• Rejected snapshots — invalid edits are recorded; the last good snapshot keeps serving.
• Hot reload — watchdog-driven, debounced, revision-hashed.
• Fleet selection — match node.id or node.cluster to proxy groups.
• ACK/NACK tracking per proxy, exposed through a JSON admin API.
• Tiny admin UI — HTMX page at / over the existing admin state.

Quickstart

just demo
# in another shell
curl -sS -H 'Host: api.local' http://127.0.0.1:10000/   # → api-v1
just verify

Architecture

examples/context/*.yaml
        ↓
LocalContextSource → merge → DesiredState (Pydantic)
        ↓
EnvoyCompiler → typed Resources → protobuf Any
        ↓
ResourceValidator → SnapshotStore
        ↓
ADS gRPC stream → Envoy fleet

Admin API (FastAPI) reads state only: /healthz, /readyz, /api/snapshots, /api/proxies, /api/resources/{version}, /api/render-errors. A small HTMX dashboard is served at /.

Proxy groups can select listener settings per Envoy node:

proxy_groups:
  default:
    node_match: {}
    listener_port: 10000
  edge:
    node_match:
      cluster: edge
    listener_port: 10001
  canary:
    node_match:
      id: proxy-canary-1
    listener_port: 10002

License

MIT