📖 Read-only preview — lessons, diagrams, and quizzes only. The hands-on labs, live grading, and progress tracking require running the real course locally against a Kubernetes cluster.Run it locally →

Module 8 · Lesson 8.2

Gateway API

Splitting one object into the right roles

Ingress bundles everything into one object, owned by whoever creates it. In practice that's often wrong: a platform team owns the shared load balancer and TLS certs, while an app team just wants to say "route /api to my Service" — and shouldn't need permission to touch the load balancer config to do it.

Gateway API splits that into three resources along exactly that boundary:

  • GatewayClass — the controller/implementation (cluster-scoped, usually platform-owned) — traefik, in this cluster.
  • Gateway — one real listener: a protocol, a port, a hostname — the shared infrastructure, platform-owned.
  • HTTPRoute (or GRPCRoute, TCPRoute, ...) — the actual routing rules, attached to a Gateway, app-team-owned, living in the app's own namespace.

Ownership split by resource, not by convention

Platform team owns this

GatewayClass traefik
Gateway web-gateway :80
↓ attaches to

ns: team-api

HTTPRoute api-route
match: /api

ns: team-blog

HTTPRoute blog-route
match: /blog
GatewayClass and Gateway are platform-owned, cluster/shared scope. Each HTTPRoute lives in its own app team's namespace and only needs permission on that one object to attach to the shared Gateway.

Why this is the one SIG Network points you toward

Three things Ingress structurally can't do well, which is why it's the recommended Ingress successor, not just an alternative flavor of the same idea:

  1. Role separation that RBAC can actually enforce — an app team can create HTTPRoutes in their own namespace without ever touching the Gateway, because they're different objects with different owners.
  2. Portable advanced routing. Header matching, traffic splitting (weighted backends for canaries), and request mirroring are typed fields on HTTPRoute — standard API, not per-controller annotations. The rate-limit problem from last lesson doesn't exist here for anything the spec covers.
  3. One Gateway, many protocols and route kinds — HTTP, gRPC, raw TCP — through one shared listener set, instead of Ingress's HTTP-only model bolted onto by annotation for everything else.

What stays the same

The controller/resource split you already know is identical: a GatewayClass with no controller behind it does nothing, just like an Ingress with no controller. Traefik implements Gateway API here the same way it implements Ingress — same binary, same Service, different watch loop.

The infrastructure analogy

Think of the old single Ingress object as one person holding both the network team's F5/ALB config and every app team's URL rules in one file everyone edits. Gateway API is what happens when you actually split that by team, with the platform team's layer enforced by Kubernetes RBAC instead of a change-review process.

In the lab, you'll build the same routing outcome as last lesson's Ingress lab — a Gateway plus an HTTPRoute — and verify it the same way, from inside the cluster.

🧪 Lab: lab-17-gateway-api

Preview only

Goal

Build the same two-path routing outcome as the Ingress lab, through Gateway API's three-resource split instead — and fix the same style of wrong-backend bug, now in an HTTPRoute.

Tasks

  1. Apply the starting manifests: kubectl apply -f manifests/
  2. Check everything landed: kubectl get gateway,httproute,pods -n lab-17-gateway-api
  3. Check the Gateway itself is accepted by Traefik: kubectl describe gateway web-gateway -n lab-17-gateway-api — look for Accepted: True in the status conditions.
  4. Test /blog from inside the cluster (already correct): 
    kubectl exec -n lab-17-gateway-api client -- wget -q -O- \
  --header="Host: gw.example.com" \
  http://traefik.traefik-system.svc.cluster.local/blog
    Expect hello from blog-backend.
  5. Test /api the same way — you'll get hello from blog-backend again. Same bug as the Ingress lab, same lesson: a backendRef is just a name and a port, and nothing validates it points where you meant.
  6. Open manifests/httproute.yaml, find the comment, and fix the /api rule's backendRef to point at api-svc, port 8080.
  7. Re-apply: kubectl apply -f manifests/httproute.yaml
  8. Re-test /api — expect hello from api-backend.

Check

Run the check once both paths return their correct backend's text.

This lab runs against a real local Kubernetes cluster with an automated grader — clone the repo and run make start to do it for real.

📝 Quiz

1. Which of these are the three core Gateway API resources? (select all that apply)

2. A platform team wants app teams to add their own routing rules without ever being able to touch shared TLS/listener config. How does Gateway API make this enforceable?scenario

3. Why is weighted traffic splitting (e.g. 90% v1 / 10% v2 for a canary) more portable in Gateway API than in Ingress?

4. You create a GatewayClass, a Gateway, and an HTTPRoute, but no controller in the cluster implements that GatewayClass's controllerName. What happens?scenario

5. Why does Kubernetes SIG Network specifically recommend Gateway API as a destination for ingress-nginx users, rather than just 'pick any other Ingress controller'?

Progress isn't saved in this preview — run the course locally to track completion and grade labs for real.