5 examples of what you can do with Kubernetes Gateway API

Today, I want to guide you through a brief look at the Kubernetes Gateway API, which offers a flexible set of tools for managing and routing traffic, giving you more control than Ingress alone can provide.

In this article, we’ll cover five practical examples of what you can do with the Kubernetes Gateway API, showing you how it goes beyond Ingress’ capabilities.

Some quick context before we look at the examples

Normally, to access an application running inside a Kubernetes cluster, you use a Kubernetes Service. One example is a NodePort service, which allows external communication with pods via a specific port on any node’s IP address.

Fig.1: NodePort services allow external communication with pods via a specific port

To make applications accessible from outside the cluster, additional network configuration is often required, depending on your environment (cloud or on-premise).

Fig.2: An example of making applications accessible from outside the cluster

Kubernetes Ingress offers basic HTTP routing, forwarding requests with paths like /blog, /docs, or /stats to different services. But when more complex routing or traffic control is required, the Gateway API is a better fit.

Fig.3: Ingress offers basic HTTP routing, forwarding requests with paths like /blog, /docs, or /stats

So, what is the Gateway API?

The Gateway API introduces a more extensible and role-specific model for traffic routing. It separates infrastructure (Gateways) from routing logic (HTTPRoutes), allowing better scalability, reusability, and configuration flexibility.

Let’s walk through five of the ways you can use the Gateway API.

1. HTTP Path-Based Routing

To replicate a typical Ingress scenario with the Gateway API, start by creating a Gateway object that represents the network component handling traffic (e.g., a load balancer). Each Gateway includes a list of listeners that define the ports and protocols to be used.

Next, attach HTTPRoute objects to this Gateway. Each route can define hostnames and rules that match HTTP paths. For example:

Requests to myapp.mydomain.com/blog route to the blog service
Requests to /docs go to the docs service
Requests to /stats go to the stats service

This setup allows clean, URL-based routing to services from right inside the cluster.

2. Routing Based on HTTP Headers

The Gateway API allows you to match routes based on HTTP headers, not just paths. A common use case is on device content rendering. For instance, if a web app serves different views for mobile and desktop users, you can inspect the User-Agent header to identify mobile devices.

Using a regular expression, you can match keywords like Android, iPhone, or Mobile and route such traffic accordingly. This provides context-aware routing that Ingress alone can’t handle.

Fig.4: match routes based on HTTP headers

3. Routing by HTTP Method

Let’s say you’ve rolled out a new API version (v2) but want to allow only safe GET requests initially. With the Gateway API, you can define HTTP method-specific rules in your route configuration.

Only GET requests will be forwarded to api/v2, while other methods like POST or DELETE are denied. This lets you roll out changes incrementally and more safely.

Fig.5: Only GET requests will be forwarded to api/v2

4. Header Modification for Manual Testing

Suppose you’re conducting a manual test and want to bypass standard authentication. The Gateway API allows you to inject custom headers into HTTP requests before they hit the backend.

For example, you can automatically add an Authorization header containing encoded test credentials for all traffic to myapp.mydomain.com/test. This simplifies testing workflows and avoids modifying the app itself.

5. Traffic Splitting for Canary Deployments

Another feature of the Gateway API is traffic splitting. When deploying a new app version, you can run both the stable and the canary version simultaneously and route a percentage of traffic (e.g., 5%) to the new version.

By listing multiple backends and assigning them weights, you can control traffic distribution, which is something not possible when running standard Ingress.

Fig.6: When deploying a new app version, you can run both the stable and the canary version simultaneously

Bonus: Redirects and Beyond

The Gateway API also supports:

Request redirection: Send HTTP responses with a new location header (useful for URL restructuring).
URL rewriting
Query parameter matching
Request mirroring
Protocol support beyond HTTP: including TCP, UDP, TLS, and gRPC

These capabilities make the Gateway API a comprehensive tool for advanced traffic management in Kubernetes. Our video tutorial explains how to implement these uses yourself.