Skip to content
fzymgc-house Cluster Docs

Select the ZDR lane via two HTTPRoutes + Gateway API header-count tiebreaker

Date: 2026-06-20 Status: Accepted Decision: hl-d5lu Deciders: Sean Brandt

Context

Section titled “Context”

The generic and ZDR lanes share a single host (openrouter-gw.fzymgc.house) and an identical PathPrefix "/" match. A mechanism is needed to steer ZDR-requesting clients to the ZDR backend without path differentiation (which would break the transparent 1:1 base-URL contract). Gateway API resolves a path-tie ambiguity by choosing the rule/route with more matching headers.

Decision

Section titled “Decision”

Deploy two separate HTTPRoutes on the same host and PathPrefix "/"; the ZDR route adds an x-agentgateway-backend: openrouter-generic-zdr header match so Gateway API’s header-count tiebreaker selects it over the generic route when the header is present.

Rationale

Section titled “Rationale”
  • Mirrors the proven llm-chat / llm-chat-zdr pattern already running in-cluster.
  • Clients toggle ZDR by adding a single request header — the base URL is identical for both lanes.
  • Separate HTTPRoutes allow AgentgatewayPolicy to target each independently, preventing the ZDR header from bypassing the virtual-key gate.

Alternatives Considered

Section titled “Alternatives Considered”
  • Two separate HTTPRoutes; ZDR route adds a header match (chosen): deterministic header-count precedence; proven in-cluster by the llm-chat/llm-chat-zdr pair; each route independently policy-targetable. Cost: requires live verification that the tiebreaker applies the same way on a / catch-all path as on a specific path.
  • Single HTTPRoute with two same-path rules (rejected): one resource, but the second rule is ambiguous/unreachable under naive first-match, and the header tiebreaker is not reliably applied within a single route’s rule list.
  • Path-differentiated ZDR lane (e.g. /zdr/api/v1/*) (rejected): unambiguous path-based selection, but breaks the 1:1 base-URL contract — clients would need a different base URL for ZDR vs non-ZDR, preventing a transparent per-request toggle.

Consequences

Section titled “Consequences”
  • Positive: ZDR is client-selectable per-request with no base-URL change; each route is independently targetable for policy attachment.
  • Negative: relies on the Gateway API header-count tiebreaker on a / wildcard path — must be live-verified before ZDR is trusted.
  • Neutral: the pattern is additive; llm-gw routes are unchanged.