From d7f33ef6e385f32653f91b5a1d927b52b8ecbf2c Mon Sep 17 00:00:00 2001 From: bmertens-datum Date: Wed, 3 Jun 2026 11:44:57 -0400 Subject: [PATCH] Add expanded AI Edge and datumctl how-to guides MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds 8 new guides covering HTTPProxy filters, WAF configuration, DNS setup, and datumctl resource workflows. New guides: - ai-edge/proxy-waf.mdx — HTTPProxy and WAF capabilities reference - ai-edge/dns-setup.mdx — DNS zone, ALIAS, and CNAME setup for AI Edge - ai-edge/path-routing.mdx — Path-based routing with HTTPProxy - ai-edge/host-header-override.mdx — Host header rewrite via RequestHeaderModifier - ai-edge/https-redirect.mdx — HTTP to HTTPS redirect via RequestRedirect - ai-edge/url-rewrite.mdx — Path and hostname rewriting via URLRewrite - ai-edge/waf-configuration.mdx — WAF setup, paranoia levels, enforce workflow - datumctl/working-with-resources.mdx — Core commands, declarative model, namespaces All guides validated against live datumctl explain output. Existing drafts were cleaned up for style consistency, cross-platform coverage (Windows PowerShell + macOS/Linux), generic placeholder values, and uniform section structure (Prerequisites, Steps, Verification, Cleanup, Troubleshooting, Summary). Co-Authored-By: Claude Sonnet 4.6 --- ai-edge/dns-setup.mdx | 280 ++++++++++++++++++++++++ ai-edge/host-header-override.mdx | 184 ++++++++++++++++ ai-edge/https-redirect.mdx | 174 +++++++++++++++ ai-edge/path-routing.mdx | 195 +++++++++++++++++ ai-edge/proxy-waf.mdx | 148 +++++++++++++ ai-edge/url-rewrite.mdx | 245 +++++++++++++++++++++ ai-edge/waf-configuration.mdx | 322 ++++++++++++++++++++++++++++ datumctl/working-with-resources.mdx | 77 +++++++ 8 files changed, 1625 insertions(+) create mode 100644 ai-edge/dns-setup.mdx create mode 100644 ai-edge/host-header-override.mdx create mode 100644 ai-edge/https-redirect.mdx create mode 100644 ai-edge/path-routing.mdx create mode 100644 ai-edge/proxy-waf.mdx create mode 100644 ai-edge/url-rewrite.mdx create mode 100644 ai-edge/waf-configuration.mdx create mode 100644 datumctl/working-with-resources.mdx diff --git a/ai-edge/dns-setup.mdx b/ai-edge/dns-setup.mdx new file mode 100644 index 0000000..696642e --- /dev/null +++ b/ai-edge/dns-setup.mdx @@ -0,0 +1,280 @@ +--- +title: "DNS Setup for AI Edge" +description: "Create a DNS zone, apex ALIAS record, and subdomain CNAME to point a domain at a Datum AI Edge endpoint." +--- + +This guide prepares a domain for use with a Datum AI Edge by creating a DNS zone, an apex ALIAS record, and a subdomain CNAME — all pointing at the AI Edge endpoint. + + +This guide assumes your domain is already delegated to Datum nameservers. See [DNS](/domain-dns/dns) for nameserver details and ALIAS record behavior. + + +--- + +## Prerequisites + +- `datumctl` installed and authenticated +- A valid **Project** +- Domain delegated to Datum nameservers + +--- + +## Configuration Steps + +### Step 1: Set Variables + +The `TARGET` value is your AI Edge endpoint hostname. Find it in the Datum portal under your AI Edge's generated hostname, or via: + +```bash +datumctl get httpproxy --namespace default -o yaml +``` + +#### Windows (PowerShell) + +```powershell +$PROJECT = "your-project-id" +$NAMESPACE = "default" +$ZONE = "your-zone-name" +$DOMAIN = "your-domain.example.com" +$TARGET = "your-endpoint.datumproxy.net." +``` + +#### macOS / Linux + +```bash +PROJECT="your-project-id" +NAMESPACE="default" +ZONE="your-zone-name" +DOMAIN="your-domain.example.com" +TARGET="your-endpoint.datumproxy.net." +``` + + +`TARGET` must include a trailing dot. Without it, the value will be treated as a relative name and DNS resolution will fail. + + +--- + +### Step 2: Create the DNS Zone + +#### Windows (PowerShell) + +```powershell +@" +apiVersion: dns.networking.miloapis.com/v1alpha1 +kind: DNSZone +metadata: + name: $ZONE + namespace: $NAMESPACE +spec: + dnsZoneClassName: datum-external-global-dns + domainName: $DOMAIN +"@ | datumctl apply -f - --project $PROJECT --validate=false +``` + +#### macOS / Linux + +```bash +cat < +`--validate=false` disables client-side schema validation. It is required here because `datumctl` does not bundle schemas for DNS API types locally. + + +Verify the zone is accepted and programmed: + +```bash +datumctl get dnszones --project $PROJECT --namespace $NAMESPACE +``` + +Wait until both `ACCEPTED` and `PROGRAMMED` show `True` before proceeding. + +--- + +### Step 3: Create the Apex ALIAS Record + +Points the root domain (`@`) at the AI Edge endpoint. + +#### Windows (PowerShell) + +```powershell +@" +apiVersion: dns.networking.miloapis.com/v1alpha1 +kind: DNSRecordSet +metadata: + name: ${ZONE}-apex + namespace: $NAMESPACE +spec: + dnsZoneRef: + name: $ZONE + recordType: ALIAS + records: + - name: "@" + ttl: 300 + alias: + content: $TARGET +"@ | datumctl apply -f - --project $PROJECT --validate=false +``` + +#### macOS / Linux + +```bash +cat < +AI Edge enforces HTTPS by default. This guide applies when you have disabled that enforcement, or when you need a custom redirect configuration — for example, redirecting from a specific path or returning a `302` instead of the default `301`. + + +--- + +## Overview + +A `RequestRedirect` filter responds to the client with a redirect response directly — no backend is reached. The AI Edge handles the redirect at the proxy layer. + +At a high level, this setup: + +1. Matches all incoming requests on a hostname +2. Returns a `301 Moved Permanently` redirect to the same URL using `https` + +--- + +## Prerequisites + +- `datumctl` installed and authenticated +- A valid **Project** +- An existing `HTTPProxy` hostname, or create a new one with this guide + +--- + +## Configuration Steps + +### Step 1: Set Variables + +#### Windows (PowerShell) + +```powershell +$PROJECT = "your-project-id" +$NAMESPACE = "default" +$PROXY_NAME = "https-redirect-demo" +$HOSTNAME = "your-app.example.com" +``` + +#### macOS / Linux + +```bash +PROJECT="your-project-id" +NAMESPACE="default" +PROXY_NAME="https-redirect-demo" +HOSTNAME="your-app.example.com" +``` + +--- + +### Step 2: Apply the Redirect Configuration + +The `RequestRedirect` filter requires `type: RequestRedirect`. No backend is needed — the redirect is returned immediately by the proxy. + +#### Windows (PowerShell) + +```powershell +@" +apiVersion: networking.datumapis.com/v1alpha +kind: HTTPProxy +metadata: + name: $PROXY_NAME +spec: + hostnames: + - $HOSTNAME + rules: + - name: https-redirect + matches: + - path: + type: PathPrefix + value: / + filters: + - type: RequestRedirect + requestRedirect: + scheme: https + statusCode: 301 +"@ | datumctl apply --project $PROJECT --namespace $NAMESPACE -f - +``` + +#### macOS / Linux + +```bash +cat < +Each rule currently supports only a single backend. Multiple backends per rule are not yet supported. + + +#### Windows (PowerShell) + +```powershell +@" +apiVersion: networking.datumapis.com/v1alpha +kind: HTTPProxy +metadata: + name: $PROXY_NAME +spec: + hostnames: + - $HOSTNAME + rules: + - name: login-exact + matches: + - path: + type: Exact + value: /login + backends: + - endpoint: https://auth-origin.example + + - name: catch-all + matches: + - path: + type: PathPrefix + value: / + backends: + - endpoint: https://web-origin.example +"@ | datumctl apply --project $PROJECT --namespace $NAMESPACE -f - +``` + +#### macOS / Linux + +```bash +cat < --namespace default -o yaml +``` + +### Feature Reference + +```text +HTTPProxy + ├── metadata + │ ├── name + │ ├── namespace + │ └── annotations + │ + └── spec + ├── hostnames[] + │ + └── rules[] + ├── name + │ + ├── matches[] + │ ├── path + │ │ ├── type (Exact | PathPrefix | RegularExpression) + │ │ └── value + │ ├── headers[] + │ │ ├── name + │ │ ├── type (Exact | RegularExpression) + │ │ └── value + │ ├── queryParams[] + │ └── method (GET | POST | PUT | ...) + │ + ├── filters[] (rule-level) + │ ├── RequestRedirect + │ ├── RequestHeaderModifier + │ ├── ResponseHeaderModifier + │ ├── RequestMirror + │ ├── URLRewrite + │ ├── CORS + │ └── ExtensionRef + │ + └── backends[] + ├── endpoint + ├── connector + ├── tls + └── filters[] (backend-level) +``` + + +Each rule currently supports a single backend. Multiple backends per rule are not yet supported. + + +--- + +## TrafficProtectionPolicy (WAF) + +The `TrafficProtectionPolicy` resource provides application-layer security using the OWASP Core Rule Set. It attaches to an `HTTPProxy` using `targetRefs` and can target the entire proxy or a specific named rule via `sectionName`. + +### Inspect the Schema + +```bash +datumctl explain trafficprotectionpolicy --recursive +``` + +### List and Inspect WAF Policies + +```bash +# List all WAF policies +datumctl get trafficprotectionpolicies --namespace default + +# View a specific policy +datumctl get trafficprotectionpolicy --namespace default -o yaml +``` + +### Feature Reference + +```text +TrafficProtectionPolicy + ├── metadata + │ + └── spec + ├── mode (Observe | Enforce | Disabled) + ├── samplingPercentage + ├── ruleSets[] + │ └── OWASPCoreRuleSet + │ ├── paranoiaLevels + │ │ ├── detection + │ │ └── blocking + │ ├── scoreThresholds + │ │ ├── inbound + │ │ └── outbound + │ └── ruleExclusions + │ ├── ids + │ ├── idRanges + │ └── tags + │ + └── targetRefs[] + ├── group + ├── kind + ├── name + └── sectionName (optional — target a specific rule) +``` + +**Mode values:** +- `Observe` *(default)* — Logs rule matches without blocking traffic. Use this to evaluate impact before enforcing. +- `Enforce` — Blocks requests that exceed the score threshold. +- `Disabled` — WAF is inactive. + +**Paranoia levels** control how aggressively rules are applied. Higher levels catch more threats but increase false-positive risk. Separate levels can be set for detection (logging) and blocking. + +**`samplingPercentage`** controls what fraction of traffic is evaluated by the WAF. Useful for gradual rollout or high-throughput environments. + +--- + +## Next Steps + +- [Path-Based Routing](/ai-edge/path-routing) — Route requests to different backends by URL path +- [HTTP Basic Authentication](/ai-edge/basic-auth) — Add username/password protection to a route +- [OIDC with Google](/ai-edge/oidc-google) — Protect a route with Google sign-in +- [OIDC with Auth0](/ai-edge/oidc-auth0) — OIDC with email-based allow-lists via Auth0 diff --git a/ai-edge/url-rewrite.mdx b/ai-edge/url-rewrite.mdx new file mode 100644 index 0000000..9143789 --- /dev/null +++ b/ai-edge/url-rewrite.mdx @@ -0,0 +1,245 @@ +--- +title: "URL Rewrite with HTTPProxy" +description: "Rewrite the path or hostname on upstream requests using a URLRewrite filter on a Datum HTTPProxy." +--- + +This guide shows how to rewrite the URL path before a request is forwarded to an upstream backend using a Datum `HTTPProxy`. + +URL rewriting is useful when: + +- Your public API path structure differs from your backend's internal paths +- You want to strip a path prefix before forwarding (e.g., `/api/v1/users` → `/users`) +- You need to replace the full path for a specific route +- You need to rewrite the hostname the backend sees (separate from `Host` header modification) + +--- + +## Overview + +The `URLRewrite` filter modifies the path and/or hostname of the forwarded request. Unlike `RequestHeaderModifier`, which sets arbitrary headers, `URLRewrite` is purpose-built for path and authority rewriting and is the recommended approach for path manipulation. + +At a high level, this setup: + +1. Matches requests on a path prefix +2. Rewrites the path before forwarding to the backend +3. The client sees no change to the URL + +--- + +## Prerequisites + +- `datumctl` installed and authenticated +- A valid **Project** + +--- + +## Configuration Steps + +### Step 1: Set Variables + +#### Windows (PowerShell) + +```powershell +$PROJECT = "your-project-id" +$NAMESPACE = "default" +$PROXY_NAME = "url-rewrite-demo" +$HOSTNAME = "your-app.example.com" +``` + +#### macOS / Linux + +```bash +PROJECT="your-project-id" +NAMESPACE="default" +PROXY_NAME="url-rewrite-demo" +HOSTNAME="your-app.example.com" +``` + +--- + +### Step 2: Apply URL Rewrite Configuration + +This example strips the `/api` prefix. Requests to `/api/users` are forwarded to the backend as `/users`. + +`ReplacePrefixMatch` must be paired with a `PathPrefix` match on the same prefix — mixing match types will cause the route to be rejected. + +#### Windows (PowerShell) + +```powershell +@" +apiVersion: networking.datumapis.com/v1alpha +kind: HTTPProxy +metadata: + name: $PROXY_NAME +spec: + hostnames: + - $HOSTNAME + rules: + - name: strip-api-prefix + matches: + - path: + type: PathPrefix + value: /api + filters: + - type: URLRewrite + urlRewrite: + path: + type: ReplacePrefixMatch + replacePrefixMatch: / + backends: + - endpoint: https://api-backend.example.com +"@ | datumctl apply --project $PROJECT --namespace $NAMESPACE -f - +``` + +#### macOS / Linux + +```bash +cat < +WAF policies default to `Observe` mode when `mode` is not specified. Always start in `Observe` mode before enforcing — this prevents unexpected blocking of legitimate traffic. + + +--- + +## Prerequisites + +- `datumctl` installed and authenticated +- A valid **Project** +- An existing `HTTPProxy` to attach the policy to + +Verify your proxy exists: + +```bash +datumctl get httpproxy --project $PROJECT --namespace $NAMESPACE +``` + +--- + +## Configuration Steps + +### Step 1: Set Variables + +#### Windows (PowerShell) + +```powershell +$PROJECT = "your-project-id" +$NAMESPACE = "default" +$PROXY_NAME = "your-proxy-name" +$WAF_NAME = "${PROXY_NAME}-waf" +``` + +#### macOS / Linux + +```bash +PROJECT="your-project-id" +NAMESPACE="default" +PROXY_NAME="your-proxy-name" +WAF_NAME="${PROXY_NAME}-waf" +``` + +--- + +### Step 2: Apply WAF in Observe Mode + +Start by attaching the WAF in `Observe` mode. Violations are logged but traffic is not blocked. + +#### Windows (PowerShell) + +```powershell +@" +apiVersion: networking.datumapis.com/v1alpha +kind: TrafficProtectionPolicy +metadata: + name: $WAF_NAME + namespace: $NAMESPACE +spec: + mode: Observe + ruleSets: + - type: OWASPCoreRuleSet + owaspCoreRuleSet: + paranoiaLevels: + detection: 2 + blocking: 1 + scoreThresholds: + inbound: 5 + outbound: 4 + targetRefs: + - group: networking.datumapis.com + kind: HTTPProxy + name: $PROXY_NAME +"@ | datumctl apply --project $PROJECT --namespace $NAMESPACE -f - +``` + +#### macOS / Linux + +```bash +cat <