Skip to content
CertDirectory.io

Limited Time: 40% OFF all Linux Foundation Certifications. Save now

Back to the blog
Glossary6 min read

What is Gateway API in Kubernetes? A plain explainer

Sajeeva Nambadawa Vithanage19 Nov 2026 · Senior Software Site Reliability Engineer

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:

  1. The client resolves the hostname to an address that belongs to the Gateway.
  2. The proxy matches the request's Host: header to configuration built from the Gateway and its attached HTTPRoutes.
  3. It can match on headers and paths, and change the request (add or remove headers) using the route's filters.
  4. 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 apply will 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 allowedRoutes on the listener to permit it.
  • Reading kubectl get alone. The route's status.parents conditions 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