kgateway v2.5.1 Rejects Bad Config at kubectl apply

kgateway v2.5.1 adds CRD admission bounds, so a bad health check timeout or backend port now fails at kubectl apply instead of deep in the control plane.

kgateway v2.5.1 shipped on 2026-11-06 with a change that is easy to miss in a changelog and annoying to find out about the hard way: PR #14992 adds explicit minimum and maximum bounds to a batch of CRD fields across BackendConfigPolicy, Backend, ListenerPolicy, and GatewayExtension. Values that Envoy itself would refuse now get rejected by the Kubernetes API server at kubectl apply, instead of being accepted and failing somewhere deeper in the control plane.

(kgateway is a CNCF Gateway API implementation built on Envoy, used as a general Kubernetes ingress and API gateway. It’s a separate project from agentgateway, Solo’s gateway built specifically for AI agent and MCP traffic. This post is about kgateway, not agentgateway.)

I built a small kind cluster to see exactly what that looks like. The demo is in themsquared/kgateway-admission-validation-demo: two manifests the API server now refuses outright, and a working gateway built from the ones that pass.

What admission validation was missing before

kgateway’s CRDs have always had an OpenAPI schema, so the API server already checked type: a string where a string belongs, an integer where an integer belongs. What the schema mostly didn’t check was range. A BackendConfigPolicy with healthCheck.timeout: 0s is the right type, a valid duration string, and completely useless, because Envoy needs a positive timeout to actually time anything out. Before v2.5.1, that value passed CRD admission, got picked up by the kgateway controller, and only became a problem once it reached Envoy’s own config validation, with nothing about it visible in the kubectl apply exit code.

PR #14992 moves that check to the boundary. The same invalid value now fails at the API server, with the specific field and the specific reason.

Watching the API server reject it

The CRD schema change shows up as a CEL rule on the field itself:

kubectl get crd backendconfigpolicies.gateway.kgateway.dev -o json | \
  python3 -c "import json,sys; print(json.load(sys.stdin)['spec']['versions'][0]['schema']['openAPIV3Schema']['properties']['spec']['properties']['healthCheck']['properties']['timeout'])"
{
  "description": "Timeout is time to wait for a health check response...",
  "maxLength": 32,
  "type": "string",
  "x-kubernetes-validations": [
    {"message": "invalid duration value", "rule": "matches(self, '^([0-9]{1,5}(h|m|s|ms)){1,4}$')"},
    {"message": "must be at least 1ms", "rule": "duration(self) >= duration('1ms')"}
  ]
}

Apply a BackendConfigPolicy with healthCheck.timeout: 0s:

kubectl apply -f manifests/01-bad-backendconfigpolicy.yaml
The BackendConfigPolicy "bad-healthcheck" is invalid: spec.healthCheck.timeout: Invalid value: "0s": must be at least 1ms

The same pattern applies to a Backend with a static host port outside the valid range:

kubectl apply -f manifests/05-bad-backend-port.yaml
The Backend "bad-static-backend" is invalid: spec.static.hosts[0].port: Invalid value: 70000: port must be between 1 and 65535

Both of these are rejected before the kgateway controller ever sees the object. There’s no reconcile loop to get stuck, no status condition to go read, no proxy to restart and discover is still broken. The error comes back synchronously, on the same kubectl apply that created the problem.

The valid version, end to end

The same policy with a real timeout attaches and works. I stood up an httpbin backend behind a Gateway and HTTPRoute, then attached a BackendConfigPolicy with healthCheck.timeout: 2s:

kubectl apply -f manifests/04-good-backendconfigpolicy.yaml
kubectl -n demo get backendconfigpolicy good-healthcheck -o jsonpath='{.status}'
{"ancestors":[{"ancestorRef":{"group":"","kind":"Service","name":"httpbin","namespace":"demo"},
  "conditions":[{"reason":"Valid","status":"True","type":"Accepted"},
                {"reason":"Attached","status":"True","type":"Attached"}],
  "controllerName":"kgateway.dev/kgateway"}]}

And traffic through the gateway proves the whole chain, API server, controller, and Envoy, agrees on the config:

kubectl -n demo port-forward svc/demo-gw 18080:80 &
curl -s http://localhost:18080/get -H "Host: demo"
{
  "headers": {"Host": "demo", "X-Envoy-Expected-Rq-Timeout-Ms": "15000"},
  "origin": "10.244.0.7",
  "url": "http://demo/get"
}

What else got tightened in the same release

Two examples are enough to show the pattern, but the full list in PR #14992 is worth knowing if you run kgateway: BackendConfigPolicy connect timeouts and health check intervals of 0s, a DNS refreshRate of 1ms or less, maxHeadersCount of 0, a leastRequest.choiceCount below 2, ring hash sizes outside 1 to 8,388,608; Backend AWS EC2 ports above 65535; ListenerPolicy local reply status codes below 200 and gRPC retry base intervals of 0s; GatewayExtension ext-auth statusOnError codes Envoy doesn’t define, and ext-proc message timeouts above one hour.

If you already have a resource with one of these values, it keeps running. The grandfather clause only blocks new admission: you can’t create a fresh resource with the bad value, and you can’t re-apply the existing one unchanged, since an update is its own admission check against the current schema. Worth finding out in a staging cluster before a routine config sync fails in CI for a value that’s been sitting in a manifest for months.

Running it yourself

kind create cluster --name kgateway-admission-demo
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.7.0/standard-install.yaml
helm install kgateway-crds oci://cr.kgateway.dev/kgateway-dev/charts/kgateway-crds \
  --version v2.5.1 --namespace kgateway-system --create-namespace
helm install kgateway oci://cr.kgateway.dev/kgateway-dev/charts/kgateway \
  --version v2.5.1 --namespace kgateway-system --create-namespace

Full manifests and the exact sequence are in the repo. Note the Gateway API bump to v1.7.0 that shipped in v2.5.0, the release before this one: installing against an older Gateway API CRD set will not reproduce this.

For the agent-facing side of the gateway layer rather than general Gateway API reliability, see how to choose an AI agent gateway, which covers agentgateway, kgateway’s AI-routing counterpart for model traffic.

Frequently asked questions

What changed in kgateway v2.5.1's CRD validation?

PR #14992 added explicit minimum and maximum bounds, enforced with CEL x-kubernetes-validations rules, to several BackendConfigPolicy, Backend, ListenerPolicy, and GatewayExtension fields. Values Envoy itself would reject, like a health check timeout of 0s or a backend port outside 1-65535, now fail Kubernetes API server validation at kubectl apply instead of passing admission and failing later in the control plane.

Does kgateway v2.5.1 break existing resources that already have out-of-range values?

No. Existing objects that already hold a now-invalid value are left alone and keep working. The new bounds only apply going forward: you cannot create a new resource with that value, and you cannot re-apply the same resource with that value unchanged, since Kubernetes treats an update as a new admission check against the current schema.

How do I check if my kgateway BackendConfigPolicy will pass admission in v2.5.1?

Run kubectl apply against the resource. If a field like healthCheck.timeout, dns.refreshRate, or a static backend’s port is out of range, the API server rejects the request immediately and names the exact field and the rule it violated, for example ‘must be at least 1ms’. There is no separate dry-run step needed; admission validation runs on every apply.

What is the difference between kgateway and agentgateway?

kgateway is a CNCF Gateway API implementation built on Envoy, used as a general Kubernetes ingress and API gateway. agentgateway is Solo.io’s separate gateway built specifically for AI agent and MCP traffic. They are different projects; this post is about kgateway’s CRD admission validation, not agentgateway.

Disagree or have a war story? Reply on X