Ingress-NGINX Retirement Migration Guide: Your 2026 Path Forward
Ingress-NGINX hit end-of-life in March 2026. A practical decision framework and cutover playbook for platform teams still running the retired controller on internet-facing workloads.
By VVV Ops
The community ingress-nginx controller reached end of life in March 2026. The last builds, controller-v1.15.1, v1.14.5 and v1.13.9, went out on 19 March 2026, and the repository was archived and made read-only on 24 March 2026. The Kubernetes SIG Network announcement was plain about what that means: no more releases, no bug fixes, no security updates. The Helm charts and images stay available so existing deployments keep running, but nobody is patching them. Any vulnerability disclosed from now on stays open on every cluster that still runs it. This guide is a decision framework and a cutover plan for platform teams that need to move off it without breaking production.
Why the retirement matters now
The maintainers were open about the cause: one or two people doing the work in their spare time, a steady stream of feature requests, and a configuration surface that had become a security liability, above all the snippet annotations that let users inject raw NGINX configuration. InGate, the planned successor, did not progress far enough and is being retired as well. Waiting for upstream is not a plan.
The first real test of that arrived seven weeks after the archive. CVE-2026-42945 was published on 13 May 2026 with a CVSS 4.0 base score of 9.2, and it sits in ngx_http_rewrite_module. The advisory describes the trigger precisely: a rewrite directive followed by a rewrite, if or set directive, with an unnamed PCRE capture such as $1 and a replacement string that contains a question mark. Unauthenticated HTTP requests can then overflow a heap buffer in the worker process and restart it, and the advisory notes code execution where ASLR is disabled or can be bypassed.
That configuration shape is what nginx.ingress.kubernetes.io/rewrite-target with a $1 capture generates. We are not claiming every cluster is exploitable, because the advisory itself puts conditions outside the attacker's control in the path, and nginx.org rates the bug medium where F5's CVSS 4.0 score says 9.2. The point is narrower. The vulnerable range runs from nginx 0.6.27 to 1.30.0, the fixes are 1.30.1 and 1.31.0, and no ingress-nginx image carries either, because the last one was cut 55 days before the CVE was published. There is nothing to upgrade to.
For an internet-facing cluster, running an unmaintained ingress controller means:
- New vulnerabilities in the controller stay unpatched. The ingress sits at the edge of the cluster, so these are the bugs attackers look for first.
- Your patch process cannot meet its own targets. Whatever window you hold yourself to for critical CVEs, there will be no patch to apply.
- Compliance work gets harder. NIST SP 800-53 has a control for exactly this case (SA-22, unsupported system components), and SOC 2 auditors ask how you handle vulnerabilities in third-party components. "No fix exists" is a finding, not an answer. Our Terraform security guide covers the same supply-chain argument for providers and modules.
Check your exposure:
kubectl get pods --all-namespaces \
--selector app.kubernetes.io/name=ingress-nginx \
-o wide
kubectl get ingressclass \
-o custom-columns=NAME:.metadata.name,CONTROLLER:.spec.controller
Any pod in the first list, or an IngressClass with the controller k8s.io/ingress-nginx, means this guide applies to you. Before moving traffic, make sure the rest of the cluster is in order. Our Kubernetes production readiness checklist covers resource limits, Pod Disruption Budgets and health checks, all of which an ingress migration will expose if they are missing.
Managed add-ons have their own clock
On EKS and GKE, the community controller is something your team installed, so March 2026 was the whole story. Azure is the exception worth checking before you plan anything, because AKS sold ingress-nginx as a managed add-on and kept patching it after upstream stopped.
Microsoft's migration guide states that it provides official support for critical security patches for application routing add-on NGINX Ingress resources through November 2026. The page gives a month and no day, which is worth raising with your account team if you are planning the last week. That window covers the add-on's own resources. A controller you installed from the community Helm chart on an AKS cluster has had no patch source since March, add-on or not.
The successor on AKS is the application routing Gateway API implementation, which runs a trimmed Istio control plane that reconciles only Gateway API resources under the approuting-istio GatewayClass, with no Istio CRDs and no sidecar injection. Both data planes can run on the same cluster, so the cutover is a DNS change rather than a swap. It needs Azure CLI 2.86.0 or later:
az aks update --resource-group "$RG" --name "$CLUSTER" --enable-gateway-api
az aks update --resource-group "$RG" --name "$CLUSTER" --enable-app-routing-istio
kubectl get gatewayclass approuting-istio
One detail will cost you an outage if you miss it. The two data planes get separate Azure Load Balancer frontend IPs, and there is no flag that moves the old IP to the new Gateway. AKS deletes the public IP it manages when the owning Service goes away, even when you have marked it Static. If a Front Door origin, a Traffic Manager endpoint or a customer firewall rule pins the ingress-nginx address, that upstream configuration has to change to the Gateway IP. Inventory those pins before you touch DNS, and remember the add-on can run more than one NginxIngressController, each with its own class and its own address.
Three realistic paths
There are many ingress controllers you could move to. For most teams the choice comes down to three:
- Gateway API with a conformant implementation such as Envoy Gateway, Istio, Cilium or Kong. This is the long-term direction for Kubernetes traffic management, with role separation between platform and application teams and built-in traffic splitting, header changes and multi-protocol routing.
- F5's NGINX Ingress Controller (the
nginx/kubernetes-ingressproject). It is a different project from the retired community controller, maintained by F5 with open-source and NGINX Plus editions, and F5 publishes a migration guide that maps community annotations to its own. - Traefik with its Kubernetes Ingress NGINX provider, which reads ingress-nginx annotations directly. It is the closest to a drop-in replacement and keeps your existing
Ingressresources working while you plan a longer-term move.
HAProxy, Contour, Kong's ingress controller and the cloud providers' controllers (AWS Load Balancer Controller, GKE Gateway, Azure Application Gateway for Containers) are valid choices too. They either fall into one of these three groups or fit a specific need, such as staying close to one cloud.
| Criterion | Gateway API | F5 NGINX Ingress Controller | Traefik with the NGINX provider | |---|---|---|---| | Time to first cutover | Longest | Short | Shortest | | Changes to existing Ingress resources | Rewrite to HTTPRoute | Annotation mapping per F5's guide | Most annotations read as they are | | Role separation between platform and app teams | Built in (GatewayClass, Gateway, HTTPRoute) | Annotation-based | Annotation-based | | Advanced routing (header rewrites, retries, mirroring) | Built in | Some features need NGINX Plus | Built-in middleware | | License | Open-source implementations | Open source, or paid NGINX Plus | Open source, or paid Traefik Hub | | Chance of a second migration later | Low | Low | Higher, if you outgrow annotations |
A rough rule: if you have a platform team and several application teams that submit their own ingress configuration, Gateway API repays the migration. If a small operations team has to keep dozens of Ingress resources working next week, Traefik or F5's controller gets you off the retired software faster. Do not let the long-term choice delay getting off unpatched software.
Gateway API: the long-term choice
Gateway API (gateway.networking.k8s.io/v1) reached general availability in October 2023. The model has three resources: a GatewayClass and a Gateway that the platform team manages, and HTTPRoute objects that application teams own. A typical HTTPS setup with Envoy Gateway:
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: public
namespace: edge
spec:
gatewayClassName: envoy-gateway
listeners:
- name: https
protocol: HTTPS
port: 443
tls:
mode: Terminate
certificateRefs:
- kind: Secret
name: wildcard-tls
allowedRoutes:
namespaces:
from: All
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: api
namespace: prod
spec:
parentRefs:
- name: public
namespace: edge
hostnames: ["api.example.com"]
rules:
- matches:
- path:
type: PathPrefix
value: /v1
backendRefs:
- name: api-v1
port: 8080
weight: 90
- name: api-v2
port: 8080
weight: 10
The weight field gives you traffic splitting without canary annotations. from: All lets routes in any namespace attach to this Gateway; in a shared cluster, use a namespace selector instead. The project's implementations page lists the conformant implementations and the versions they support.
The gap list has also shrunk since this guide first went up. Gateway API v1.7.0 promoted the HTTPRoute retry block (codes, attempts and backoff) to the Standard channel, with HTTPRouteRetryCodes and HTTPRouteRetryConnectionError as the Standard features. The release notes mark backoff as implementation-specific, because jitter differs between proxies. If nginx.ingress.kubernetes.io/proxy-next-upstream-tries was on your list of reasons to stay, check your implementation's support for those features before you accept the reason.
Converting Ingress resources with ingress2gateway
Hand-writing HTTPRoute for every Ingress is where teams stall, and SIG Network ships a tool for it. ingress2gateway reached v1.0.0 on 20 March 2026, and v1.2.0, from July 2026, is the current release. It reads Ingress resources from a cluster or from files and prints the equivalent Gateway API objects.
# Dry read of the whole cluster, in the default standard emitter
ingress2gateway print --providers=ingress-nginx -A
# From manifests in git, as kyaml, for an Envoy Gateway cluster
ingress2gateway print --providers=ingress-nginx \
--input-file ingress/prod.yaml \
--input-file ingress/staging.yaml \
--emitter envoy-gateway -o kyaml
Read the output before you apply it, for three reasons.
The default ingress class will skip most of your resources. --ingress-nginx-ingress-class defaults to nginx, so anything on a different class is quietly out of scope. Microsoft's guide calls this out for AKS, where the add-on classes are webapprouting.kubernetes.azure.com and whatever your extra NginxIngressController objects use. Run the tool once per class with --ingress-nginx-ingress-class=<class>, and count the output against kubectl get ingress -A before you believe it.
Annotations are translated, not carried. The README is explicit that the tool is not intended to copy annotations across, and the v1.0.0 notes list what it does understand: header manipulation, GRPC, canary routing, path rewriting, timeouts, SSL, permanent and temporary redirects, CORS, regex path matching, backend TLS, buffer sizing and IP access control. Anything outside that list is reported rather than dropped in silence: v1.0.0 added a notification system that says which annotations were parsed, unsupported or unrecognized. Those notifications are the real migration backlog, so capture them in a ticket rather than scrolling past them.
Pick the emitter that matches your target. standard produces vanilla Gateway API, and v1.0.0 added emitters for Envoy Gateway, kgateway, Agentgateway and GCE, and v1.2.0 added one for Airlock Microgateway. --allow-experimental-gw-api opens up experimental fields such as URLRewrite, which is worth knowing about and not worth shipping to production without a conformance check.
F5 NGINX Ingress Controller: the compatibility path
If converting every Ingress to HTTPRoute is not possible this quarter, F5's controller keeps the NGINX model with active maintenance and commercial backing. It has its own CRDs and its own annotations, and F5's migration guide maps the common community annotations; snippets and session affinity are usually where the manual work is.
Install it from F5's OCI chart under its own IngressClass. The current chart is 2.8.1, shipping controller v5.7.1:
helm install nginx-inc oci://ghcr.io/nginx/charts/nginx-ingress \
--version 2.8.1 \
--namespace nginx-inc \
--create-namespace \
--set controller.ingressClass.name=nginx-inc
Check the current chart version before you install; F5 releases often, and it also publishes an -lts- line if you would rather track that. One detail matters a lot during the cutover: F5's controller also processes Ingress resources that have no ingressClassName. Before installing it, set ingressClassName: nginx (the old controller's class) on every existing Ingress, so the two controllers do not both pick up unlabelled resources. Then move each service to ingressClassName: nginx-inc one at a time. Two controllers serving the same unlabelled resource is a classic source of intermittent 502s that never reproduce on demand.
Traefik with the NGINX provider: the drop-in path
Traefik's Kubernetes Ingress NGINX provider parses community ingress-nginx annotations, so you can install Traefik, enable the provider and leave your Ingress resources as they are. In the Traefik Helm chart:
# values.yaml for the Traefik Helm chart
providers:
kubernetesIngressNGINX:
enabled: true
ingressClass: nginx
controllerClass: k8s.io/ingress-nginx
If the standard Kubernetes Ingress provider is also enabled, limit it to other classes, otherwise both providers create routers for the same Ingresses. The trade-off with this path is that your traffic configuration is still written in the vocabulary of a retired project. Plan a follow-up move to Traefik's own IngressRoute resources or to Gateway API, and treat this as a bridge.
The cutover: parallel run, test, roll back
Whichever controller you choose, the cutover works the same way. Do not switch ingressClassName for everything at once.
- Install the new controller in parallel, with its own IngressClass and its own load balancer addresses. Run both for days, not minutes.
- Test the new path before users hit it. Point a low-TTL DNS record at the new load balancer and use synthetic checks or a header-based canary to confirm TLS, long-running connections and WebSockets work.
- Move one hostname at a time, the busiest last. Watch 5xx rates, p99 latency and connection errors on both controllers.
- Keep the old controller running for a few days after the last hostname moves. The rollback is changing the DNS record back, and that only works while the old controller is still there.
- Then remove the old controller and its IngressClass.
Lower the TTL on every hostname in scope before step 2, and wait out the previous TTL window in full. If the old value was an hour, that is an hour of waiting, or cached resolvers will keep sending clients to a controller you have already deleted. We run the same shape of node-by-node cutover for kube-proxy IPVS to nftables, and the pattern holds: the install is the small part of the job, and the careful cutover is where the time goes.
Common pitfalls
- Two controllers claiming the same
Ingress. Unlabelled resources are the usual cause. Give every existingIngressan explicitingressClassNamebefore the new controller starts. - Lost client IPs. Each controller handles
X-Forwarded-Forand the PROXY protocol in its own way. If your WAF or rate limits (Cloudflare, ModSecurity, AWS WAF) key on client IP, test it end to end after the cutover. We have seen rate limits quietly apply to the load balancer's address, which switches off abuse protection without any error. - Snippet annotations ignored.
nginx.ingress.kubernetes.io/configuration-snippetandnginx.ingress.kubernetes.io/server-snippetdo not carry over, and neither donginx.ingress.kubernetes.io/auth-url,nginx.ingress.kubernetes.io/limit-rpsornginx.ingress.kubernetes.io/limit-connectionsin the general case. Rebuild custom headers, redirects, external auth and rate limits as Gateway API filters, Traefik middleware or F5 policies before the cutover, and use theingress2gatewaynotifications to find the ones that were never written down. - Certificate renewals. On Gateway API, cert-manager needs Gateway API support enabled and an HTTP-01 solver of type
gatewayHTTPRoutethat points at your Gateway; an Issuer still configured for theingresssolver will not complete challenges. Let's Encrypt certificates last 90 days and renew 30 days before expiry, so a broken solver shows up about 60 days after the cutover. Test a renewal on purpose, instead of only checking that existing certificates still work. - Shared clusters where one Gateway serves several environments. Namespace selectors on
allowedRoutesare the control, and the hostnames and cluster-wide pieces need their own pass. Our notes on multiple environments on one Kubernetes cluster cover what a namespace boundary does not reach.
Each of these is quick to fix if the parallel run catches it, and a page at 3 AM if it does not.
Most teams find that more of their Ingress annotations were doing important work than anyone had written down, and that some applications relied on behaviour specific to ingress-nginx. Start with an inventory of annotations per namespace, run ingress2gateway against it, and read what it could not translate; that decides which path is realistic. For help scoping or running the migration, write to us about your clusters. The first call is free, and we will tell you which path we would take.