Networking and traffic

Gateway API CRDs

1.What is the CRD Bundle ?

One YAML file per release of kubernetes-sigs/gateway-api. You apply it once and the cluster learns the Gateway API kinds.

  • Defines the kinds, their schema and CEL validation
  • Cluster-scoped : one copy, shared by every controller
  • Versions apart from Kubernetes core, latest v1.6.3
  • Each CRD is annotated with its bundle-version and channel
Key ideaThey are only the API. A controller (Envoy Gateway, kgateway, Istio, Cilium...) makes them real.
gateway-api repo kubectl apply CRD bundleschema, CEL, v1.6.3 watched by Controllervendor chart, own release programs Proxy (data plane) one percluster one ormany
Why Gateway API ? Ingress vs Gateway API, the role model, request flow and YAML examples are in the Gateway API section. This topic is only the CRDs.

2.Standard vs Experimental

Two release channels, same version number. Experimental is a superset of Standard.

  • Standard : only v1 kinds and fields
  • Experimental : adds alpha fields, plus kinds in group gateway.networking.x-k8s.io
Note : do not mix channels or versions across controllers. The CRDs are cluster-scoped, so every controller sees the same copy.
StandardExperimental
StableNo breaking changes in a versionMay break any release
Filestandard-installexperimental-install
UseProductionTrying features
RollbackSafe (pin version)Can fail if objects use experimental fields

3.Versions and Graduation

KindRolePoints to
GatewayClassNames the controllercontroller
GatewayListeners, the LBGatewayClass
HTTPRouteL7 host, path, headerGateway
GRPCRouteL7 gRPC methodGateway
BackendTLSPolicyTLS to backendService
TLSRouteRoute by SNIGateway
ReferenceGrantAllows cross-ns refsits own ns
ListenerSetExtra listenersGateway
TCPRoute / UDPRouteL4 port routingGateway

Only GatewayClass is cluster-scoped, every other kind lives in a namespace.

v1.0 GatewayClass, GatewayHTTPRoute v1.1 GRPCRoute v1.4 BackendTLSPolicy v1.5 TLSRoute, ReferenceGrantListenerSet v1.6 TCPRoute, UDPRoute kinds graduate into Standard as v1
Upgrade note : a graduated kind keeps its old version (v1alpha2) for a few releases. Move objects to v1 before it is removed.
In short : The CRD bundle is only the API : one cluster-wide copy per channel and version, kinds graduate to v1 over releases, and a separate controller does the work.

1.Install : CRDs vs Controller

One kubectl apply registers the CRDs. The controller, installed apart, does the real work.

  • Always apply with --server-side
  • Install the CRDs first, then the controller
  • Without a controller objects are stored, status stays empty
  • Controller writes Accepted and Programmed to status
kubectl apply registers API serverCRDs registered Gateway, Routes stored watches Controller writes statusconditions
Note : check with kubectl get gatewayclass, ACCEPTED = a controller owns it.

2.Upgrade and Uninstall

An upgrade is the same apply with a newer file. The risk is what the new version drops.

  • A removed version (v1alpha2) must not be in storedVersions
  • New required fields can reject old objects
  • The controller must support the new bundle version
Upgrade Flow
Checkannotation
Read notesremovals
Applyserver side
Verifystatus
Uninstall : kubectl delete -f with the same file. Deleting a CRD deletes every object of that kind, so every Gateway and Route goes with it.

3.Commands

CommandDescriptionExample
kubectl apply --server-side -f standard-install.yamlInstall or upgradepin the v1.6.3 URL
kubectl get crd | grep gateway.networkingList the CRDsk8s.io, x-k8s.io
kubectl get crd gateways.gateway.networking.k8s.io -o yaml | grep bundleBundle versionv1.6.3, standard
kubectl get crd tcproutes.gateway.networking.k8s.io -o jsonpath='{.status.storedVersions}'Versions in etcdlists v1alpha2 = migrate first
kubectl apply --server-side --force-conflicts -f <file>Take over fieldsafter Helm owned them
kubectl delete -f <same file>Uninstall the CRDsdrops all Routes too

4.Helm-Managed CRDs

Many controller charts ship the Gateway API CRDs. Helm treats them differently by folder.

Helm actioncrds/ foldertemplates/
installCreatedCreated
upgradeSkipped (stale)Updated
uninstallKeptDeleted, with all objects
Rule : one owner for the CRDs per cluster : the platform, one chart, or kubectl. Never two.
Gotchas
  • metadata.annotations: Too long = client-side apply, add --server-side
  • Two charts, two bundle versions : every upgrade flips the CRDs
  • One chart's experimental CRDs switch the channel for every controller
  • Old admission webhook left over : remove it, CEL replaced it
  • templates/ CRDs : add resource-policy: keep
  • v1.6.0 : ReferenceGrant spec now required
In short : Install the CRDs once with server-side apply, pick one channel and one owner, check storedVersions before upgrades, and let a controller do the rest.