# Kubernetes Gateway API Knowledge Patch > Kubernetes Gateway API - Skill: `nevaberry/kubernetes-gateway-api-knowledge-patch-2` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add nevaberry/kubernetes-gateway-api-knowledge-patch-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/nevaberry/kubernetes-gateway-api-knowledge-patch-2/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - License: MIT - Author: nevaberry (https://skillmd.com/u/nevaberry) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/nevaberry/kubernetes-gateway-api-knowledge-patch-2 --- # 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 | Reference | Topics | | --- | --- | | [API lifecycle and upgrades](references/api-lifecycle-and-upgrades.md) | Safe-upgrade admission, channel identities, API graduation, deprecated versions, and schema migrations | | [Gateways, listeners, and status](references/gateways-listeners-and-status.md) | TLS coalescing, infrastructure, assigned addresses, default attachment, ListenerSet, compatibility, and status | | [Policies, security, and capabilities](references/policies-security-and-capabilities.md) | Backend TLS, certificates, authentication, retry budgets, session persistence, and advertised features | | [Routes, filters, and validation](references/routes-filters-and-validation.md) | HTTPRoute, GRPCRoute, TLSRoute, TCPRoute, UDPRoute, CORS, mirroring, retries, and hostname portability | ## 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](references/api-lifecycle-and-upgrades.md). ### 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](references/api-lifecycle-and-upgrades.md) 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](references/gateways-listeners-and-status.md) 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](references/policies-security-and-capabilities.md) 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](references/routes-filters-and-validation.md) 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.