Gateway API 1.2 migration includes controllers and stored versions

Changing a manifest's API version does not prove that every client and stored object has completed the same migration. The November 21 Gateway API 1.2 article makes that problem concrete. Gateway API 1.2 shipped on October 3. November's guidance describes its new routing capabilities alongside the removal of older API versions, with particular attention to dependencies that are easy to miss during a CRD upgrade.

The removed versions are v1alpha2 for GRPCRoute and ReferenceGrant, in both the Standard and Experimental channels. A controller still requesting those versions can fail even when the manifests supplied by users already name a newer version. Kubernetes also records versions used to persist custom resources, and that history can prevent removal of a CRD version. The migration therefore crosses both running clients and stored data.

I value custom resources because they let external controllers use Kubernetes's API machinery. That extensibility also means an API upgrade belongs to the relationship between the resource definition and its consumers. Replacing the CRD YAML alone cannot establish that the controller and existing objects are ready for the new contract.

Check the actual served version

There is a detail in the announcement worth resolving against the release artifact. The prose broadly describes migration to v1 for both resources, but the ReferenceGrant CRD shipped in v1.2.0 serves v1beta1. GRPCRoute uses v1. The release's own storage migration commands make that distinction explicit.

The versioned changelog explains that status.storedVersions may still contain v1alpha2. Kubernetes does not automatically prune that historical entry. Before changing the status, existing resources need to be rewritten through the latest storage version. Removing the recorded version first would assert completion of work that has not necessarily happened.

This separates the version currently served from the versions that may have been used to store objects. Both affect a safe transition. A manifest that creates new objects through a current endpoint says little about older objects already persisted in the cluster. The changelog addresses that gap with an explicit migration sequence.

Standard does not mean universally implemented

The new routing capabilities also have distinct support levels. HTTPRoute timeouts graduate to the Standard channel, providing request and backend-request timeout configuration. The changelog marks their conformance support as Extended, so implementation support is optional. Stable API design and mandatory support across every conformant controller are different properties.

A request timeout can be expressed directly on an HTTPRoute rule, as in this fragment based on the announcement's example:

rules:
- matches:
  - path:
      type: PathPrefix
      value: /face
  backendRefs:
  - name: face
    port: 80
  timeouts:
    request: 300ms

The field belongs to HTTPRoute. The November article explicitly says GRPCRoute timeouts are not yet included. Keeping that limit clear avoids assuming that similar resource names imply identical routing controls. The API's stable contract is specific to the resource and capability described.

Backend protocol support also reaches Standard. The Service port's appProtocol can identify cleartext HTTP/2 or WebSocket protocols through the defined Kubernetes values. Gateway implementations that support the capability can use that information for backend connections. The changelog again marks this as Extended support, which makes the installed implementation's capability relevant to the result.

Infrastructure configuration has its own contract

Gateway infrastructure labels and annotations graduate to Standard as well. A Gateway can carry metadata intended for resources its controller creates to fulfill the Gateway declaration. This is useful because generated Services or Deployments otherwise sit one step away from the resource an administrator edits. The field gives that relationship an API representation.

The changelog identifies infrastructure propagation as another Extended capability. An administrator needs to distinguish the presence of the field in the schema from support in the selected implementation. A structurally valid object does not itself prove that generated infrastructure receives the requested metadata.

I prefer that explicit capability accounting to treating a version number as a complete behavior description. Gateway API defines a shared language used by several implementations. Its conformance model has to say which parts every implementation provides and which parts require an additional support claim.

Experimental additions remain a separate choice. The release adds counted HTTPRoute retries and percentage-based request mirroring in that channel. Those fields can change or disappear before graduation. The changelog describes them as intended for testing and verification, with support still dependent on the implementation. Their inclusion beside Standard graduations in the announcement does not give them the same compatibility commitment.

The November guidance is consequently useful as an adoption document after October's release. It connects new fields to the implementation and storage changes required to use them safely. For an existing installation, successful migration means that controllers use served versions, stored resources have completed the version transition, and the selected controller supports the specific routing capabilities the configuration requests.