ZDR via structured field-override (ai.overrides); CEL only for drop_params

Date: 2026-06-07 Status: Accepted Decision: hl-0eb Deciders: Sean, Claude

Context

ADR hl-env chose CEL request transformations for BOTH ZDR injection (provider.zdr=true) and drop_params (strip encoding_format on Ollama embeddings) under standalone mode. The CRD model has a dedicated AgentgatewayBackend.spec.policies.ai.overrides field (FieldDefault, a structured field-merge) that is the direct analog for static body-field injection, making CEL for ZDR unnecessary and semantically misplaced.

Decision

ZDR is implemented via AgentgatewayBackend.spec.policies.ai.overrides (structured FieldDefault) on the ZDR backend; drop_params (encoding_format removal) remains a CEL body transformation (traffic.transformation.request.body) on the embeddings route because a field-default cannot express deletion. Amends/supersedes hl-env.

Rationale

• ai.overrides is the CRD-spec-correct home for static body-field injection; CEL for a value with a dedicated structured field is misplaced.\n- CEL is reserved for the removal case (drop_params) that overrides genuinely cannot express.\n- The end-to-end guarantee (server-side, route-bound, client-bypass-proof) is preserved; only the ZDR mechanism changes.

Alternatives Considered

• CEL for both, carrying hl-env forward unchanged (rejected): semantically wrong home for a static field in the CRD model.\n- ai.overrides for ZDR + CEL for drop_params (chosen): each mechanism used as designed.

Consequences

• Positive: ZDR config idiomatic + readable in the CRD model; clean separation (structured field for injection, CEL for deletion).\n- Negative: two distinct mechanisms for related transforms; both must be validated with kubectl —dry-run=server against the alpha CRD schema.\n- Neutral: the ZDR + drop_params guarantee is unchanged from hl-env.

References

• Supersedes: hl-env