Gateway

The Flux gateway is the public ingress for v2 shared Service URLs. It resolves the hostname to a tenant, validates the caller’s project JWT, and issues a short-lived bridge JWT consumed by PostgREST.

What you will learn

  • Why “proxy” understates the gateway
  • What verification implies for trust
  • Relationship to rate limiting and Redis (cache-only)

The idea

The gateway is a security control, not passive forwarding. A mistaken tenant_id or role in an issued JWT is a cross-tenant data risk; mitigations include strict resolution against the catalog, short TTLs, and tests around host parsing.

Redis (when used) is for cache and telemetry—not authoritative for correctness.

How it works

At a high level:

  1. TLS terminates (or upstream proxy terminates) on the public name. For canonical v2 hosts, the control plane publishes an exact-host router from the catalog so Traefik can discover and renew its ACME certificate without a gateway restart.
  2. Gateway maps host → tenant record.
  3. External JWT verified per project configuration.
  4. Bridge JWT minted with Postgres role and claims PostgREST expects.

The generated Traefik file is operational state, not source configuration. Startup and every pooled create/delete or v2→v1 cutover reconcile the complete document from the authoritative project catalog, using an atomic replace so Traefik never observes a partial write.

Dashboard mesh probes may use FLUX_TENANT_PROBE_GATEWAY_URL (tenant Host on the gateway base) so flux-web does not depend on public DNS. That probe is separate from the process checks below.

Health

GET /health is liveness: HTTP 200 {"status":"ok"}, no database or Redis call, no project JWT. GET /health/deep is readiness: SELECT 1 on FLUX_SYSTEM_DATABASE_URL, HTTP 503 when that ping fails. The deep body also reports Redis (up, down, or null when REDIS_URL is unset); Redis does not change the status code. Neither route checks PostgREST or tenant JWT verification. Operator contract: docs/OPERATOR-GATEWAY-HEALTH.md.

Example

Debugging production traffic often starts at gateway logs (reject reasons) before Postgres logs—401s usually never reach the database.

Next steps