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 Gateway API 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
| Feature | Ingress | Gateway API |
|---|---|---|
| Protocol Support | HTTP(S) only | HTTP, TCP, UDP, TLS |
| Traffic Splitting | Limited via annotations | Native support |
| Cross-Namespace Delegation | Not standardized | Supported via ReferenceGrant |
| Role Separation | Single resource | Multiple resource roles |
| Extensibility | Controller-specific | Standardized CRD extensions |
| Maturity | Stable | GA since Kubernetes v1.27+ |
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.
