Skip to content

Gateway Architecture

All customer traffic routes through Envoy Gateway. This page covers the decision, how it works at MVP, and the post-MVP auth flow.

§33.1 Decision: Envoy Gateway

Envoy Gateway from day one. All customer traffic routes through it.

Why Envoy Gateway:

  • Standard Gateway API HTTPRoute resources (portable to any implementation)
  • Native JWT/JWKS validation via SecurityPolicy CRD — validates tokens, extracts claims, injects headers (e.g., X-Starform-User-ID)
  • Native ext_authz support — calls external auth service for complex access control
  • Proper multi-tenant Gateway isolation (per specification)
  • Best L7 performance tier

Why NOT others:

Gateway Reason eliminated
Cilium Gateway No auth capabilities (no JWT, no JWKS, no ext_authz, no claim-to-header)
NGINX Gateway Fabric Cannot support multiple Gateways (rejects second Gateway)
Traefik No multi-tenant isolation (violates Gateway API spec), JWT requires commercial license
Kong No multi-tenant isolation (violates Gateway API spec)

§33.2 How It Works

One shared Gateway per cluster. All customer HTTPRoutes attach to it. One DO Load Balancer per Gateway (auto-provisioned by DO CCM).

flowchart LR
  classDef built fill:#3434DC22,stroke:#3434DC,color:#5B5EE8;
  classDef third fill:transparent,stroke:#808080,color:#808080;

  LB["DO LB"]:::third
  ENVOY["Envoy Gateway pods"]:::third
  ROUTE["HTTPRoute<br/>by hostname"]:::third
  SVC["Customer Service"]:::third
  POD["Pod"]:::third

  LB --> ENVOY
  ENVOY --> ROUTE
  ROUTE --> SVC
  SVC --> POD
Diagram — Gateway data path. DO LB → Envoy Gateway pods → HTTPRoute (by hostname) → customer Service → Pod. One shared Gateway per cluster; one DO LB per Gateway (auto-provisioned by DO CCM, §34).

MVP (no auth): Envoy Gateway routes by hostname only.

Post-MVP (auth primitive): Envoy Gateway validates JWT against JWKS endpoint via SecurityPolicy CRD, extracts claims, injects X-Starform-User-ID header. Customer app reads the header — never validates JWTs itself.

§33.3 Future Auth Flow

flowchart TB
  classDef built fill:#3434DC22,stroke:#3434DC,color:#5B5EE8;
  classDef third fill:transparent,stroke:#808080,color:#808080;

  REQ["Request with Bearer token"]:::third
  SP["Envoy Gateway SecurityPolicy"]:::third
  ROUTE["HTTPRoute"]:::third
  POD["Customer Pod<br/>receives request with user ID header"]:::third

  REQ --> SP
  SP -- "validate JWT against JWKS endpoint<br/>extract claims (user_id, roles, …)<br/>inject X-Starform-User-ID header" --> ROUTE
  ROUTE --> POD
Diagram — Future auth flow (post-MVP). A Bearer-token request hits the SecurityPolicy, which validates the JWT against the JWKS endpoint, extracts claims, and injects X-Starform-User-ID; the HTTPRoute then forwards to the customer Pod.

Shuttle creates both the HTTPRoute and the SecurityPolicy from desired state. The auth configuration (JWKS URL, claim mappings) is set by the customer in the Starform dashboard, stored in Starbase, and delivered to Shuttle via desired state.

Cross-references

The LB the Gateway provisions → §34 · HTTPRoute naming (load-bearing for metrics attribution) → §20.2 · desired state that delivers HTTPRoute + SecurityPolicy → §32 · the customer auth primitive is a deferred feature → §39. Canonical map: Canonical Sources.