Kubernetes Gateway API Knowledge Patch

Kubernetes Gateway API Knowledge Patch

Load this skill when installing or upgrading Gateway API CRDs, writing Gateway or Route manifests, implementing a controller, or evaluating conformance and feature support. Start with the upgrade hazards below, then open the topic reference that matches the work.

Reference index

Upgrade and migration hazards

Keep the safe-upgrade admission policy

Gateway API installs a ValidatingAdmissionPolicy named safe-upgrades.gateway.networking.k8s.io. It guards operations that can leave CRDs in an unsafe or unsupported combination:

• Adding Experimental CRDs after Standard CRDs are installed is blocked.
• Downgrading to releases before the policy's supported floor is blocked.
• Monthly and older release installations are also blocked by the tightened policy.
• Upgrading Experimental CRDs that are already present remains permitted.

Delete the policy only for a deliberate guarded operation whose consequences have been assessed. See API lifecycle and upgrades.

Recreate graduated Experimental resources

New Experimental kinds use an X prefix in the gateway.networking.x-k8s.io API group. Experimental and Standard identities can coexist, but graduation does not transform stored objects: recreate them under the non-X kind and the Standard API group.

This matters especially for XListenerSet. Use the Standard ListenerSet after graduation; the Experimental kind is no longer shipped.

Migrate route and grant API versions

• Use gateway.networking.k8s.io/v1 for TLSRoute, TCPRoute, UDPRoute, and ReferenceGrant.
• Treat older TLSRoute alpha versions and the v1alpha2 transport-route versions as deprecated migration sources, not new manifest targets.
• Correct ReferenceGrant objects that omit spec; the field is mandatory.
• Kubernetes 1.31 or later is required for the stable TLSRoute CEL validation.

Read API lifecycle and upgrades before changing installed CRDs or stored objects.

Update manifests for stricter schemas

Previously accepted or generated shapes can now fail validation:

• GRPCRoute.spec is required.
• HTTPRoute.spec.rules must contain at least one rule.
• ReferenceGrant.spec is required.
• HTTP retry codes must be unique and attempts must be at least 1.
• An HTTPRoute rule may contain at most one CORS filter.
• Session-persistence cookieConfig is valid only for cookie persistence.
• Experimental session persistence no longer has idleTimeout.
• A Gateway infrastructure object may have at most 16 annotations.

Generated clients that modeled CORS allowCredentials as an enum must also be updated to accept the Boolean value false.

Recheck listener and route compatibility

• Do not attach a TCPRoute to a TLS listener.
• Do not assume HTTPRoute and GRPCRoute can share one hostname; an implementation may either allow or reject that combination.
• A healthy listener need not emit Conflicted=False.
• Overlapping TLS configuration can make connection coalescing unsafe and produce OverlappingTLSConfig; affected requests should receive HTTP 421.

Gateway and listener quick reference

Handle infrastructure failures precisely

For a missing, unsupported, or malformed Gateway infrastructure reference, set Accepted with reason InvalidParameters. Infrastructure support is a Standard feature.

Gateway.spec.addresses permits an entry without value. An implementation that supports empty addresses assigns one; an implementation that does not must report Programmed=False with reason AddressNotAssigned.

Account for implicit and delegated attachment

Default-Gateway support allows selected Routes to attach without the usual explicit relationship, so both controller logic and route-owner expectations must account for the additional attachment path.

ListenerSet delegates listener configuration to a Gateway and can attach across namespaces. A ListenerSet requires each listener's port. Gateway status reports the number attached through AttachedListenerSets, while invalid delegated listeners can use reason ListenersNotValid.

See Gateways, listeners, and status for attachment, compatibility, and status details.

Policy and security quick reference

Treat BackendTLSPolicy capabilities separately

BackendTLSPolicy is Standard, but not every field is Core: subjectAltNames is Extended and therefore optional for implementations. Target references receive CEL validation.

When evaluating a policy:

• Use ResolvedRefs for reference-resolution status.
• Apply the standardized invalid-policy and target-conflict behavior.
• Give SAN validation precedence over Hostname validation.
• Allow implementation-specific wellKnownCACertificates values only when the selected implementation documents them.
• Account for support on additional Route types.
• Permit no more than 16 certificate-authority references.

Separate frontend and backend certificate roles

Gateway-terminated TLS client-certificate validation and selection of the Gateway client certificate used for backend TLS are distinct Standard features. Check both capabilities when mutual TLS spans both sides of a Gateway.

Validate authentication and persistence placement

External authentication began at HTTPRoute scope and also has an Experimental Gateway-level form. Confirm the scope supported by the implementation before placing authentication configuration.

XBackendTrafficPolicy combines session persistence with destination-wide retry budgets. Use nested budget.percent and budget.interval, not the old flat field names. Read Policies, security, and capabilities for the full policy lifecycle and feature-reporting rules.

Route and filter quick reference

Use percentage request mirroring deliberately

RequestMirror can select a percentage of requests on both HTTPRoute and GRPCRoute. It is a Standard-channel Extended feature, so check advertised support rather than assuming every conformant implementation provides it.

Apply the current CORS constraints

The HTTPRoute CORS filter is Standard. Its relevant validation rules include:

• allowCredentials is Boolean and may be false.
• allowMethods cannot combine * with named methods.
• Origin host values must pass CEL validation.
• A rule cannot contain duplicate CORS filters.

Name route elements and respect limits

HTTPRoute rules and matches can be named for stable identification. GRPCRoute allows up to 64 matches. A TLSRoute can scale to 4096 hostnames and 4096 rules, but large manifests should be tested against representative API server, etcd, and controller capacity.

Validate retry configuration

Within an HTTPRoute retry configuration, each status code must appear only once and attempts must be at least 1. These are schema-level constraints, not controller-specific preferences.

See Routes, filters, and validation for complete route API and graduation details.

Implementation and conformance checklist

Before accepting a Gateway API manifest or enabling a controller feature:

1. Identify whether each resource is Standard or Experimental and use its current API identity.
2. Check GatewayClass.status.supportedFeatures for optional capabilities.
3. Validate all required spec, rule, filter, and policy relationships.
4. Resolve listener attachment and route compatibility, including implicit default-Gateway attachment.
5. Emit the specified conditions and reasons for infrastructure, address, TLS, and ListenerSet outcomes.
6. Exercise large route objects and implementation-specific policy values in a representative environment.
7. Keep the safe-upgrade admission policy in place unless intentionally performing and reviewing a guarded operation.