Fork: 0
yangyangxie / aegis-public
Transfer to URL with SHA Find file
Newer
Older
aegis-public / docs / envoy-config.md
@Jerry Xie Jerry Xie on 19 May 3 KB docs: add detailed README in scripts folder explaining the demo traffic generator architecture
Raw Blame History

Envoy Configuration

Aegis controls Envoy via xDS (specifically using the ADS - Aggregated Discovery Service - protocol). You configure everything through the Aegis UI — no manual YAML editing required.

How it works

  1. Envoy starts using a static bootstrap file (envoy.yaml) pointing it to Aegis.
  2. Envoy connects to Aegis at aegis:18000 (gRPC ADS).
  3. Aegis pushes listeners, clusters, and secrets dynamically from its database.
  4. Changes made in the Aegis UI take effect in Envoy within ~1 second.

Static bootstrap (envoy.yaml)

Envoy needs a static bootstrap file to know where to find the xDS server. The provided envoy/envoy.yaml configures:

  • xDS server: aegis:18000 (using gRPC).
  • Node ID: home (must match NODE_ID env var in Aegis).
  • Admin interface: bound to port 9901 (internal or public as mapped in docker-compose).

Do not add listeners or clusters to this bootstrap file. They should be managed entirely through the Aegis Gateway UI (and are stored in Aegis's database).

Dynamic configuration (starter.json)

The configs/starter.json is not read by Envoy. It is an export of the Aegis database structure. When imported via the Aegis UI, it configures:

  • http_listener (port 10080): Redirects all standard HTTP traffic to HTTPS, but routes /.well-known/acme-challenge to the acme-renewer cluster.
  • https_listener (port 10443): Placeholder for your SSL traffic with SNI matching.
  • acme-renewer cluster: Points to Aegis's built-in ACME challenge responder.
  • my-service cluster: Placeholder for your actual backend application.

Once imported, Aegis dynamically translates these into Envoy-native config and pushes them to Envoy over the xDS channel.

Exposing Envoy to Public Traffic (Port Mapping)

To make your gateway accept real public traffic from the internet, you must understand how ports are mapped between your host machine and the Envoy container.

The Port Flow

Internet ──► Host Port 80  ──────(Docker Map)─────► Container Port 10080 (Envoy HTTP Listener)
Internet ──► Host Port 443 ──────(Docker Map)─────► Container Port 10443 (Envoy HTTPS Listener)
  1. Docker Port Mapping: In docker-compose.yml, the envoy service exposes ports 80 and 443 on the host, mapping them to 10080 and 10443 inside the container respectively.
    • This is done because binding to privileged ports (< 1024) directly inside a container is restricted by default for security.
  2. UI Port Binding: When you create or edit Listeners in the Aegis UI, you must bind them to the container port, NOT the host port:
    • Your HTTP listener (handling redirects and ACME challenge) must bind to 10080.
    • Your HTTPS listener (handling secure SSL traffic) must bind to 10443.
  3. Public Access: Once the containers are running, simply point your domain's DNS A or AAAA records to your host machine's public IP address. Traffic arriving at port 80/443 will automatically flow through Envoy.