Gateway API version matching

[FernandoMiguel]

is there a map or doc that details which versions of Gateway API are supported by each release of LBC?
or does LBC requires a minimum version and supports all newer ones ?

[FernandoMiguel]

sourced from Claude

AWS Load Balancer Controller & Kubernetes Gateway API Compatibility

LBC Version → Gateway API Version Mapping

Gateway API support was introduced in LBC v2.13.0.

LBC Version	go.mod gateway-api	Docs-prescribed CRDs	Gateway API Features
< v2.13.0	—	—	No Gateway API support
v2.13.0 – v2.13.4	v1.2.0	v1.2.0	L4 only (NLB): TCPRoute, UDPRoute, TLSRoute
v2.14.0 – v2.14.1	v1.3.0	v1.2.0	L4 + L7 (ALB): adds HTTPRoute, GRPCRoute
v2.15.0 – v2.17.1	v1.3.0	v1.2.0	L4 + L7
v3.0.0 – v3.1.0	v1.3.0	v1.3.0	L4 + L7

Note: LBC v2.14.0+ was compiled against Gateway API v1.3.0, but the install docs
continued to prescribe v1.2.0 CRDs until v3.0.0 aligned them. Both work — see the
forward compatibility section below.

Feature Gates

Gateway API support requires explicit feature gate enablement:

--feature-gates=NLBGatewayAPI=true    # L4 routes (>= v2.13.3)
--feature-gates=ALBGatewayAPI=true    # L7 routes (>= v2.14.0)

---

API Versions Used by LBC

The controller watches these specific Kubernetes API versions at runtime:

Purpose	Type	API Version	CRD Channel
L7 (ALB)	Gateway	gateway.networking.k8s.io/v1	Standard
L7 (ALB)	GatewayClass	gateway.networking.k8s.io/v1	Standard
L7 (ALB)	HTTPRoute	gateway.networking.k8s.io/v1	Standard
L7 (ALB)	GRPCRoute	gateway.networking.k8s.io/v1	Standard
L4 (NLB)	TCPRoute	gateway.networking.k8s.io/v1alpha2	Experimental only
L4 (NLB)	UDPRoute	gateway.networking.k8s.io/v1alpha2	Experimental only
L4 (NLB)	TLSRoute	gateway.networking.k8s.io/v1alpha2	Experimental only
Both	ReferenceGrant	gateway.networking.k8s.io/v1beta1	Standard

Key implication: L4/NLB support always requires the experimental CRD channel
(experimental-install.yaml), since TCPRoute and UDPRoute only exist there.

---

Forward Compatibility Matrix

Can you install newer Gateway API CRDs than the version LBC was compiled against?

L7 Routes (ALB) — All use stable v1 types

Gateway API CRDs	Gateway v1	HTTPRoute v1	GRPCRoute v1	ReferenceGrant v1beta1	L7 Result
v1.2.0	Served	Served	Served	Served	Works
v1.3.0	Served	Served	Served	Served	Works
v1.4.0	Served	Served	Served	Served	Works
v1.4.1	Served	Served	Served	Served	Works
v1.5.0-dev	Served	Served	Served	Served	Works

L7 routes are fully forward-compatible. The v1 API is stable and all versions continue to
serve it.

L4 Routes (NLB) — Experimental CRDs required

Gateway API CRDs (experimental)	TCPRoute v1alpha2	UDPRoute v1alpha2	TLSRoute v1alpha2	L4 Result
v1.2.0	Served (storage)	Served (storage)	Served (storage)	Works
v1.3.0	Served (storage)	Served (storage)	Served (storage)	Works
v1.4.0	Served (storage)	Served (storage)	Served (not storage)	Works
v1.4.1	Served (storage)	Served (storage)	Served (not storage)	Works
v1.5.0-dev (experimental)	Served (storage)	Served (storage)	Served (not storage)	Works
v1.5.0-dev (standard)	Not included	Not included	NOT served	BREAKS

All current LBC releases work with experimental Gateway API CRDs up to at least v1.4.1.

---

Upcoming Breaking Changes

TLSRoute graduating from v1alpha2

In the Gateway API main branch (heading towards v1.5.0):

• TLSRoute was promoted to standard channel with v1 as the storage version
• In the standard CRDs: v1alpha2 is no longer served (served=false)
• In the experimental CRDs: v1alpha2 is still served (for backward compatibility)

Impact: If you switch from experimental to standard CRDs on a future Gateway API
release, LBC's L4 TLSRoute support will break because the controller hardcodes
v1alpha2 watches.

TCPRoute and UDPRoute

These remain experimental (v1alpha2 only) with no graduation timeline announced yet.
When they eventually graduate to v1beta1 or v1, LBC will need a code update.

ReferenceGrant

v1beta1 remains served across all versions. A v1 version has been added alongside it
(v1 is served but not yet storage). No breaking change expected — v1beta1 will continue
to be served through the standard deprecation cycle (at least 4 minor releases).

---

Upgrade Guidance

Safe upgrade path

1. L7 only (ALB): You can use any Gateway API CRD version from v1.2.0 onward,
   standard or experimental channel. All v1 types are stable.

2. L4 + L7 (NLB + ALB): Always use experimental-install.yaml. You can safely
   upgrade from v1.2.0 through v1.4.1 with any current LBC release.

3. Upgrading LBC: Newer LBC releases are backward-compatible with older CRDs.
   You don't need to upgrade CRDs when upgrading LBC (though aligning them is
   recommended).

What to watch for

• Never install standard-install.yaml if you use L4/NLB routes. TCPRoute and
  UDPRoute are experimental-channel only.
• When Gateway API v1.5.0 releases, review the TLSRoute situation if using standard
  CRDs.
• Monitor for TCPRoute/UDPRoute API version changes in future Gateway API releases.

---

Summary

There is no formal compatibility matrix published by either project. However, the
practical rule is straightforward:

All LBC releases with Gateway API support (v2.13.0+) work with Gateway API CRDs
v1.2.0 through v1.4.1 when using the experimental channel. The v1 (stable) types
used for L7 routing are forward-compatible indefinitely. The v1alpha2 types used for
L4 routing are forward-compatible as long as the experimental CRDs continue to serve
v1alpha2 — which they do through at least v1.4.1 and the current development branch.

---

Data sourced from aws-load-balancer-controller git tags (go.mod + docs at each release)
and gateway-api CRD definitions at each tagged version. Last verified: 2026-02-25.

[zac-nixon]

Claude output looks correct. Our documentation stating the supported version is here.

The go.mod also reflects that oo.

[FernandoMiguel]

thanks for that link