[Upstream Breaking Change] kgateway v2.1.1 → v2.2.1

[github-actions]

Summary

kgateway v2.2.1 has been released with major breaking changes introduced in v2.2.0. The current pin is v2.1.1 in guides/prereq/gateway-provider/kgateway.helmfile.yaml.

Critical Breaking Changes in v2.2.0

1. AgentgatewayPolicy API Changes (HIGH)

The v2.2.0 release introduces a new AgentgatewayPolicy API that replaces TrafficPolicy for agentgateway:

• New agentgateway.dev group replaces kgateway.dev/agentgateway
• TrafficPolicy AI policies have been removed (#12901)
• AgentgatewayPolicy is now the only way to configure agentgateway (#13013)

Impact: Existing agentgateway installations will break without migration.

2. Helm Chart Split (HIGH)

The Helm installation UX has been completely restructured (#13062):

• Separate charts for kgateway and agentgateway
• New installation commands required
• Controller renamed from kgateway.dev/agentgateway to agentgateway.dev/agentgateway (#13088)

New installation pattern:

helm install kgateway-crds oci://cr.kgateway.dev/kgateway-dev/charts/kgateway-crds --version v2.2.1
helm install kgateway oci://cr.kgateway.dev/kgateway-dev/charts/kgateway --version v2.2.1
helm install agentgateway-crds oci://cr.agentgateway.dev/charts/agentgateway-crds --version v2.2.1
helm install agentgateway oci://cr.agentgateway.dev/charts/agentgateway --version v2.2.1

3. GatewayParameters Changes (MEDIUM)

• Removed deprecated spec.kube.floatingUserId field (#12747)
• agentgateway can no longer be configured with GatewayParameters, only with AgentgatewayParameters (#13054)
• AgentgatewayParameters rawConfig has breaking changes (#13127)

Migration: Use spec.kube.omitDefaultSecurityContext instead of floatingUserId.

4. Feature Gate (MEDIUM)

New environment variable KGW_ENABLE_EXPERIMENTAL_GATEWAY_API_FEATURES defaults to false (#12695). Experimental features now require explicit opt-in.

5. Deprecations

• HTTPListenerPolicy deprecated in favor of httpSettings under ListenerPolicy (#13066)
• GatewayParameters agentgateway fields deprecated (#13101)

Files Affected

Per docs/upstream-versions.md:

• guides/prereq/gateway-provider/kgateway.helmfile.yaml

We also track agentgateway separately:

• guides/prereq/gateway-provider/agentgateway.helmfile.yaml (currently v2.2.0-beta.3)

Recommended Actions

1. Review Migration Guide: Read the official agentgateway migration guide

2. Audit Usage:

   # Check for TrafficPolicy usage in guides
   grep -r "TrafficPolicy" guides/ --include="*.yaml" --include="*.gotmpl"
   
   # Check for AgentgatewayPolicy usage
   grep -r "AgentgatewayPolicy" guides/ --include="*.yaml" --include="*.gotmpl"
   
   # Check for GatewayParameters with agentgateway fields
   grep -r "agentgateway:" guides/ -A 5 --include="*.yaml"
   
   # Check for floatingUserId
   grep -r "floatingUserId" guides/ --include="*.yaml"

3. Update helmfile references from v2.1.1 to v2.2.1

4. Update agentgateway from v2.2.0-beta.3 to v2.2.1

5. Test E2E workflows that use kgateway/agentgateway

6. Update documentation to reflect new installation patterns

Impact

HIGH - Multiple breaking changes affecting agentgateway installations, Helm chart structure, and API groups. Installations using agentgateway will break without migration.

Upstream References

• v2.2.1 Release: https://github.com/kgateway-dev/kgateway/releases/tag/v2.2.1
• v2.2.0 Release: https://github.com/kgateway-dev/kgateway/releases/tag/v2.2.0
• Migration Guide: https://github.com/kgateway-dev/kgateway/blob/main/docs/guides/agentgateway-migration.md
• Full Changelog: kgateway-dev/kgateway@v2.1.1...v2.2.1

---

Generated by Upstream Dependency Monitor

Generated by Upstream Dependency Monitor