The Gateway API is the successor to Ingress. It splits routing into three role-oriented resources: a platform team owns the GatewayClass and Gateway, while application teams own HTTPRoute. That separation and a typed, extensible spec are the main reasons to adopt it.
Before you start
You should understand Services, Ingress and namespaces. This article assumes a controller that implements the Gateway API is installed.
Step-by-step walkthrough
Step 1: Establish a GatewayClass and Gateway
A GatewayClass names the controller that will implement gateways, and a Gateway represents one load-balancer listener, including its port, protocol and TLS configuration. The platform team manages both, so application teams do not configure the shared entry point.
Step 2: Attach routes with parentRefs
An HTTPRoute references the Gateway through parentRefs and defines matches, filters and backendRefs. Matches can use path, header and query rules, which Ingress could only express through controller-specific annotations.
Step 3: Verify status and cross-namespace rules
Routes report status conditions on the resource, so you can see whether a Gateway accepted the route. Cross-namespace attachment is controlled by allowedRoutes, which is the explicit replacement for Ingress’s implicit sharing.
Worked scenario
The route matches a path prefix and forwards to a Service.
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: api
spec:
parentRefs:
- name: main-gateway
rules:
- matches:
- path:
type: PathPrefix
value: /api
backendRefs:
- name: api-service
port: 80Walk through the example
The parentRefs entry binds the route to main-gateway, and the rule forwards any /api/... request to api-service:80. Because matching is part of the spec rather than an annotation, the behavior is portable across controllers. The route’s status tells you whether the Gateway accepted it.
Common mistake
Copying Ingress annotations onto Gateway API objects, which are ignored because the API is typed. Another is assuming a route is live without checking its status conditions, so a rejected or unattached route looks fine until traffic fails.
Verify the behavior
Apply the resources and check kubectl get httproutes and the resource’s status for an Accepted condition. Send a request to the matched path and confirm it reaches the Service, and send an unmatched path to confirm the default. Change the backend port and confirm the status reflects the change.
Interview exercise
Why does the Gateway API separate Gateway and HTTPRoute into different resources?
Answer and reasoning
It separates ownership. The platform team controls the shared listeners, TLS and IP, while application teams attach routes without editing the shared entry point. This reduces the blast radius of a mistake and removes the Ingress pattern where every team annotated the same object, which made the shared resource a contention point.
Continue learning
Compare routing options in Kubernetes ingress routing and service selectors. Read the Kubernetes Gateway API documentation and try the Kubernetes interview questions.