# 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.

- Canonical URL: https://webofmike.com/kgateway-admission-validation/
- Author: Mike Moore (https://webofmike.com/about/)
- Published: 2026-11-17
- Last modified: 2026-11-17
- Tags: AI Gateways, Kubernetes, Platform Engineering, DevOps
- Cite as: Mike Moore, "kgateway v2.5.1 Rejects Bad Config at kubectl apply", Web of Mike (webofmike.com), 2026-11-17. https://webofmike.com/kgateway-admission-validation/


kgateway [v2.5.1](https://github.com/kgateway-dev/kgateway/releases/tag/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](https://github.com/kgateway-dev/kgateway/pull/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](https://github.com/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:

```bash
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'])"
```

```json
{
  "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`:

```bash
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:

```bash
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`:

```bash
kubectl apply -f manifests/04-good-backendconfigpolicy.yaml
kubectl -n demo get backendconfigpolicy good-healthcheck -o jsonpath='{.status}'
```

```json
{"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:

```bash
kubectl -n demo port-forward svc/demo-gw 18080:80 &
curl -s http://localhost:18080/get -H "Host: demo"
```

```json
{
  "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](https://github.com/kgateway-dev/kgateway/pull/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

```bash
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](https://github.com/themsquared/kgateway-admission-validation-demo). Note the [Gateway API bump to v1.7.0](https://github.com/kgateway-dev/kgateway/releases/tag/v2.5.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](/how-to-choose-an-ai-agent-gateway/), which covers agentgateway, kgateway's AI-routing counterpart for model traffic.

