Document kgateway support guarantees for major dependencies

[danehans]

Summary

PR #13671 highlighted that kgateway does not currently have a clearly defined, easy-to-find support policy for Gateway API and other major upstream dependencies.

Today, users can infer different things from different places:

• the version support page documents one Gateway API line per kgateway release line
• the nightly workflow tests multiple Gateway API releases and channels
• individual PRs end up making policy decisions ad hoc (for example, whether to keep compatibility shims for promoted resources such as XListenerSet -> ListenerSet)

We should define and document what kgateway actually guarantees so users and maintainers can answer questions like:

• Which Gateway API versions are supported vs only tested?
• Do we support N, N-1, or N-2 for Gateway API?
• Does that differ for standard vs experimental Gateway API channels?
• When an experimental API graduates, how long do we keep compatibility with the pre-promotion form?
• What is the difference between a compatibility target, a CI-tested target, and a release-blocking support guarantee?
• What guarantees do we provide for other major dependencies such as Kubernetes, Istio, Envoy, and the Gateway API Inference Extension?

This issue is about defining the policy and publishing it clearly. Follow-up implementation issues can refine CI, docs, and compatibility behavior once the policy is agreed.

Guidance

Istio is a useful model here because it documents:

• release support windows and maintenance expectations
• compatibility matrices
• support status by release line
• temporary compatibility behavior during upgrades

References:

• Istio supported releases
• Istio compatibility versions
• Istio support status of releases

Related

• PR #13671
• Issue #13682

Scenarios To Cover

The policy should explicitly address scenarios like these:

• Gateway API resource promotion, such as XListenerSet graduating to ListenerSet
• Gateway API fields moving from experimental to standard
• Gateway API features being present only behind kgateway feature gates
• Old experimental Gateway API resources no longer existing in current Go dependencies, while users may still run older CRDs
• Schema tightening between Gateway API releases that makes previously accepted manifests invalid
• Conformance tests added in a newer upstream Gateway API release when kgateway only partially supports the promoted API surface
• Whether CI testing multiple versions implies official support, best-effort compatibility, or only regression detection
• Whether standard and experimental Gateway API channels should have different support windows
• How long compatibility shims should remain after upstream promotions or removals
• How support guarantees should differ across Kubernetes, Istio, Envoy, Gateway API, and the Gateway API Inference Extension

Checklist

• Define the difference between supported, tested in CI, best effort, and not supported for upstream dependencies.
• Define the Gateway API support policy by channel: standard and experimental.
• Decide whether Gateway API support should be N, N-1, N-2, or something else, and whether that policy differs by channel.
• Decide what happens when an experimental Gateway API resource or field graduates, such as XListenerSet -> ListenerSet.
• Decide how long compatibility shims for promoted or removed Gateway API APIs should remain in kgateway.
• Decide whether conformance coverage is required for every supported Gateway API version/channel combination, or only for a primary target.
• Define the policy for Gateway API feature gates and how gated features affect what we advertise in GatewayClass.status.supportedFeatures.
• Define what support guarantee kgateway provides for Kubernetes versions, and how that differs from nightly min/max CI coverage.
• Define what support guarantee kgateway provides for Istio versions, including whether we want a compatibility matrix similar to Istio's published docs.
• Define what support guarantee kgateway provides for Envoy / xDS / protobuf dependency sets, especially when transitive updates can affect validation behavior.
• Define what support guarantee kgateway provides for the Gateway API Inference Extension, if any, and how its versioning should be communicated.
• Decide where the canonical dependency support policy should live in docs and how release notes should call out changes to that policy.
• Update repo automation and CI so the documented policy and the nightly/test matrix do not drift apart.
• Add follow-up issues as needed for any changes in CI, docs, conformance lanes, or compatibility shims once the policy is agreed.

Desired Outcome

A user should be able to answer, from one clear page and a small number of linked references:

• what kgateway officially supports today
• what is only tested as a compatibility signal
• what upgrade path the project expects for each major dependency
• what temporary compatibility behavior exists during upstream transitions

[danehans]

The repo has several different docs labels, hopefully I picked the right one.

[danehans]

cc: @davidjumani @DuncanDoyle @josh-pritchard I tagged this as high priority b/c IMHO it sets a requirement for much of our dev efforts.

[Mike-4-prog]

Hi @danehans ,
I’ll look into this and plan to create a single clear docs page showing what’s officially supported, what’s just tested, and how transitions (like experimental → standard) are handled.

[artberger]

Posting the current docs related to version support for reference:

• Version page, has a table of supported versions but does not explain any n+/- support https://kgateway.dev/docs/envoy/latest/reference/versions/
• Feature maturity, including for Gateway API experimental: https://kgateway.dev/docs/envoy/latest/reference/feature-maturity/

[Mike-4-prog]

Hi @danehans and maintainers 👋

I’m interested in helping move this forward from the documentation side.

From reviewing the issue and current docs, it seems this requires defining a clear support policy first (e.g., supported vs tested vs best-effort), before we can document it accurately.

To help progress this, I can:

• Propose a draft structure/template for the support policy page
• Summarize the key decisions needed (based on the checklist above)
• Reference models like Istio’s support/compatibility docs

Before I start drafting, could you clarify:

1. Should we first agree on a high-level policy direction (e.g., N/N-1 support for Gateway API)?
2. Is there any existing internal consensus on Kubernetes / Istio / Envoy support guarantees?
3. Would you prefer an initial proposal PR (draft) or discussion in this issue first?

Happy to take the first pass once direction is clear.
Take care!