A migration from ingress-nginx to Gateway API is less about YAML than about planning. Converting Ingress objects is largely automated. The real work is in three places:
- the annotations and configuration snippets nobody remembers adding
- the things ingress-nginx did for you implicitly
- the moment traffic moves to the new gateway
Plan for those, and the migration is routine.
Why now: the Kubernetes project retired ingress-nginx on March 26, 2026, so it no longer receives security fixes. For healthcare, fintech and government, an unpatched component on the edge of every cluster is a compliance issue, not only a technical one.
We are migrating every cluster we manage from ingress-nginx to Gateway API with Envoy Gateway. This article describes how we approach it, in five phases. If you first want to know why Gateway API is different and why ListenerSet matters, read Gateway API vs. Ingress.
1. Choose a cutover strategy
Decide first how traffic will move, because it determines how you test and how you roll back. There are two options.
A new IP address. The Gateway runs next to ingress-nginx with its own IP. Applications move one at a time by changing their DNS records. Old and new stay fully separated, and you can test everything before production traffic arrives. The downside: you depend on DNS, and on anyone outside your team who has the old IP in a firewall rule or allowlist.
Gateway in front of ingress-nginx, same IP. The Gateway takes over the existing IP. Migrated applications are served by the Gateway directly; everything else is passed through to ingress-nginx behind it. Firewall rules, allowlists and partner integrations keep working, and teams migrate at their own pace.
| New IP address | Gateway in front, same IP | |
|---|---|---|
| External changes needed | DNS per application | None |
| Teams migrate | Per DNS change | Per application, at their own pace |
| Rollback | DNS change | Remove the new routes, or move the IP back |
| Main risk | Forgotten firewall rules and allowlists | The IP move itself |
For most of our customers, keeping the IP wins: there are always firewall rules, allowlists or partners that nobody wants to coordinate with.
Limiting the risk of the IP move.
- With the Gateway in front, ingress-nginx keeps running behind it with all Ingress objects intact.
- If the move fails, rollback is moving the IP back to the ingress-nginx service.
- Before the switch, check the cloud load balancer for anything attached to it that Kubernetes didn’t create.
- Do the move as a separate change, not bundled with other maintenance, and announce it to everyone who depends on the endpoint.
- Watch the load balancer service during the switch, not only the pods.
2. Find out what you are actually migrating
Hostnames, paths and TLS certificates convert mechanically. Annotations don’t.
The annotations fall into three groups:
- Standard features. Redirects, rewrites, header changes, timeouts and traffic splitting are part of Gateway API itself.
- Implementation-specific features. IP allowlists, rate limiting, authentication and CORS move to policy resources of your Gateway API implementation, such as Envoy Gateway’s
SecurityPolicyandBackendTrafficPolicy. - Things that need a decision. Configuration snippets with raw NGINX config, and ModSecurity WAF rules, have no one-to-one replacement.
In our experience, most snippets turn out to be header changes, redirects or rewrites that Gateway API handles natively. A few are workarounds for problems that no longer exist. Only a handful need an implementation-specific escape hatch.
For ModSecurity, there is no built-in equivalent. Coraza runs the same kind of rules on Envoy, as a Go filter, a Wasm plugin or a dynamic module. Plan the WAF as a separate component, with its own rule tuning and updates.
ingress2gateway converts Ingress objects to Gateway API resources and flags what it can’t translate. Use it as a starting point, not as the result.
3. Map to the new ownership model
With Ingress, one object held everything: hostnames, certificates, paths and controller settings. Gateway API splits that up:
- The platform team owns the Gateway: the proxy, its IP address and the shared baseline.
- Application teams own their hostnames and certificates (in a ListenerSet), their routing rules (in HTTPRoutes) and their policies. All of it lives in their own namespace.
ListenerSet started out in Gateway API’s experimental channel (v1.3) and needs a recent implementation: Envoy Gateway supports it from v1.7. Check the versions your cluster runs before you plan around it.
Decide this split before converting anything, because it determines which team changes what. On the clusters we manage, Guida owns the Gateways, and teams deploy their ListenerSets and routes through their own GitOps flow, the same way they deployed Ingress objects before.
4. Don’t lose what ingress-nginx did implicitly
This is the phase most teams underestimate, because nothing visibly breaks. ingress-nginx did a number of things by default or through global configuration. After the migration, each of these needs to be set explicitly:
- HTTP-to-HTTPS redirects. With ingress-nginx, they were on by default. With Gateway API, your application’s route is attached to the HTTPS listener, and the redirect is a separate route on the HTTP listener. Without that redirect route, visitors who type
http://or follow an old link get an error instead of your site. - Security headers. If HSTS, X-Frame-Options and similar headers were set globally, they disappear. Check your sites with securityheaders.com and internet.nl before and after; the scores should match.
- Network policies. With default-deny policies, traffic now comes from the Gateway’s proxy pods, not from ingress-nginx. Certificate renewal through Let’s Encrypt needs its own exception.
- Monitoring and logging. Metrics, dashboards and alerts built on ingress-nginx disappear with it. Access logs change format and field names, so saved log queries break too.
Put this list in every migration plan, and check it per application.
5. Test before traffic moves
Gateway API reports the status of every resource, so misconfigured routes show up immediately instead of failing silently. Use that first. Then test real requests against the new Gateway’s IP address before changing DNS or moving the IP, including TLS and redirects.
Make sure the new dashboards and alerts are in place before the switch. You want to see the first errors on the new gateway yourself, not hear about them from your users.
The bottom line
The tooling handles most of the conversion. What makes a migration go well is knowing which annotations you depend on, listing what ingress-nginx did implicitly, testing before traffic moves, and making the cutover its own change.
As part of Guida managed Kubernetes, we plan and run the migration: we manage the Gateways, dashboards and cutover, and help your team move its routes. If you are planning this migration, talk to one of our engineers.