Networking and traffic
Gateway API
Gateway API : the role-based, portable successor to Ingress
1.Why Gateway API ?
Typed routing objects, split by who owns what. This topic is how routing behaves. The CRDs, channels and install are in the Gateway API CRDs section.
- Match header, query, method, not just host + path
- Redirect, rewrite, mirror : typed filters
- Canary is a
weighton backendRefs - Timeouts per rule, TLS Terminate or Passthrough
- ingress-nginx was archived 2026-03-24, no more fixes
Ingress is still supported but frozen. Gateway API is the upstream successor (SIG Network).
2.Resource Model
Each role edits its own object. parentRefs / gatewayClassName point up to the parent; backendRefs point down to the backend.
| Field | On | Points to |
|---|---|---|
| controllerName | GatewayClass | Controller (up) |
| gatewayClassName | Gateway | GatewayClass (up) |
| parentRefs | Route | Gateway (up) |
| backendRefs | Route rule | Service (down) |
| certificateRefs | Listener | Secret (TLS) |
| hostnames | Route | Listener hostname |
GatewayClass is cluster scoped, everything else is namespaced. A Route can list several parentRefs (two Gateways, or one listener by sectionName). Route and Listener hostnames must overlap.
3.Request Flow
The Gateway status gives the address. The listener handles TLS, then a Route rule picks the backend.
| Mode | Who decrypts | Route |
|---|---|---|
| Terminate | Gateway, cert in certificateRefs | HTTPRoute, GRPCRoute |
| Passthrough | Backend, Gateway reads SNI only | TLSRoute |
status.addresses = the LB IP clients hit.1.Matching and Filters
A rule = matches + filters + backendRefs, checked in that order.
| Field | Example | Note |
|---|---|---|
| matches | ||
| path | PathPrefix /api | Exact, Prefix, Regex |
| headers | env = canary | Exact (Core), regex (impl.) |
| queryParams | v = 2 | Exact (Extended) |
| method | POST | Extended |
| filters | ||
| RequestHeaderModifier | set, add, remove | Core filter |
| RequestRedirect | to https, 301 | Core, no backend |
| URLRewrite | /v1/x to /x | prefix or full path |
| RequestMirror | copy to shadow | reply dropped |
| rule | ||
| timeouts | request: 10s | backendRequest per try |
- Tie break : Exact path, longest prefix, method, most headers
- No rule matches : 404
2.Gateway + Canary Route
kind: Gateway
metadata: {name: my-gw, namespace: infra}
spec:
gatewayClassName: my-class
listeners:
- {name: http, port: 80, protocol: HTTP,
allowedRoutes: {namespaces: {from: All}}}
---
kind: HTTPRoute
metadata: {name: web, namespace: app}
spec:
parentRefs: [{name: my-gw, namespace: infra}]
rules:
- backendRefs:
- {name: web-svc, weight: 90}
- {name: web-canary, weight: 10}
- Operator creates the Gateway
- Controller sets
status.addresses - Dev creates the HTTPRoute in ns app
- allowedRoutes must permit ns app
- Controller sets Accepted / ResolvedRefs
parentRefs. The Gateway must allow it with allowedRoutes (default : same ns).
3.Status and ReferenceGrant
| On | Condition | Reasons when False |
|---|---|---|
| Gateway | Accepted | ListenersNotValid |
| Gateway | Programmed | Pending, AddressNotAssigned |
| Listener | ResolvedRefs | InvalidCertificateRef |
| Route | Accepted | NotAllowedByListeners |
| Route | ResolvedRefs | BackendNotFound, RefNotPermitted |
| Command | Shows |
|---|---|
kubectl describe gateway my-gw -n infra | Listener conditions, attachedRoutes |
kubectl describe httproute web -n app | status.parents per Gateway |
kubectl get referencegrant -A | Who may point across ns |
ingress2gateway print | Convert Ingress to Gateway YAML |