Envoy Configuration

Aegis controls Envoy via xDS (ADS protocol). You configure everything through the Aegis UI — no manual YAML editing required.

How it works

1. Envoy connects to Aegis at aegis:18000 (gRPC ADS)
2. Aegis pushes listeners, clusters, and secrets dynamically
3. Changes in the Aegis UI take effect in Envoy within ~1 second

Static bootstrap (envoy.yaml / starter.json)

Envoy needs a static bootstrap file to know where to find the xDS server. The provided configs/starter.json configures:

• xDS server: aegis:18000
• Access log: streamed to Aegis via gRPC ALS (provides real-time traffic data)
• Node ID: home (must match NODE_ID env var in Aegis)

Do not add listeners or clusters to the bootstrap file — manage them entirely through the Aegis Gateway UI.

Gateway concepts

Listeners

A listener binds to a port and accepts connections. Typically:

• One listener on port 80 (HTTP)
• One listener on port 443 (HTTPS)

Filter chains

Each listener can have multiple filter chains. A filter chain matches incoming connections (by SNI/domain) and routes them to a backend cluster. Each filter chain can have:

• A TLS secret (for HTTPS)
• A backend cluster
• HTTP extensions (OIDC, rate limiting, Lua, etc.)

Clusters

An upstream cluster defines where traffic goes. Types:

• STATIC — fixed IP/hostname (resolved once at startup)
• LOGICAL_DNS — resolve hostname once and cache
• STRICT_DNS — resolve on every connection

Secrets (SDS)

TLS certificates stored in Envoy's Secret Discovery Service. Aegis manages these automatically when you issue certificates via the Certs page.

Common setups

Reverse proxy for a single service

1. Create a cluster pointing to your service (e.g. 192.168.1.10:3000)
2. Add an HTTPS listener on port 443
3. Add a filter chain: domain = app.example.com, cluster = your cluster, TLS = your cert

Multiple domains on one server

Add one filter chain per domain to your HTTPS listener. Each filter chain has its own SNI match, backend cluster, and TLS secret.

HTTP → HTTPS redirect

Add a catch-all filter chain on the port-80 listener with a Lua HTTP filter that returns a 301 redirect.

Blocked IPs

Blocked IPs are automatically injected as Envoy RBAC deny rules on every xDS push. You do not need to configure this.

Troubleshooting

"xDS NACK" in the dashboard header means Envoy rejected the last config. The error message shows which resource failed. Fix the highlighted resource and save again.

Changes not applying — check that the xDS status is "synced" (green dot). If it shows "xDS …" (grey), Envoy is not connected — verify the NODE_ID env var matches the node ID in your bootstrap config.