Kubernetes Ingress has been the default way to route HTTP(S) traffic into clusters for years. But as more complex use cases emerged—like advanced traffic splitting, richer policy controls, and cross-namespace delegation—it became clear Ingress alone wasn’t enough.

Enter the Gateway API, a modern, expressive standard designed to replace Ingress over time.

In this article, you’ll learn:

• What the Gateway API is
• How it differs from Ingress
• Common configuration patterns
• Migration strategies
• Why it’s worth adopting

What Is the Gateway API?

The is a set of Kubernetes resources designed to model Layer 4–7 routing in a portable, extensible way. It offers:

✅ Role-oriented resources (separate configuration for infrastructure and application teams)
✅ Rich traffic controls (e.g., header-based routing, traffic splitting)
✅ CRD-based extensibility
✅ Future replacement for Ingress

Gateway API resources include:

• GatewayClass – Defines a kind of load balancer or gateway implementation.
• Gateway – Instantiates a GatewayClass; binds to IPs and ports.
• HTTPRoute – Configures routing rules for HTTP(S) traffic.
• TCPRoute, UDPRoute, TLSRoute – For non-HTTP protocols.
• ReferenceGrant – Allows safe cross-namespace references.

Ingress Recap: What We Had Before

A Kubernetes Ingress resource looks like this:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: my-ingress
spec:
 rules:
 - host: example.com
 http:
 paths:
 - path: /app
 pathType: Prefix
 backend:
 service:
 name: app-service
 port:
 number: 80

Limitations:

• Only supports HTTP(S).
• No native traffic splitting or weight-based routing.
• Limited cross-namespace delegation.
• Hard to separate infrastructure and application concerns.

Gateway API Example

A comparable Gateway API configuration splits concerns into:

1️⃣ GatewayClass (the gateway implementation):

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
 name: my-gateway-class
spec:
 controllerName: example.net/gateway-controller

2️⃣ Gateway (the actual Gateway):

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
 name: my-gateway
spec:
 gatewayClassName: my-gateway-class
 listeners:
 - name: http
 protocol: HTTP
 port: 80
 hostname: "*.example.com"

3️⃣ HTTPRoute (the routing rules):

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
 name: app-route
spec:
 parentRefs:
 - name: my-gateway
 rules:
 - matches:
 - path:
 type: PathPrefix
 value: /app
 backendRefs:
 - name: app-service
 port: 80

Key Differences: Gateway API vs Ingress

Why this matters:
Gateway API enables clean separation: platform teams manage Gateways, app teams manage Routes.

Migration Patterns

Here’s how you can start migrating Ingress to Gateway API safely:

✅ 1. Evaluate Your Ingress Controller Support

Leading controllers (e.g., NGINX, Contour, Traefik) already have Gateway API support.

✅ 2. Start with HTTPRoute

Create GatewayClass, Gateway, and HTTPRoute resources equivalent to your Ingress rules.

✅ 3. Validate Functionality

Test routes, TLS termination, and traffic policies in staging.

✅ 4. Migrate Incrementally

Migrate Ingress resources gradually. Both Ingress and Gateway API can coexist.

✅ 5. Automate Translation

Use tools like kubectl-gateway-api or custom scripts to convert Ingress YAML to Gateway resources.

Example: Traffic Splitting with Gateway API

This scenario is hard to do with Ingress alone:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
 name: rollout-route
spec:
 parentRefs:
 - name: my-gateway
 rules:
 - matches:
 - path:
 type: PathPrefix
 value: /
 backendRefs:
 - name: v1-service
 port: 80
 weight: 80
 - name: v2-service
 port: 80
 weight: 20

Here, 20% of traffic goes to v2-service, enabling progressive rollout.

Best Practices

✅ Use distinct GatewayClasses for different controller types
✅ Namespace scoping for team isolation
✅ Apply ReferenceGrant for cross-namespace access
✅ Leverage status fields to monitor readiness

Resources and Further Reading

Conclusion

While Ingress has served Kubernetes well, the Gateway API is the new standard for traffic management, enabling more flexible, expressive, and secure routing in modern clusters. As controllers mature, now is an excellent time to begin exploring and migrating.