Routing: how a developer's traffic reaches their copies

Nazeel runs one router per Baseline, next to the application's services. Every in-cluster Service name (ledger, payments-api) points at the router; the real pods sit behind <name>-baseline. An Environment's copies live in their own namespace and are reached only through the router.

The routing key

Requests carry the environment name in X-Nazeel-Env: <environment>. The router also accepts and sets the W3C baggage member nazeel-env=<environment>, so services that already propagate OpenTelemetry baggage need no change.

Your services must forward X-Nazeel-Env (or baggage) on every outgoing call, the same way they forward trace context. Without it, a call from a baseline service to a service the environment overrides lands on the baseline copy.

What the router does with a request

Arrives on	Environment taken from	Client routing headers	Goes to
Service port (in-cluster)	`X-Nazeel-Env`, else `baggage`	trusted	copy if the environment overrides the service, else `<name>-baseline`
Edge port (from the Ingress)	Host header only	discarded	the Baseline `entrypoint` service, copy or baseline as above

Unknown environment names fall open to the baseline. Each occurrence is counted in nazeel_router_unknown_env_total and recorded as an UnknownEnvironment Event on the Baseline, so a developer whose environment was deleted mid-session is visible.

Ports declared protocol: tcp and services marked shared: true never pass through the router. They always reach the baseline pods directly.

Preview URLs and TLS

With --ingress-domain=<domain> the operator publishes:

<app>.<domain> for the baseline
<env>--<app>.<domain> for every environment

Both are exact-host Ingress objects in the application namespace, backed by the router's edge Service. Set --ingress-class if the cluster has more than one ingress controller.

TLS requires a wildcard certificate for *.<domain>. Create a TLS Secret holding it in each application namespace and pass its name through --ingress-tls-secret. Until you do, preview URLs are served over plain HTTP and each Baseline shows the condition IngressTLS=False with reason NoTLSSecret. Nazeel does not integrate with cert-manager or ACME; the product never makes outbound network calls.

Preview URLs are not yet authenticated. SSO in front of them arrives with the API component.

Diagnostics

Response header X-Nazeel-Upstream: copy|baseline says which instance answered.
Baseline.status.routes lists the router listener port for every service port.
Baseline.status.conditions[RoutingReady] reports RouterStarting, RouterSwitching (brief resets possible) or RouterReady.
Metrics on the router Service port 9090: nazeel_router_requests_total, nazeel_router_request_duration_seconds, nazeel_router_unknown_env_total, nazeel_router_edge_headers_dropped_total.