Agent Skills: Kubernetes Gateway API Knowledge Patch

Kubernetes Gateway API Knowledge Patch

Use this skill when installing or upgrading Gateway API CRDs, authoring Gateway and Route manifests, implementing a controller, or checking conformance and status behavior. Start with the upgrade hazards, then open the reference that matches the task.

Reference index

| Reference | Topics | | --- | --- | | API lifecycle and upgrades | Safe-upgrade admission, channel identities, CRD graduation, route API migration, ReferenceGrant | | Gateways, listeners, and TLS | Addresses, infrastructure, ListenerSet, connection coalescing, client certificates, listener status | | Routes, filters, and attachment | Route validation, mirroring, CORS, authentication, retries, default Gateways, portability | | Policies, status, and conformance | Backend TLS, session persistence, retry budgets, feature reporting, Mesh capabilities |

Breaking changes and upgrade blockers

Respect the safe-upgrade admission policy

Gateway API installs safe-upgrades.gateway.networking.k8s.io as a ValidatingAdmissionPolicy. It blocks unsafe CRD combinations and release downgrades, including:

• adding Experimental CRDs after Standard CRDs are installed;
• downgrading to a release before the policy's supported floor;
• installing monthly Gateway API releases or older releases.

Upgrading Experimental CRDs already present is still allowed. Delete the policy only for a deliberately guarded operation whose consequences have been assessed.

Migrate graduated route and grant APIs

• Write TLSRoute, TCPRoute, and UDPRoute with gateway.networking.k8s.io/v1.
• Treat the older TLSRoute alpha versions and the v1alpha2 TCPRoute and UDPRoute versions as deprecated.
• Do not expect the Experimental channel to ship TLSRoute v1alpha2.
• Use ReferenceGrant at v1 and always include spec.
• Account for the Kubernetes version requirement imposed by stable TLSRoute CEL validation.

Experimental resources have distinct identities. New experimental kinds use an X prefix and gateway.networking.x-k8s.io; graduation requires object recreation under the Standard kind and group. Do not assume an experimental object changes identity in place.

Remove retired experimental forms and fields

• Replace XListenerSet with the Standard ListenerSet; the X-prefixed kind is no longer shipped.
• Remove idleTimeout from Experimental SessionPersistence configuration.
• Do not configure TCPRoute on a TLS listener.
• Do not emit an HTTPRoute without at least one rule.
• Do not emit GRPCRoute or ReferenceGrant objects without spec.

Update validation assumptions

Schema and CEL validation now reject several shapes that older tooling may have emitted:

• duplicate values in retry.codes;
• retry attempts values below 1;
• more than one CORS filter in one HTTPRoute rule;
• unsupported host values in CORS origins;
• session cookieConfig without persistence type Cookie;
• Gateway infrastructure with more than 16 annotations.

Generated clients must model CORS allowCredentials as a Boolean that may be either true or false, rather than using the earlier enum representation.

Gateway and listener quick reference

Handle overlapping TLS configuration

When HTTPS listener configuration overlaps in a way that makes connection coalescing unsafe, expose OverlappingTLSConfig as appropriate. Apply the clarified Hostname and SNI matching rules and return HTTP 421 for affected requests.

Client-certificate validation on a TLS-terminating Gateway and selection of the Gateway client certificate for backend TLS are Standard features. Keep those concerns distinct from BackendTLSPolicy server validation.

Handle implementation-assigned addresses

Gateway.spec.addresses contains GatewaySpecAddress entries whose value may be absent. With the Standard GatewayEmptyAddress feature:

• a supporting implementation assigns the address; or
• a non-supporting implementation reports Programmed=False with AddressNotAssigned.

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

Use ListenerSet status precisely

ListenerSet allows listeners to be merged into a Gateway and can attach across namespaces. Its listener port is required. The obsolete None option for Route namespaces must not be accepted.

Gateway status reports successfully attached sets with AttachedListenerSets. A ListenerSet that cannot be programmed because its listeners are invalid can report ListenersNotValid.

A listener that is not conflicted need not report Conflicted=False; absence of that negative condition is valid.

Route and filter quick reference

Validate route structure

• GRPCRoute allows up to 64 matches and requires a top-level spec.
• HTTPRoute requires at least one item in spec.rules.
• TLSRoute can scale to 4096 hostnames and 4096 rules, but large objects need representative API server, etcd, and controller testing.
• TCPRoute and UDPRoute have stable APIs and corresponding conformance coverage.

HTTPRoute and GRPCRoute on the same hostname are implementation-dependent: an implementation may allow or reject the combination. Avoid relying on coexistence in portable manifests.

Mirror only the desired traffic

RequestMirror can select a percentage of HTTPRoute or GRPCRoute requests. This is Standard-channel behavior at the Extended support level. For HTTPRoute, implementations advertise percentage mirroring with HTTPRouteRequestPercentageMirror in GatewayClass.status.supportedFeatures.

Configure CORS carefully

The HTTPRoute CORS filter supports Boolean allowCredentials, including false. Do not combine * with other entries in allowMethods, and do not place more than one CORS filter in a rule. Standard CORS validation rejects unsupported values in the host portion of an origin.

Name and authenticate routes

HTTPRoute rules and matches can carry explicit name values, enabling individual identification. Experimental HTTPRoute external authentication delegates authorization to an external service; experimental authentication can also be configured at Gateway scope.

Default-Gateway attachment can cause selected Gateways to program routes without an ordinary explicit attachment. Both controller implementations and route owners must account for this additional path.

Policy and conformance quick reference

Apply BackendTLSPolicy validation rules

BackendTLSPolicy is Standard and uses ResolvedRefs for reference resolution. Follow the standardized invalid-policy and target-reference conflict behavior.

subjectAltNames is Extended and therefore optional for implementations. When SAN validation is configured, it takes precedence over Hostname validation. Target references receive CEL validation.

The policy supports implementation-specific wellKnownCACertificates values, additional Route combinations, and up to 16 certificate-authority references.

Keep experimental retry and persistence fields current

XBackendTrafficPolicy replaces BackendLBPolicy. It combines session persistence with destination-wide retry budgets. Nest retry budget values under budget.percent and budget.interval; do not use the former flat field names.

Session-persistence cookieConfig is valid only with persistence type Cookie, and the Experimental SessionPersistence API no longer has idleTimeout.

Discover support instead of assuming it

GatewayClass.status.supportedFeatures is the Standard capability-reporting surface. Percentage request mirroring has a feature name, while experimental ListenerSet and backend traffic policy forms may require implementation-level support checks without a conformance feature name.

Mesh-wide experimental configuration reports mesh capabilities separately from Gateway capabilities. Do not infer one capability set from the other.

Review workflow

Before applying manifests or shipping controller changes:

1. Identify whether every resource is Standard or Experimental and use its correct API identity.
2. Check the installed CRD schema and the safe-upgrade policy before changing channels or release families.
3. Validate newly required fields, list bounds, filter uniqueness, and policy field relationships.
4. Inspect GatewayClass.status.supportedFeatures and implementation documentation for Extended or experimental behavior.
5. Verify attachment and programming through status, including negative reasons, rather than assuming that admission implies successful programming.
6. Exercise TLS coalescing, route-hostname portability, and large-object behavior when those edge cases apply.