diff --git a/docs/tutorials/01-whoami-local-https.md b/docs/tutorials/01-whoami-local-https.md new file mode 100644 index 0000000..6773d3d --- /dev/null +++ b/docs/tutorials/01-whoami-local-https.md @@ -0,0 +1,205 @@ +# Tutorial Series: Exposing a Service with Aegis + +| # | Tutorial | Description | +|---|---|---| +| **1** | **Local HTTPS with a whoami service** ← you are here | Configure the gateway manually through the UI | +| 2 | [Configure the Gateway with Owl AI](02-whoami-ai-setup.md) | Let Owl AI do the configuration for you | + +--- + +# Part 1 — Local HTTPS with a whoami service + +> **Prerequisite:** Before starting this tutorial, make sure your Aegis gateway and Envoy are up and running. Follow the [Getting Started](../getting-started.md) guide first — this tutorial picks up from a working gateway. + +This tutorial walks through deploying a simple whoami web service and exposing it over HTTPS through Envoy, using Aegis's built-in Local CA — no public domain or open ports required. + +**You will:** +1. Run a `whoami` container alongside Aegis + Envoy +2. Add a cluster and filter chain in Aegis +3. Issue a TLS certificate from the Local CA +4. Add a `/etc/hosts` entry +5. Access `https://whoami.local` from your browser + +--- + +## Prerequisites + +- Docker and Docker Compose installed +- Aegis + Envoy already running and accessible at `http://localhost:8765` +- Admin access to add an `/etc/hosts` entry on your machine + +--- + +## Step 1 — Run the whoami container + +Start `whoami` as a standalone container with a published port: + +```bash +docker run -d --name whoami -p 8081:80 --restart unless-stopped traefik/whoami +``` + +It runs independently — no changes to your existing `docker-compose.yml` needed. + +![Run whoami container](../assets/step1-run-whoami.gif) + +--- + +## Step 2 — Add a cluster in Aegis + +Open the Aegis dashboard → **Gateway → Clusters → Add Cluster**. + +| Field | Value | +|---|---| +| Name | `whoami` | +| Type | `STRICT_DNS` | +| Host | `host.docker.internal` | +| Port | `8081` | +| Connect timeout | `5s` | + +> **Mac / Docker Desktop only:** expand **Advanced parameters** and add `{"dnsLookupFamily":"V4_ONLY"}` — Docker Desktop resolves `host.docker.internal` to IPv6 first, which breaks connections to IPv4-only containers. + +Save — Aegis pushes the cluster to Envoy immediately. + +![Add whoami cluster in Aegis](../assets/step2-add-cluster.gif) + +--- + +## Step 3 — Issue a Local CA certificate + +### 3a — Create a Local CA provider (first time only) + +Go to **Certificates → Signing Providers → Add Provider**, choose **Local CA**, give it a name (e.g. `Local CA`), and save. + +### 3b — Issue the certificate + +Go to **Certificates → Managed Certs → Issue Certificate**: + +| Field | Value | +|---|---| +| Domain | `whoami.local` | +| Provider | `Local CA` | +| Auto-renew | on | + +Click **Issue**. The cert is generated and pushed to Envoy SDS within a second. Note the **secret name** shown (e.g. `tls-whoami-local`). + +![Issue certificate from Local CA](../assets/step3-issue-cert.gif) + +--- + +## Step 4 — Add a filter chain to the HTTPS listener + +Go to **Gateway → Listeners → `https_listener` → Edit**. + +Click **Add Filter Chain** and fill in: + +| Field | Value | +|---|---| +| Domain(s) | `whoami.local` | +| Backend Cluster | `whoami` | +| TLS Secret | `tls-whoami-local` _(or the name shown on the cert page)_ | + +Leave Route Prefix as `/` and click **Add**. Envoy picks up the new filter chain within ~1 second. + +![Add filter chain to HTTPS listener](../assets/step4-add-filter-chain.gif) + +--- + +## Step 5 — Trust the Root CA + +First, download the Root CA certificate. You can do this two ways: + +**Option A — from the UI:** Go to **Certificates → Signing Providers**, click **Download CA Cert** next to your Local CA provider. This downloads `aegis-local-ca.crt` directly from the browser. + +**Option B — via curl:** +```bash +curl -s http://localhost:8765/api/certs/ca -o aegis-local-ca.crt +``` + +Then install it in your OS trust store: + +**macOS:** +```bash +sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain aegis-local-ca.crt +``` + +**Linux:** +```bash +sudo cp aegis-local-ca.crt /usr/local/share/ca-certificates/aegis-local-ca.crt +sudo update-ca-certificates +``` + +**Windows (PowerShell as Administrator):** +```powershell +Import-Certificate -FilePath aegis-local-ca.crt -CertStoreLocation Cert:\LocalMachine\Root +``` + +Restart your browser after installing the CA. + +![Download and trust the Root CA](../assets/step5-trust-ca.gif) + +--- + +## Step 6 — Add an `/etc/hosts` entry + +Map `whoami.local` to the IP address of the machine running Envoy: + +- **Running on your local machine** — use `127.0.0.1` +- **Running on a NAS or remote server** — use that machine's LAN IP (e.g. `192.168.1.100`) + +```bash +# Local machine +echo "127.0.0.1 whoami.local" | sudo tee -a /etc/hosts + +# Or remote host (replace with actual IP) +echo "192.168.1.100 whoami.local" | sudo tee -a /etc/hosts +``` + +On Windows, edit `C:\Windows\System32\drivers\etc\hosts` as Administrator. + +![Add whoami.local to /etc/hosts](../assets/step6-etc-hosts.gif) + +--- + +## Step 7 — Open in browser + +Navigate to **`https://whoami.local`**. + +You should see the whoami response — hostname, IP, headers — served over HTTPS with a valid (locally trusted) certificate and no browser warning. + +![whoami.local trusted in browser](../assets/step7-browser-verify.gif) + +--- + +## What just happened + +``` +Browser → https://whoami.local:443 + │ SNI = whoami.local + ▼ + Envoy (port 10443) + │ filter chain match: whoami.local + │ TLS: cert from Aegis SDS (signed by Local CA) + ▼ + whoami container (port 80) +``` + +Aegis issued the cert from its internal Root CA, pushed it to Envoy via xDS SDS, and Envoy presented it during the TLS handshake. Your browser trusted it because you installed the Root CA. + +--- + +## Cleanup + +To remove the setup: + +1. Delete the managed cert in Aegis → Certificates +2. Remove the filter chain from `https_listener` +3. Delete the `whoami` cluster +4. Remove the `/etc/hosts` line +5. Stop the whoami container: `docker rm -f whoami` + +--- + +## Next + +**[Part 2 → Configure the Gateway with Owl AI](02-whoami-ai-setup.md)** +You've seen how to set this up manually. In the next tutorial, you hand a single prompt to Owl AI and it configures the cluster, certificate, and filter chain for you — no UI clicks required. diff --git a/docs/tutorials/02-whoami-ai-setup.md b/docs/tutorials/02-whoami-ai-setup.md new file mode 100644 index 0000000..81e33fa --- /dev/null +++ b/docs/tutorials/02-whoami-ai-setup.md @@ -0,0 +1,166 @@ +# Tutorial Series: Exposing a Service with Aegis + +| # | Tutorial | Description | +|---|---|---| +| 1 | [Local HTTPS with a whoami service](01-whoami-local-https.md) | Configure the gateway manually through the UI | +| **2** | **Configure the Gateway with Owl AI** ← you are here | Let Owl AI do the configuration for you | + +--- + +# Part 2 — Configure the Gateway with Owl AI + +> **Prerequisite:** Complete [Part 1 — Local HTTPS with a whoami service](01-whoami-local-https.md) first to understand what we're building. This tutorial sets up the same thing — but Owl AI does the configuration for you. + +Instead of clicking through the UI, you describe what you want to Owl and it handles the gateway configuration end-to-end: cluster, certificate, and filter chain. + +**You will:** +1. Run a `whoami` container +2. Hand one prompt to Owl AI +3. Add a `/etc/hosts` entry +4. Access `https://whoami.local` from your browser + +--- + +## Prerequisites + +- Docker and Docker Compose installed +- Aegis + Envoy already running and accessible at `http://localhost:8765` +- Admin access to add an `/etc/hosts` entry on your machine + +### Configure Owl Chat (first time only) + +Go to **Settings → AI → Owl Chat**, enable it, pick a provider (e.g. Gemini), enter your API key, and save. Owl will immediately show as ready (green dot). + +![Configure Gemini API key for Owl Chat](../assets/owl-ai-setup-demo.gif) + +Once configured you can ask Owl questions about recent traffic — it has live access to your gateway logs and threat intelligence. + +--- + +## Step 1 — Run the whoami container + +Same as the manual tutorial — start `whoami` as a standalone container: + +```bash +docker run -d --name whoami -p 8081:80 --restart unless-stopped traefik/whoami +``` + +--- + +## Step 2 — Ask Owl to set everything up + +Open the Owl chat panel (🦉 button, bottom-right) and paste this prompt: + +``` +Set up whoami on my gateway: create a cluster named whoami with type STRICT_DNS, +host host.docker.internal, port 8081, connect timeout 5s, and advanced params +{"dnsLookupFamily":"V4_ONLY"}; then create a Local CA provider if one doesn't +exist; issue a TLS cert for whoami.local with auto-renew; finally add a filter +chain to https_listener for domain whoami.local routing to the whoami cluster +using the issued cert's secret name. +``` + +Owl will walk through each step, confirm with you before making changes, and report back when done. + +![Owl AI configuring the whoami gateway](../assets/owl-ai-gateway-setup.gif) + +--- + +## Step 3 — Trust the Root CA + +If this is your first Local CA certificate, download and install the Root CA so your browser trusts it. + +**Option A — from the UI:** Go to **Certificates → Signing Providers**, click **Download CA Cert** next to your Local CA provider. + +**Option B — via curl:** +```bash +curl -s http://localhost:8765/api/certs/ca -o aegis-local-ca.crt +``` + +Then install it: + +**macOS:** +```bash +sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain aegis-local-ca.crt +``` + +**Linux:** +```bash +sudo cp aegis-local-ca.crt /usr/local/share/ca-certificates/aegis-local-ca.crt +sudo update-ca-certificates +``` + +**Windows (PowerShell as Administrator):** +```powershell +Import-Certificate -FilePath aegis-local-ca.crt -CertStoreLocation Cert:\LocalMachine\Root +``` + +Restart your browser after installing the CA. + +--- + +## Step 4 — Add an `/etc/hosts` entry + +```bash +# Local machine +echo "127.0.0.1 whoami.local" | sudo tee -a /etc/hosts + +# Or remote host (replace with actual IP) +echo "192.168.1.100 whoami.local" | sudo tee -a /etc/hosts +``` + +On Windows, edit `C:\Windows\System32\drivers\etc\hosts` as Administrator. + +--- + +## Step 5 — Open in browser + +Navigate to **`https://whoami.local`**. + +You should see the whoami response served over HTTPS with a valid locally-trusted certificate — configured entirely by Owl. + +--- + +## What just happened + +``` +You (one prompt) + │ + ▼ +Owl AI + ├─ gateway_upsert_cluster → created "whoami" cluster + ├─ certs_create_provider → created Local CA (if needed) + ├─ certs_issue_cert → issued tls-whoami-local + └─ gateway_upsert_filter_chain → added filter chain to https_listener + │ + ▼ + Envoy (port 10443) + │ + ▼ + whoami container (port 80) +``` + +Owl used Aegis's MCP tools to make each change atomically. Every step was validated against the Envoy proto schema and pushed live via xDS — no restarts, no YAML files. + +--- + +## Cleanup + +Ask Owl to clean up for you: + +``` +Remove the whoami setup: delete the whoami.local filter chain from https_listener, +delete the whoami.local managed cert, and delete the whoami cluster. +``` + +Or do it manually: + +1. Delete the filter chain from `https_listener` in Gateway → Listeners +2. Delete the managed cert in Certificates +3. Delete the `whoami` cluster in Gateway → Clusters +4. Remove the `/etc/hosts` line +5. Stop the whoami container: `docker rm -f whoami` + +--- + +**← [Part 1 — Local HTTPS with a whoami service](01-whoami-local-https.md)** diff --git a/docs/tutorials/whoami-ai-setup.md b/docs/tutorials/whoami-ai-setup.md deleted file mode 100644 index e09d9ad..0000000 --- a/docs/tutorials/whoami-ai-setup.md +++ /dev/null @@ -1,166 +0,0 @@ -# Tutorial Series: Exposing a Service with Aegis - -| # | Tutorial | Description | -|---|---|---| -| 1 | [Local HTTPS with a whoami service](whoami-local-https.md) | Configure the gateway manually through the UI | -| **2** | **Configure the Gateway with Owl AI** ← you are here | Let Owl AI do the configuration for you | - ---- - -# Part 2 — Configure the Gateway with Owl AI - -> **Prerequisite:** Complete [Part 1 — Local HTTPS with a whoami service](whoami-local-https.md) first to understand what we're building. This tutorial sets up the same thing — but Owl AI does the configuration for you. - -Instead of clicking through the UI, you describe what you want to Owl and it handles the gateway configuration end-to-end: cluster, certificate, and filter chain. - -**You will:** -1. Run a `whoami` container -2. Hand one prompt to Owl AI -3. Add a `/etc/hosts` entry -4. Access `https://whoami.local` from your browser - ---- - -## Prerequisites - -- Docker and Docker Compose installed -- Aegis + Envoy already running and accessible at `http://localhost:8765` -- Admin access to add an `/etc/hosts` entry on your machine - -### Configure Owl Chat (first time only) - -Go to **Settings → AI → Owl Chat**, enable it, pick a provider (e.g. Gemini), enter your API key, and save. Owl will immediately show as ready (green dot). - -![Configure Gemini API key for Owl Chat](../assets/owl-ai-setup-demo.gif) - -Once configured you can ask Owl questions about recent traffic — it has live access to your gateway logs and threat intelligence. - ---- - -## Step 1 — Run the whoami container - -Same as the manual tutorial — start `whoami` as a standalone container: - -```bash -docker run -d --name whoami -p 8081:80 --restart unless-stopped traefik/whoami -``` - ---- - -## Step 2 — Ask Owl to set everything up - -Open the Owl chat panel (🦉 button, bottom-right) and paste this prompt: - -``` -Set up whoami on my gateway: create a cluster named whoami with type STRICT_DNS, -host host.docker.internal, port 8081, connect timeout 5s, and advanced params -{"dnsLookupFamily":"V4_ONLY"}; then create a Local CA provider if one doesn't -exist; issue a TLS cert for whoami.local with auto-renew; finally add a filter -chain to https_listener for domain whoami.local routing to the whoami cluster -using the issued cert's secret name. -``` - -Owl will walk through each step, confirm with you before making changes, and report back when done. - -![Owl AI configuring the whoami gateway](../assets/owl-ai-gateway-setup.gif) - ---- - -## Step 3 — Trust the Root CA - -If this is your first Local CA certificate, download and install the Root CA so your browser trusts it. - -**Option A — from the UI:** Go to **Certificates → Signing Providers**, click **Download CA Cert** next to your Local CA provider. - -**Option B — via curl:** -```bash -curl -s http://localhost:8765/api/certs/ca -o aegis-local-ca.crt -``` - -Then install it: - -**macOS:** -```bash -sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain aegis-local-ca.crt -``` - -**Linux:** -```bash -sudo cp aegis-local-ca.crt /usr/local/share/ca-certificates/aegis-local-ca.crt -sudo update-ca-certificates -``` - -**Windows (PowerShell as Administrator):** -```powershell -Import-Certificate -FilePath aegis-local-ca.crt -CertStoreLocation Cert:\LocalMachine\Root -``` - -Restart your browser after installing the CA. - ---- - -## Step 4 — Add an `/etc/hosts` entry - -```bash -# Local machine -echo "127.0.0.1 whoami.local" | sudo tee -a /etc/hosts - -# Or remote host (replace with actual IP) -echo "192.168.1.100 whoami.local" | sudo tee -a /etc/hosts -``` - -On Windows, edit `C:\Windows\System32\drivers\etc\hosts` as Administrator. - ---- - -## Step 5 — Open in browser - -Navigate to **`https://whoami.local`**. - -You should see the whoami response served over HTTPS with a valid locally-trusted certificate — configured entirely by Owl. - ---- - -## What just happened - -``` -You (one prompt) - │ - ▼ -Owl AI - ├─ gateway_upsert_cluster → created "whoami" cluster - ├─ certs_create_provider → created Local CA (if needed) - ├─ certs_issue_cert → issued tls-whoami-local - └─ gateway_upsert_filter_chain → added filter chain to https_listener - │ - ▼ - Envoy (port 10443) - │ - ▼ - whoami container (port 80) -``` - -Owl used Aegis's MCP tools to make each change atomically. Every step was validated against the Envoy proto schema and pushed live via xDS — no restarts, no YAML files. - ---- - -## Cleanup - -Ask Owl to clean up for you: - -``` -Remove the whoami setup: delete the whoami.local filter chain from https_listener, -delete the whoami.local managed cert, and delete the whoami cluster. -``` - -Or do it manually: - -1. Delete the filter chain from `https_listener` in Gateway → Listeners -2. Delete the managed cert in Certificates -3. Delete the `whoami` cluster in Gateway → Clusters -4. Remove the `/etc/hosts` line -5. Stop the whoami container: `docker rm -f whoami` - ---- - -**← [Part 1 — Local HTTPS with a whoami service](whoami-local-https.md)** diff --git a/docs/tutorials/whoami-local-https.md b/docs/tutorials/whoami-local-https.md deleted file mode 100644 index fbeb211..0000000 --- a/docs/tutorials/whoami-local-https.md +++ /dev/null @@ -1,205 +0,0 @@ -# Tutorial Series: Exposing a Service with Aegis - -| # | Tutorial | Description | -|---|---|---| -| **1** | **Local HTTPS with a whoami service** ← you are here | Configure the gateway manually through the UI | -| 2 | [Configure the Gateway with Owl AI](whoami-ai-setup.md) | Let Owl AI do the configuration for you | - ---- - -# Part 1 — Local HTTPS with a whoami service - -> **Prerequisite:** Before starting this tutorial, make sure your Aegis gateway and Envoy are up and running. Follow the [Getting Started](../getting-started.md) guide first — this tutorial picks up from a working gateway. - -This tutorial walks through deploying a simple whoami web service and exposing it over HTTPS through Envoy, using Aegis's built-in Local CA — no public domain or open ports required. - -**You will:** -1. Run a `whoami` container alongside Aegis + Envoy -2. Add a cluster and filter chain in Aegis -3. Issue a TLS certificate from the Local CA -4. Add a `/etc/hosts` entry -5. Access `https://whoami.local` from your browser - ---- - -## Prerequisites - -- Docker and Docker Compose installed -- Aegis + Envoy already running and accessible at `http://localhost:8765` -- Admin access to add an `/etc/hosts` entry on your machine - ---- - -## Step 1 — Run the whoami container - -Start `whoami` as a standalone container with a published port: - -```bash -docker run -d --name whoami -p 8081:80 --restart unless-stopped traefik/whoami -``` - -It runs independently — no changes to your existing `docker-compose.yml` needed. - -![Run whoami container](../assets/step1-run-whoami.gif) - ---- - -## Step 2 — Add a cluster in Aegis - -Open the Aegis dashboard → **Gateway → Clusters → Add Cluster**. - -| Field | Value | -|---|---| -| Name | `whoami` | -| Type | `STRICT_DNS` | -| Host | `host.docker.internal` | -| Port | `8081` | -| Connect timeout | `5s` | - -> **Mac / Docker Desktop only:** expand **Advanced parameters** and add `{"dnsLookupFamily":"V4_ONLY"}` — Docker Desktop resolves `host.docker.internal` to IPv6 first, which breaks connections to IPv4-only containers. - -Save — Aegis pushes the cluster to Envoy immediately. - -![Add whoami cluster in Aegis](../assets/step2-add-cluster.gif) - ---- - -## Step 3 — Issue a Local CA certificate - -### 3a — Create a Local CA provider (first time only) - -Go to **Certificates → Signing Providers → Add Provider**, choose **Local CA**, give it a name (e.g. `Local CA`), and save. - -### 3b — Issue the certificate - -Go to **Certificates → Managed Certs → Issue Certificate**: - -| Field | Value | -|---|---| -| Domain | `whoami.local` | -| Provider | `Local CA` | -| Auto-renew | on | - -Click **Issue**. The cert is generated and pushed to Envoy SDS within a second. Note the **secret name** shown (e.g. `tls-whoami-local`). - -![Issue certificate from Local CA](../assets/step3-issue-cert.gif) - ---- - -## Step 4 — Add a filter chain to the HTTPS listener - -Go to **Gateway → Listeners → `https_listener` → Edit**. - -Click **Add Filter Chain** and fill in: - -| Field | Value | -|---|---| -| Domain(s) | `whoami.local` | -| Backend Cluster | `whoami` | -| TLS Secret | `tls-whoami-local` _(or the name shown on the cert page)_ | - -Leave Route Prefix as `/` and click **Add**. Envoy picks up the new filter chain within ~1 second. - -![Add filter chain to HTTPS listener](../assets/step4-add-filter-chain.gif) - ---- - -## Step 5 — Trust the Root CA - -First, download the Root CA certificate. You can do this two ways: - -**Option A — from the UI:** Go to **Certificates → Signing Providers**, click **Download CA Cert** next to your Local CA provider. This downloads `aegis-local-ca.crt` directly from the browser. - -**Option B — via curl:** -```bash -curl -s http://localhost:8765/api/certs/ca -o aegis-local-ca.crt -``` - -Then install it in your OS trust store: - -**macOS:** -```bash -sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain aegis-local-ca.crt -``` - -**Linux:** -```bash -sudo cp aegis-local-ca.crt /usr/local/share/ca-certificates/aegis-local-ca.crt -sudo update-ca-certificates -``` - -**Windows (PowerShell as Administrator):** -```powershell -Import-Certificate -FilePath aegis-local-ca.crt -CertStoreLocation Cert:\LocalMachine\Root -``` - -Restart your browser after installing the CA. - -![Download and trust the Root CA](../assets/step5-trust-ca.gif) - ---- - -## Step 6 — Add an `/etc/hosts` entry - -Map `whoami.local` to the IP address of the machine running Envoy: - -- **Running on your local machine** — use `127.0.0.1` -- **Running on a NAS or remote server** — use that machine's LAN IP (e.g. `192.168.1.100`) - -```bash -# Local machine -echo "127.0.0.1 whoami.local" | sudo tee -a /etc/hosts - -# Or remote host (replace with actual IP) -echo "192.168.1.100 whoami.local" | sudo tee -a /etc/hosts -``` - -On Windows, edit `C:\Windows\System32\drivers\etc\hosts` as Administrator. - -![Add whoami.local to /etc/hosts](../assets/step6-etc-hosts.gif) - ---- - -## Step 7 — Open in browser - -Navigate to **`https://whoami.local`**. - -You should see the whoami response — hostname, IP, headers — served over HTTPS with a valid (locally trusted) certificate and no browser warning. - -![whoami.local trusted in browser](../assets/step7-browser-verify.gif) - ---- - -## What just happened - -``` -Browser → https://whoami.local:443 - │ SNI = whoami.local - ▼ - Envoy (port 10443) - │ filter chain match: whoami.local - │ TLS: cert from Aegis SDS (signed by Local CA) - ▼ - whoami container (port 80) -``` - -Aegis issued the cert from its internal Root CA, pushed it to Envoy via xDS SDS, and Envoy presented it during the TLS handshake. Your browser trusted it because you installed the Root CA. - ---- - -## Cleanup - -To remove the setup: - -1. Delete the managed cert in Aegis → Certificates -2. Remove the filter chain from `https_listener` -3. Delete the `whoami` cluster -4. Remove the `/etc/hosts` line -5. Stop the whoami container: `docker rm -f whoami` - ---- - -## Next - -**[Part 2 → Configure the Gateway with Owl AI](whoami-ai-setup.md)** -You've seen how to set this up manually. In the next tutorial, you hand a single prompt to Owl AI and it configures the cluster, certificate, and filter chain for you — no UI clicks required.