What is Gateway API in Kubernetes? A plain explainer

Gateway API is the Kubernetes project's answer to "how do I get traffic from outside the cluster to my Services?". It is a set of API kinds (GatewayClass, Gateway, HTTPRoute, GRPCRoute and others) that describe load balancers and routing rules in a portable way, and the Kubernetes docs now recommend it over Ingress.
It's also on the exams. The CKA's Services & Networking domain includes "Use the Gateway API to manage Ingress traffic", and the new CKNE goes further, with Gateway, HTTPRoute and TLS certificates for Gateway API in two of its domains. If you learnt Kubernetes networking on Ingress, this is the explainer to read before you book.
Key points
- Gateway API is an official Kubernetes project for L4 and L7 routing, delivered as custom resources (CRDs) that you install, not built into the core API.
- It splits the job between roles: the infrastructure provider (GatewayClass), the cluster operator (Gateway) and the application developer (routes such as HTTPRoute).
- Gateway, GatewayClass and HTTPRoute are stable, in the API group
gateway.networking.k8s.io/v1. - The Ingress API is frozen: still GA and not being removed, but it won't get new features.
- Moving from Ingress is a one-time conversion; Gateway API doesn't include an Ingress kind.
Why Ingress wasn't enough
Ingress gave Kubernetes one simple object: hostnames and paths in, Services out. Anything beyond that (header matching, traffic splitting, timeouts) was left to each controller, usually through annotations. The same YAML behaved differently on different controllers, and one team's annotations could affect everyone sharing the load balancer.
The docs now say it plainly: "The Ingress API has been frozen." It stays GA under the usual stability guarantees, and the project has no plans to remove it, but there will be no further changes.
The controller side has moved too. The Ingress NGINX project, which many clusters used, ended best-effort maintenance in March 2026, with no further releases or security fixes after that. Existing installations keep running, but new work is going to Gateway API implementations.
How Gateway API is organised
The design is role-oriented. The Gateway API docs describe three personas: an infrastructure provider, a cluster operator and an application developer. Each one owns a different resource, so a developer can change routes without touching the load balancer.
| Kind | Who usually owns it | What it does |
|---|---|---|
| GatewayClass | Infrastructure provider | Names the controller that implements a type of gateway |
| Gateway | Cluster operator | An instance of traffic-handling infrastructure, such as a cloud load balancer, with its listeners |
| HTTPRoute | Application developer | Rules that map HTTP requests from a Gateway listener to backends |
| GRPCRoute | Application developer | The same for gRPC traffic |
A Gateway is linked to exactly one GatewayClass. Routes attach to a Gateway through parentRefs, and the Gateway's listeners decide which routes may attach. The docs call this a "bidirectional trust model": the route asks to attach, and the Gateway has to allow it.
What it looks like in YAML
These three manifests are adapted from the Kubernetes documentation. First, the class, usually installed with your implementation:
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
name: example-class
spec:
controllerName: example.com/gateway-controller
Then a Gateway that listens for HTTP on port 80 for one hostname, and only accepts routes from its own namespace:
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: example-gateway
namespace: example-namespace
spec:
gatewayClassName: example-class
listeners:
- name: http
protocol: HTTP
port: 80
hostname: "www.example.com"
allowedRoutes:
namespaces:
from: Same
Finally, an HTTPRoute that sends /login to a Service:
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: example-httproute
namespace: example-namespace
spec:
parentRefs:
- name: example-gateway
hostnames:
- "www.example.com"
rules:
- matches:
- path:
type: PathPrefix
value: /login
backendRefs:
- name: example-svc
port: 8080
No addresses field on the Gateway means the controller assigns one. Check it with kubectl get gateway -n example-namespace, and read the status conditions on both the Gateway and the route when something doesn't connect.
How a request flows
For a Gateway implemented as a reverse proxy, the docs describe the flow like this:
- The client resolves the hostname to an address that belongs to the Gateway.
- The proxy matches the request's
Host:header to configuration built from the Gateway and its attached HTTPRoutes. - It can match on headers and paths, and change the request (add or remove headers) using the route's filters.
- It forwards the request to one or more backends.
From there, normal Service routing takes over. Gateway API decides which Service; kube-proxy or your CNI decides which Pod.
Common mistakes
- No CRDs. Gateway API isn't part of a plain cluster. Install the CRDs, or follow your implementation's install steps, or
kubectl applywill tell you the kind doesn't exist. - Cross-namespace routes. By default a Gateway only accepts routes from its own namespace. A route in another namespace needs
allowedRouteson the listener to permit it. - Reading
kubectl getalone. The route'sstatus.parentsconditions tell you whether it was accepted and whether its backends resolved. Look there first.
Pro tip: practise with one implementation end to end (install, GatewayClass, Gateway, route, curl) until you can do it without the docs open. In a performance-based exam, the time goes on debugging, not on typing YAML.
What this means if you're studying
For the CKA, expect to work with both: Ingress controllers and Ingress resources are still in the curriculum, next to Gateway API. Be comfortable writing an HTTPRoute from scratch and fixing one that isn't attached.
For the CKNE, Gateway API appears in "Managing Traffic with the Gateway API (Gateway, HTTPRoutes)" and in "Managing TLS Certificates for Gateway API". Go beyond the basics there: HTTPS listeners, certificate references and cross-namespace rules.
If you'd like someone who has already passed to look over your study plan, our mentors page is a good place to start.
FAQ
Is Ingress deprecated? No. It's frozen, not deprecated. Ingress stays GA and the project has no plans to remove it, but it won't change, and the docs recommend Gateway API instead.
Is Gateway API only for traffic coming into the cluster? No. The project covers L4 and L7 routing, and its GAMMA work uses the same route kinds for service-to-service (mesh) traffic.
Do I need a service mesh to use Gateway API? No. You need an implementation (a controller) that supports it. Many ingress controllers, load balancers and meshes do.
Can I convert my Ingress objects automatically? The docs describe the move as a one-time conversion and link to a migration guide. Conversion tools exist, but review what they produce, especially controller-specific annotations that have no direct equivalent.
Which API version should I use?
gateway.networking.k8s.io/v1 for GatewayClass, Gateway, HTTPRoute and GRPCRoute.
Spin up a lab cluster, install one implementation, and route your first request through a Gateway today.
Sources
- Gateway API (Kubernetes docs)
- Ingress (Kubernetes docs)
- Gateway API documentation (Kubernetes SIG Network)
- Ingress NGINX Retirement: What You Need to Know (Kubernetes blog, 11 November 2025)
- Certified Kubernetes Administrator (CKA) (Linux Foundation)
- Certified Kubernetes Network Engineer (CKNE) (Linux Foundation)