Deploy agentgateway via k8s-native Gateway-API/CRD control plane (supersedes standalone)
Date: 2026-06-07 Status: Accepted Decision: hl-m3c Deciders: Sean, Claude
Context
Section titled “Context”agentgateway was deployed standalone (local config.yaml; ADR hl-jd4) when scope was one LLM proxy + one MCP upstream (engram). The MCP gateway now fronts six servers with mixed per-server client auth (engram OAuth, SaaS virtual-key, deepwiki none). Standalone expresses client auth at the listener level (one mode per listener) with no native path routing, so per-route/per-server auth needs an awkward verbose-config rewrite. agentgateway’s local and XDS/control-plane config forms map to the SAME shared internal representation, so the CRD model is feature-complete with standalone by design.
Decision
Section titled “Decision”Deploy agentgateway via its self-contained Helm controller (agentgateway-crds + agentgateway charts, GatewayClass agentgateway) driven by Gateway-API + agentgateway.dev/v1alpha1 CRDs (Gateway/HTTPRoute/AgentgatewayBackend/AgentgatewayPolicy), replacing the standalone Deployment/ConfigMap. Supersedes hl-jd4.
Rationale
Section titled “Rationale”- Six MCP upstreams with mixed per-server auth is the requirement standalone cannot express natively.\n- CRD/XDS maps to the same IR as local config: parity is by design.\n- Per-route independence (one HTTPRoute + Policy per server) matches the operator need.\n- agentgateway controller is self-contained; no kgateway dependency.
Alternatives Considered
Section titled “Alternatives Considered”- Continue standalone (rejected): per-listener auth, no path routing, monolithic config blob.\n- k8s-native CRD control plane (chosen): native per-route auth + path routing; additive new upstreams.
Consequences
Section titled “Consequences”- Positive: native per-server path routing + auth choice; gateway config as discrete GitOps CRDs; additive upstream onboarding.\n- Negative: alpha controller (chart 0.0.2) immaturity (mitigated by digest pinning); XDS cannot fetch JWKS URLs so the Authentik JWKS host needs a backendRef (K14); direct cutover accepts a broken interim.\n- Neutral: two ArgoCD apps (controller vs gateway); Authentik + TLS cert unchanged.
References
Section titled “References”- Supersedes: hl-jd4