The King is Dead? Why NGINX Ingress Users Must Move to Gateway API
The writing is on the wall: The community NGINX Ingress Controller is slowing down. Here is your survival guide for the Gateway API migration, why role-based routing is the future, and how to start without breaking production.
If you have been running Kubernetes for more than a week, you have almost certainly used the NGINX Ingress Controller (kubernetes/ingress-nginx). It is the de facto standard, the "trusty workhorse" of the ecosystem.
For teams already focusing on advanced networking like Cilium and Hubble, the transition to Gateway API is the logical next step. But if you have been paying attention to the SIG Network updates, you know the wind has shifted. The future is Gateway API.
The community NGINX Ingress Controller is effectively entering a maintenance phase. The future is Gateway API.
At Coding Protocols, we are helping dozens of clients navigate this transition. Here is everything you need to know about why this is happening and how to prepare.
The Architecture Problem
The original Ingress API was revolutionary in 2015, but it had a fatal flaw: it tried to do too much in one object.
The Old Way: Ingress
An Ingress resource combines Load Balancing, Routing Rules, and TLS Termination into a single config.
- The Problem: If a developer makes a syntax error in an annotation (like
nginx.ingress.kubernetes.io/rewrite-target), they can potentially break the entire controller unless validaters are perfect. - The Annotation Hell: Every advanced feature (Rate Limiting, Header manipulation) became a custom string annotation. It was messy and vendor-specific.
The New Way: Gateway API (Role-Oriented)
Gateway API solves this by splitting the responsibilities into a clean linear flow.
It splits concerns into separate resources:
- GatewayClass: "What infrastructure powers this?" (e.g.,
cilium,envoy,istio). - Gateway: "Where does traffic enter?" (Owned by Platform Ops).
- HTTPRoute: "How do I route traffic to my pods?" (Owned by App Developers).
This isn't just a syntax change; it's a fundamental shift to a safer, multi-tenant model.
Mapping Features: Where did my Annotations go?
The good news is that Gateway API makes standard features native fields instead of annotations.
| Feature | NGINX Ingress (Old) | Gateway API (New) |
|---|---|---|
| Traffic Splitting | nginx.ingress.kubernetes.io/canary-weight | Native weights in backendRefs |
| Header Matching | Annotations (Limited) | Native matches.headers |
| Cross-Namespace | Not supported (mostly) | Native ReferenceGrant |
| TLS | Mixed with Routing | Separated in Gateway listeners |
How to Migrate (Without Downtime)
The most common fear we hear is: "Do I have to rip out NGINX and break everything?"
No. In fact, please don't. The migration strategy we recommend is Side-by-Side operation.
Step 1: Install a Gateway Controller
You don't need to remove NGINX. You can install a Gateway API implementation (like Envoy Gateway or Cilium) alongside it. They will listen on different LoadBalancer IPs.
Step 2: Use ingress2gateway
Don't rewrite thousands of lines of YAML manually. The Kubernetes SIG-Network team actively maintains a tool called ingress2gateway.
# From cluster: convert ingresses in current namespace
ingress2gateway print --providers=ingress-nginx
# From file: convert a local manifest
ingress2gateway print --providers=ingress-nginx --input-file=old-ingress.yamlCheck the ingress2gateway docs for the latest CLI; provider names include ingress-nginx and nginx. This tool is surprisingly good at converting complex annotation-laden Ingress resources into clean HTTPRoute objects.
Step 3: DNS Cutover
Once your HTTPRoute is valid and the backend is healthy, you simply update your DNS (or external load balancer) to point to the new Gateway IP. If anything breaks? Revert DNS. Zero downtime.
Our Recommendation
- Starting a new cluster? Use Gateway API immediately. Do not install the legacy Ingress controller.
- Existing cluster? Don't panic. NGINX Ingress isn't disappearing tomorrow. But stop adding new complexity to it. Start planning your migration for 2026.
The "King" (Ingress) served us well. But the "Republic" (Gateway API) is here, and it’s a much better way to govern your traffic.
Frequently Asked Questions
Is the NGINX Ingress Controller officially deprecated?
Not officially deprecated, but it has entered a maintenance-heavy phase. Most new networking innovations in Kubernetes are happening within the Gateway API spec. While NGINX will be around for a long time, it is no longer the recommended choice for new, complex clusters.
Can I run both Ingress and Gateway API at the same time?
Yes. You can install a Gateway API controller alongside your existing NGINX Ingress controller. They can live in the same cluster and even serve the same applications during a blue-green migration phase.
What is the most significant benefit of Gateway API?
Role-based delegation. It explicitly separates the infrastructure configuration (Gateway) from the application-level routing (HTTPRoute). this enables a "Platform Engineering" model where Ops manages the LB and developers manage their own routing rules without breaking each other.
Does Gateway API replace Service meshes like Istio?
No, it complements them. Many service meshes now use Gateway API as their primary configuration language for ingress and egress traffic. It provides a standard way to interact with whatever networking backend you choose.
Need help with your Ingress Migration?
Contact us at Coding Protocols. We have migrated massive production clusters to Gateway API without dropping a single packet.
