[kristin-kronstain-brown]

Summary

kgateway-dev/kgateway#14767 (merged to main through #14698, first shipped in v2.5.0-beta.3) limits how long the control plane delays a proxy's xDS configuration while referenced clusters are not ready. This PR adds a "Limit xDS publication delays" section to the advanced install page, after the xDS scoping section and under the same version gate (2.5 and later):

• What the delay is, when it applies (a proxy's first configuration, and a route change to a cluster that is not ready), and that a 503 is returned until the cluster is ready.
• KGW_PER_CLIENT_PUBLISH_BUDGET (default 15s) and KGW_PER_CLIENT_WARM_WITHHOLD_BOUND (default 10m), set through controller.extraEnv, as two steps that end with helm upgrade. The table rows cover what 0 does, that the budget is not the total time until the proxy is ready, and that a delayed proxy gets no updates, including certificate rotations.
• The kgateway_xds_snapshot_perclient_* metrics, all six mode values of bounded_publishes_total, how to query the metrics, and example output.
• A link from the referenceAhead row of the scoping section, because the budget also ends that hold.

The inconsistent_snapshots_total metric is left out on purpose. It has no labels and only counts when KGW_XDS_SNAPSHOT_CONSISTENCY_CHECK is on, which is meant for tests and CI.

Sources

• Settings: api/settings/settings.go and docs/guides/xds-publication-settings.md in kgateway.
• Metric names, types, labels, and label values: pkg/kgateway/proxy_syncer/perclient_publication_metrics.go and devel/architecture/metrics.md.
• Startup probe default (60 probes, 1 second apart): pkg/deployer/gateway_parameters.go.

Testing

On a kind cluster with kgateway v2.5.0 and Gateway API v1.7.0:

• The helm upgrade command from the page, with KGW_PER_CLIENT_PUBLISH_BUDGET: "20s" in controller.extraEnv, sets the variable on the controller. The kgateway Service exposes metrics on port 9092.
• The metrics command from the page returns nothing on a fresh install. After a controller restart, it returns kgateway_xds_snapshot_perclient_defers_total{...,reason="missing_endpoints"} 1, and the controller logs withholding first publish until referenced clusters are ready or the budget expires.
• A route to a Service with no ready endpoints returns 503 right away and does not count as a delay. This matches the source: empty endpoints are a ready state.

Not tested: a cluster that never becomes ready, so bounded_publishes_total, withheld_clients, and the first-publish budget expired warning were not seen in a cluster. The kgateway e2e tests do not cover this case either.

The site builds with Hugo. The section renders on main and latest, and not on the 2.1.x to 2.4.x pages.

Question for reviewers

Should these settings be documented for users at all, or kept in the contributor guide? The Helm chart has dedicated values for xDS scoping but none for these two settings. If they are meant to stay internal, I can cut the section down to the behavior and the metrics.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying kgateway-io with    Cloudflare Pages

Latest commit:	adafcec
Status:	⚡️  Build in progress...

View logs