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 weight on 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).

Ingress one objecteveryone edits annotationsper-vendor dialect Gateway API GatewayClass : infra provider Gateway : cluster operator Routes : app dev
Why roles ?Splitting by owner means a dev can ship a Route without touching the shared Gateway.

2.Resource Model

Each role edits its own object. parentRefs / gatewayClassName point up to the parent; backendRefs point down to the backend.

FieldOnPoints to
controllerNameGatewayClassController (up)
gatewayClassNameGatewayGatewayClass (up)
parentRefsRouteGateway (up)
backendRefsRoute ruleService (down)
certificateRefsListenerSecret (TLS)
hostnamesRouteListener 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.

GatewayClasscluster scoped Controller controllerName Gatewayns infra gatewayClassName HTTPRoutens app-a HTTPRoutens app-b parentRefs Service app-a Service app-b backendRefs
Just a spec CRDs are not a controller. You also need one (Envoy Gateway, kgateway, Istio, Cilium, NGINX Gateway Fabric...).

3.Request Flow

The Gateway status gives the address. The listener handles TLS, then a Route rule picks the backend.

ModeWho decryptsRoute
TerminateGateway, cert in certificateRefsHTTPRoute, GRPCRoute
PassthroughBackend, Gateway reads SNI onlyTLSRoute
Client to Pods
Client
DNS / LB IPaddresses
Listener :443TLS
Pods
Serviceweighted refs
HTTPRoutehost, path, header
Cert note : a Secret in another namespace needs a ReferenceGrant. Gateway status.addresses = the LB IP clients hit.
In short : Gateway API is a spec plus CRDs. Infra owns GatewayClass, ops owns Gateway, devs own Routes, and a controller does the work.

1.Matching and Filters

A rule = matches + filters + backendRefs, checked in that order.

FieldExampleNote
matches
pathPathPrefix /apiExact, Prefix, Regex
headersenv = canaryExact (Core), regex (impl.)
queryParamsv = 2Exact (Extended)
methodPOSTExtended
filters
RequestHeaderModifierset, add, removeCore filter
RequestRedirectto https, 301Core, no backend
URLRewrite/v1/x to /xprefix or full path
RequestMirrorcopy to shadowreply dropped
rule
timeoutsrequest: 10sbackendRequest per try
Request matchesAND inside, OR across filtersrun in listed order backendRefs + weight
  • 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}
  1. Operator creates the Gateway
  2. Controller sets status.addresses
  3. Dev creates the HTTPRoute in ns app
  4. allowedRoutes must permit ns app
  5. Controller sets Accepted / ResolvedRefs
weight 90 / 10web-svc / web-canary
Canary = weights. Devs ship it without touching the Gateway.
Attach rules A Route finds its Gateway with parentRefs. The Gateway must allow it with allowedRoutes (default : same ns).

3.Status and ReferenceGrant

OnConditionReasons when False
GatewayAcceptedListenersNotValid
GatewayProgrammedPending, AddressNotAssigned
ListenerResolvedRefsInvalidCertificateRef
RouteAcceptedNotAllowedByListeners
RouteResolvedRefsBackendNotFound, RefNotPermitted
ns app HTTPRoute ns db Service refs ReferenceGrantfrom: app Routesto: Service allows Grant lives in the TARGET namespace. Missing : RefNotPermitted
CommandShows
kubectl describe gateway my-gw -n infraListener conditions, attachedRoutes
kubectl describe httproute web -n appstatus.parents per Gateway
kubectl get referencegrant -AWho may point across ns
ingress2gateway printConvert Ingress to Gateway YAML
In short : A rule matches, filters, then picks weighted backends. Cross-namespace refs need a ReferenceGrant; when it breaks, read Gateway AND Route conditions.