Migrating from ingress-nginx to the Gateway API

A cluster network that is secure and future-proof? WZ-IT plans and operates Kubernetes networks: CNI, Gateway API, load balancing, DNS and TLS - and private access via NetBird instead of unnecessary public exposure. See Network & Secure Access

If your Kubernetes cluster routes HTTP traffic through ingress-nginx, this has become an urgent migration topic. The community project has been retired, and there are no more security patches. Roughly half of all Kubernetes clusters are affected. This guide shows what happened, why the Gateway API is the right successor - and how to migrate without downtime. As of July 2026.

Table of contents

• What happened: the end of ingress-nginx
• Why not just another ingress controller
• The Gateway API in five minutes
• The migration path
• Zero-downtime cutover
• Four pitfalls

What happened: the end of ingress-nginx

On 11 November 2025, SIG Network and the Security Response Committee announced the retirement of ingress-nginx (Kubernetes blog). The core: best-effort maintenance ran only until March 2026. After that there are "no further releases, no bugfixes, and no updates to resolve any security vulnerabilities that may be discovered" - so no releases, no bugfixes and no security patches.

Existing installations keep working technically, and the artifacts remain available. But that is no reason to wait: in a reinforcing statement on 29 January 2026, the committee made clear that staying on ingress-nginx after its retirement leaves operators and users open to attack (statement). The background explains the urgency: a controller that accepts traffic in about half of all clusters was maintained for years by only one or two volunteers.

An important distinction, because it is often confused: only the community project kubernetes/ingress-nginx has been retired. The commercial F5 NGINX Ingress Controller (nginxinc/kubernetes-ingress) is its own, still-maintained product. And NGINX Gateway Fabric, F5's Gateway API implementation, is yet another project. Confusing the three leads to the wrong migration decision.

Why not just another ingress controller

The obvious reflex is to replace the retired controller with a different ingress controller. Short term that works - long term it only defers the problem.

The Ingress API itself is frozen. It remains as a GA resource and is not removed, but no new features are added. All active development in Kubernetes networking happens in the Gateway API. Ingress was never very expressive either: almost every function beyond simple host/path routing had to be expressed through controller-specific annotations - exactly what makes switching between controllers so tedious.

Since replacing ingress-nginx entails migration work anyway, the economically sensible decision is to move straight to the successor standard rather than migrate again in a year.

The Gateway API in five minutes

The Gateway API is not a beta experiment: it has been GA since v1.0 on 31 October 2023 and thus stable for over two years; the current version is v1.5 (Kubernetes blog). For production, the Standard channel applies (stable v1 resources only).

Instead of a single Ingress resource, the Gateway API works with several clearly separated object types:

• GatewayClass - the template provided by an infrastructure provider or controller.
• Gateway - the concrete entry point (listeners, ports, TLS), managed by cluster operations.
• HTTPRoute (as well as GRPCRoute, TLSRoute) - the application's routing rules, managed by the respective team.

Behind this sits a role model: the infrastructure provider owns the GatewayClass, cluster operations own the Gateway including TLS termination, and application teams own their HTTPRoutes. This replaces Ingress's old self-service model, which worked poorly in shared clusters. The core is also more expressive - header and method matching, weighted traffic splitting and cross-namespace routing are part of the standard, not of proprietary annotations - and portable across implementations.

The migration path

The switch runs in four steps:

1. Inventory. Capture all Ingress resources and - crucially - the ingress-nginx annotations in use. It is precisely those annotations that determine the effort.

2. Choose the target controller. Conformant, production-relevant options include Envoy Gateway, Cilium Gateway API, Traefik, kgateway (formerly Gloo) and NGINX Gateway Fabric. The definitive selection aid is the official conformance list. For sovereign, self-hosted clusters, Cilium is attractive when it already runs as the CNI; Envoy Gateway is a neutral entry point without ties to a particular data path.

3. Convert with ingress2gateway. The official tool kubernetes-sigs/ingress2gateway translates Ingress resources and many provider annotations into Gateway and HTTPRoute - from the running cluster or from manifest files. Besides ingress-nginx it also supports cilium, istio, traefik, kong and others (README).

4. Rework manually - the actual effort. ingress2gateway is explicitly not intended to copy all annotations. Standard cases like canary weight, rewrite-target, redirects, proxy-body-size, CORS or source-range filters are translated. Not covered, and therefore to be rebuilt, are among others: external authentication (auth-url/auth-*), rate limiting, rewrite-target with capture groups ($1), configuration-snippet/server-snippet (raw NGINX config), and canary-by-cookie and canary-by-header-pattern. These functions are reproduced via the implementation-specific policies and filters of the chosen target controller - which is why the controller choice determines the concrete migration path.

Zero-downtime cutover

The downtime-free switch relies on the fact that Ingress and Gateway API are independent APIs with their own controllers and that a new Gateway gets its own LoadBalancer IP. Both therefore run in parallel without issue. The official migration guide deliberately does not cover a live migration - the following pattern is established practice:

1. Deploy the new Gateway API controller and Gateway - a dedicated LB IP is created.
2. Rebuild routes as HTTPRoute (base via ingress2gateway, then review and augment manually).
3. Attach certificates to the Gateway (typically via cert-manager).
4. Test end-to-end on the new IP before redirecting users.
5. Shift traffic - via a DNS cutover with a low TTL or via weighted traffic splitting across a HTTPRoute's backendRefs weights.
6. Remove the old Ingress only after a burn-in period, so a fast way back stays open.

A bare-metal note: Kubernetes 1.36 marked Service.externalIPs as deprecated (due to CVE-2020-8554). Anyone using externalIPs as a "poor man's load balancer" so far should put the load-balancing foundation cleanly on type: LoadBalancer (such as MetalLB) first, and only then set up the Gateway on top.

Four pitfalls

• No drop-in replacement. The Kubernetes committee says it itself: "None of the available alternatives are direct drop-in replacements." The effort lies in the annotations that do not carry over - external auth, rate limiting, snippets and capture-group rewrites must be rebuilt.
• Never apply the ingress2gateway output blindly. The tool emits only Gateway and HTTPRoute and warns on unsupported annotations. Every result must be reviewed and tested.
• Conformance is not feature parity. A conformant controller masters the Gateway API but not automatically every ingress-nginx function. Check against your own feature list before choosing.
• A new LB IP means DNS and certificate planning. Without parallel operation and a planned cutover, the migration turns into an outage.

Anyone tackling the migration anyway should use the moment to avoid exposing internal services and the cluster API publicly in the first place, and instead make them reachable privately via NetBird. The second big lifecycle change in 2026 concerns packaging: migrating from Helm 3 to Helm 4.