Networking and traffic
Gateway API CRDs
1.What is the CRD Bundle ?
One YAML file per release of kubernetes-sigs/. 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-versionandchannel
Key ideaThey are only the API. A controller (Envoy Gateway, kgateway, Istio, Cilium...) makes them real.
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.
| Standard | Experimental | |
|---|---|---|
| Stable | No breaking changes in a version | May break any release |
| File | standard- | experimental- |
| Use | Production | Trying features |
| Rollback | Safe (pin version) | Can fail if objects use experimental fields |
3.Versions and Graduation
| Kind | Role | Points to |
|---|---|---|
| GatewayClass | Names the controller | controller |
| Gateway | Listeners, the LB | GatewayClass |
| HTTPRoute | L7 host, path, header | Gateway |
| GRPCRoute | L7 gRPC method | Gateway |
| BackendTLSPolicy | TLS to backend | Service |
| TLSRoute | Route by SNI | Gateway |
| ReferenceGrant | Allows cross-ns refs | its own ns |
| ListenerSet | Extra listeners | Gateway |
| TCPRoute / UDPRoute | L4 port routing | Gateway |
Only GatewayClass is cluster-scoped, every other kind lives in a namespace.
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
AcceptedandProgrammedto status
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
| Command | Description | Example |
|---|---|---|
kubectl apply --server-side -f standard-install. | Install or upgrade | pin the v1.6.3 URL |
kubectl get crd | grep gateway. | List the CRDs | k8s.io, x-k8s.io |
kubectl get crd gateways.gateway.networking.k8s.io -o yaml | grep bundle | Bundle version | v1.6.3, standard |
kubectl get crd tcproutes.gateway.networking.k8s.io -o jsonpath='{.status.storedVersions}' | Versions in etcd | lists v1alpha2 = migrate first |
kubectl apply --server-side --force-conflicts -f <file> | Take over fields | after Helm owned them |
kubectl delete -f <same file> | Uninstall the CRDs | drops all Routes too |
4.Helm-Managed CRDs
Many controller charts ship the Gateway API CRDs. Helm treats them differently by folder.
| Helm action | crds/ folder | templates/ |
|---|---|---|
| install | Created | Created |
| upgrade | Skipped (stale) | Updated |
| uninstall | Kept | Deleted, with all objects |
Rule : one owner for the CRDs per cluster : the platform, one chart, or kubectl. Never two.
Gotchas
metadata.= client-side apply, addannotations: Too long --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 : addresource-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.