Life after Ingress NGINX

If your cluster still routes traffic through ingress-nginx, you are running a piece of software that no longer has anyone to fix it. The repository was archived on 24 March 2026. There will be no more releases, no bug fixes and — the part that matters — no security patches, for any vulnerability, ever again. Nothing broke on that date, which is exactly the problem: your ingress still works, so nothing forced you to act.

This is a migration guide written after the deadline rather than before it. It covers how to measure your exposure in four commands, how to pick a destination on evidence instead of vibes, the ingress-nginx behaviours that silently change meaning when you translate them, and a rollout sequence that lets you put the traffic back if the new data plane misbehaves.

What actually happened — and what did not

The timeline is short and worth getting exactly right, because a lot of secondhand commentary garbled it. Kubernetes SIG Network and the Security Response Committee announced the retirement on 11 November 2025. On 29 January 2026 the Steering Committee and the SRC escalated with an unusually blunt joint statement: “choosing to remain with Ingress NGINX after its retirement leaves you and your users vulnerable to attack”, and “none of the available alternatives are direct drop-in replacements”.^{[retire][steering]}

That last row is the one people get wrong most often. The Ingress API is not deprecated. The documentation states that it is generally available, that the project has no plans to remove it, and that it is simply frozen — no further changes or updates. Your networking.k8s.io/v1 Ingress objects are valid Kubernetes and will keep being valid. What died is one particular controller that reads them.^[ingressdoc]

What you inherit by staying

The clearest way to size the risk is to look at the security fixes the project shipped in its final weeks. On 2 February 2026 — four days after the Steering statement, seven weeks before the repository went read-only — the SRC disclosed four vulnerabilities in ingress-nginx: CVE-2026-1580, CVE-2026-24512, CVE-2026-24513 and CVE-2026-24514. The most serious were rated HIGH at 8.8, fixed in v1.13.7 and v1.14.3.^[advisory]

CVE-2026-24512 is the one to internalise. The rules.http.paths.path field of an Ingress could be used to inject configuration into NGINX, leading to arbitrary code execution in the context of the controller and disclosure of every Secret the controller can read — which, in a default install, is every Secret in the cluster. The interim mitigation was a validating admission controller that rejects Ingress objects using the ImplementationSpecific path type. Note what that class of bug requires from an attacker: the ability to create an Ingress. Anyone with namespace-level write access qualifies.^[cve24512]

Two more followed, and they matter for the argument. CVE-2026-3288, disclosed 9 March 2026 and rated HIGH at 8.8, was configuration injection through the rewrite-target annotation — the same annotation the semantics table below warns you about — fixed in v1.13.8, v1.14.4 and v1.15.0. Then CVE-2026-4342, disclosed 19 March 2026, scored 8.8 on the same vector: comment-based configuration injection, again reaching code execution in the controller and cluster-wide Secret disclosure. It was fixed in v1.13.9, v1.14.5 and controller-v1.15.1. That is the final release. The last thing this project ever shipped was a security patch, five days before the repository went read-only. Whatever comes next gets nothing.^{[cve3288][cve4342][lastrel]}

If you want the upper bound, CVE-2025-1974 — “IngressNightmare”, March 2025, CVSS 9.8 — is the precedent. The Kubernetes project described it in plain language: anything on the pod network had a good chance of taking over your cluster, with no credentials required. That one got a patch. The next one will not.^[nightmare]

Existing deployments will continue to work, so unless you proactively check, you may not know you are affected until you are compromised.^[steering]

On scale: the Steering Committee and SRC state that about 50% of cloud native environments rely on the controller, citing internal Datadog research. Treat that number as directional rather than precise — the underlying dataset is not public and reflects Datadog-monitored environments — but the order of magnitude is corroborated by the project's own 2025 figure of “over 40% of Kubernetes clusters”. Either way, this is not a niche cleanup task.

Find out whether you are affected

Before planning anything, measure. The first command is the one the Kubernetes project publishes; the other three tell you how much work you are actually looking at, because the cost of this migration is not the number of Ingress objects — it is the number of distinct annotations behind them.

# 1. The check the Kubernetes project itself publishes
kubectl get pods --all-namespaces \
  --selector app.kubernetes.io/name=ingress-nginx

# 2. Which controller image, and therefore which version, is actually running
kubectl get deploy -A -l app.kubernetes.io/name=ingress-nginx \
  -o jsonpath='{range .items[*]}{.metadata.namespace}{"\t"}{.spec.template.spec.containers[0].image}{"\n"}{end}'

# 3. How much surface you have to translate: every Ingress bound to it
kubectl get ingress -A \
  -o jsonpath='{range .items[*]}{.metadata.namespace}/{.metadata.name}{"\t"}{.spec.ingressClassName}{"\n"}{end}'

# 4. The real cost driver - the annotations, ranked by how often you use them
kubectl get ingress -A -o json \
  | jq -r '.items[].metadata.annotations // {} | keys[]' \
  | grep -F 'nginx.ingress.kubernetes.io/' | sort | uniq -c | sort -rn

That fourth command is the estimate. A cluster with sixty Ingress objects and four annotations is an afternoon. A cluster with twelve Ingress objects and twenty-two annotations — including configuration-snippet — is a project, and you have just found out why.

Choose the destination before you touch any YAML

There are three honest options, and the right one depends on how much of ingress-nginx's behaviour you actually depend on. Worth knowing before you shortlist: the only ingress controllers Kubernetes supports and maintains as a project are the AWS and GCE ones. Everything else on the documented list — Traefik, HAProxy, Contour, Kong, APISIX, Cilium, Higress, Istio and the rest — is third party. Note also that kubernetes/ingress-nginx is no longer on that page at all.^[ctrldoc]

If you go the Gateway API route, the current release is v1.6.0, tagged at the end of June 2026 and announced on 3 August 2026. TCPRoute and UDPRoute graduated from Experimental to Standard at v1 in that release, joining Gateway, GatewayClass, HTTPRoute, GRPCRoute, TLSRoute, ListenerSet, ReferenceGrant and BackendTLSPolicy. The v1alpha2 versions of TCPRoute and UDPRoute are deprecated as of v1.6 and will be removed. Install the current patch, v1.6.1 from 16 July 2026, not v1.6.0. On cluster versions, the project publishes no fixed floor — its stated policy is to support the five most recent Kubernetes minor versions, so check that against the cluster you are on rather than trusting a number from a blog post.^{[gw16][gw16rel][gw161][versioning]}

One structural change in v1.6 is worth planning around: new experimental resources now live in a separate API group, gateway.networking.x-k8s.io, with an X prefix on the type name — XBackend, XMesh. When one graduates it is renamed into gateway.networking.k8s.io and drops the prefix. That is a deliberate signal: if the kind you are about to depend on starts with X, it is not a production commitment.^[gw16]

Pick on evidence. The Gateway API project publishes per-release conformance reports listing exactly how many extended features each implementation passes, per route type. That table is a better shortlisting tool than any vendor comparison page, including this one — check the row for the version you intend to run, not the one from last year. Be aware that not every implementation submits a report for every release, so an absent row means “no report for this version”, not “not conformant”.^[conform]

Five behaviours that do not survive translation

This is where migrations go wrong, and it is worth reading even if you have already decided on a destination. ingress-nginx accumulated behaviours that were never in the Ingress spec, that your applications now silently depend on, and that no conformant Gateway API implementation reproduces. The Kubernetes project documented five of them specifically to save people this discovery.^[gotchas]

The trailing-slash redirect is the one that bites hardest in practice, because it does not fail loudly. Requests to /api that used to be redirected to /api/ now return 404 from the application, and the error surfaces in your service's logs rather than at the edge — so the first hypothesis is a bug in the service, not the migration you did last night.

ingress2gateway: what it converts, and what it refuses to

There is an official converter, and it is much better than it was. ingress2gateway reached 1.0 on 20 March 2026 as a SIG Network subproject. The headline change: ingress-nginx annotation coverage went from three annotations to over thirty, including CORS, backend TLS, regex matching and path rewriting. Version 1.0 also added controller-level integration tests that stand up a real ingress-nginx and a real Gateway API controller in live clusters and compare their runtime behaviour, rather than just diffing YAML.^[i2gblog]

# Install the official converter (Go 1.25.5 or newer to build from source)
go install github.com/kubernetes-sigs/ingress2gateway@v1.0.0
# or: brew install ingress2gateway

# Convert a manifest on disk, without touching the cluster
ingress2gateway print --input-file ingress.yaml \
  --providers=ingress-nginx > gwapi.yaml

# Convert one namespace from a live cluster
ingress2gateway print --namespace shop \
  --providers=ingress-nginx > gwapi.yaml

# Convert everything, and keep the warnings - they are the migration backlog
ingress2gateway print --all-namespaces \
  --providers=ingress-nginx > gwapi.yaml 2> unsupported.log

Nine providers are supported — ingress-nginx, nginx, traefik, kong, istio, apisix, cilium, gce and openapi — with six output emitters including envoy-gateway and kgateway. Its output targets Gateway API v1.5.0. What it will not do for you:^[i2g]

• configuration-snippet and server-snippet — unsupported, and no equivalent exists. Arbitrary NGINX directives were exactly the design decision the Kubernetes project named as the source of “insurmountable technical debt”. If your snippets encode business logic, that logic has to move into the application, a filter, or an implementation-specific policy CRD.^[retire]
• proxy-body-size — no Gateway API equivalent. Configure it on the data plane instead, which means it becomes implementation-specific and stops being portable.
• proxy-read-timeout / proxy-send-timeout — best-effort mapping to timeouts.request, which is not the same thing. Re-measure under load rather than assuming parity.
• URL normalisation — not configurable through standard Gateway API at all. If you were relying on it, you are relying on the data plane, and you need to verify per implementation.

Read the tool's warnings as your migration backlog, not as noise. Everything it prints to stderr is a behaviour it could not carry across, and every one of those is a production incident waiting for the DNS change.

Ingress and Gateway API, side by side

A minimal but realistic example: one hostname, TLS, and a path split between an API and a web front end. The point of putting them next to each other is that the Gateway API version is longer, and the extra length is not ceremony — it is the behaviour that ingress-nginx was giving you implicitly, now written down.

Before — one Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: shop-ingress
  namespace: shop
spec:
  ingressClassName: nginx
  tls:
    - hosts: [shop.example.com]
      secretName: shop-example-com-tls
  rules:
    - host: shop.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: api-service
                port:
                  number: 8080
          - path: /
            pathType: Prefix
            backend:
              service:
                name: web-service
                port:
                  number: 80

After — a Gateway and two HTTPRoutes

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: shop-gateway
  namespace: shop
spec:
  gatewayClassName: nginx          # must match an installed GatewayClass
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      hostname: shop.example.com
      allowedRoutes:
        namespaces:
          from: Same
    - name: https
      protocol: HTTPS
      port: 443
      hostname: shop.example.com
      tls:
        mode: Terminate
        certificateRefs:
          - group: ""              # empty string = core API group
            kind: Secret
            name: shop-example-com-tls
      allowedRoutes:
        namespaces:
          from: Same
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: shop-route
  namespace: shop
spec:
  parentRefs:
    - name: shop-gateway
      sectionName: https
  hostnames: [shop.example.com]
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      backendRefs:
        - name: api-service
          port: 8080
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: web-service
          port: 80
---
# ingress-nginx redirected HTTP to HTTPS for you. Gateway API does not.
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: shop-route-ssl-redirect
  namespace: shop
spec:
  parentRefs:
    - name: shop-gateway
      sectionName: http
  hostnames: [shop.example.com]
  rules:
    - filters:
        - type: RequestRedirect
          requestRedirect:
            scheme: https
            statusCode: 308

Three things to notice. sectionName binds the route to a specific listener, which is how you keep the HTTP and HTTPS behaviours separate. allowedRoutes is the role split the Ingress API never had: a platform team owns the Gateway and decides which namespaces may attach to it, while application teams own their HTTPRoutes. And the third object exists only to reproduce a redirect that ingress-nginx performed by default — which is a fair summary of the whole migration.^[gwapi]

A cutover you can actually reverse

The single most useful property of this migration is that both controllers can run at the same time. They are different objects, watching different resources, behind different load balancers. Nothing forces a big-bang cutover, so do not perform one.

1. Install the new controller alongside the old one. Distinct GatewayClass, distinct namespace, its own LoadBalancer Service and its own external address. Traffic still goes to ingress-nginx.
2. Convert and review. Run ingress2gateway against a namespace, read the warnings, and hand-fix the annotations it could not translate. Do not apply the output unread.
3. Apply the Gateway API objects with the same hostnames. Nothing changes for users yet — the new controller has its own IP and no DNS record points at it.
4. Compare the two edges directly with --resolve, request by request: status codes, redirect targets, headers, and the trailing-slash and regex cases specifically. This is the step that catches the five behaviours above.
5. Shift DNS gradually — a low-TTL record, a weighted policy, or one non-critical hostname first. Keep ingress-nginx serving until the new edge has held real traffic through a peak.
6. Decommission deliberately. Remove the ingress-nginx Deployment, its Service, its IngressClass and its ValidatingWebhookConfiguration. Leaving the admission webhook behind is how you end up with a broken cluster weeks later.

# Install the Standard channel CRDs (server-side apply, as the project documents)
kubectl apply --server-side -f \
  https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.1/standard-install.yaml

# The Gateway must be Programmed before you move any traffic to it
kubectl get gateway shop-gateway -n shop \
  -o jsonpath='{.status.conditions[?(@.type=="Programmed")].status}{"\n"}'

# Every parentRef must be Accepted, and every backendRef ResolvedRefs.
# Nested ranges keep each condition paired with its own status.
kubectl get httproute shop-route -n shop -o jsonpath='{range .status.parents[*]}{.controllerName}{"\t"}{range .conditions[*]}{.type}={.status}{" "}{end}{"\n"}{end}'

# Compare old and new on the same request, before DNS moves.
# A cloud load balancer publishes either .ip or .hostname - AWS uses .hostname,
# so --connect-to is used instead of --resolve: it accepts both.
OLD=$(kubectl get svc -n ingress-nginx ingress-nginx-controller \
  -o jsonpath='{.status.loadBalancer.ingress[0].ip}{.status.loadBalancer.ingress[0].hostname}')
NEW=$(kubectl get gateway shop-gateway -n shop \
  -o jsonpath='{.status.addresses[0].value}')
for edge in "$OLD" "$NEW"; do
  curl -sS -o /dev/null -w "$edge  %{http_code}  %{redirect_url}\n" \
    --connect-to "shop.example.com:443:$edge:443" https://shop.example.com/api
done

Note the Programmed condition in the second command. A Gateway that exists is not a Gateway that is serving; the status conditions are the contract, and checking them is cheaper than discovering the difference during the DNS change.

ingress-nginx, NGINX Ingress, NGINX Gateway Fabric

Three separate projects, similar names, and a genuine source of bad decisions during exactly this migration. People migrate off ingress-nginx onto “NGINX Ingress” believing they have changed something, and are surprised later — or dismiss NGINX entirely on the assumption that all three died together.

The Kubernetes project itself felt the need to spell this out: both use NGINX as the data plane, but are otherwise unrelated. Migrating from the community controller to F5's is a real migration with its own annotation translation work — it is not a rename.^[gotchas]

What I would do this week

If you have not started: run the four detection commands today, because the annotation count is the only number that tells you whether this is an afternoon or a quarter. If the answer is “an afternoon”, do it this week and stop carrying the risk. If the answer is “a quarter”, the useful move is still to install a second controller alongside now and migrate one low-stakes hostname, because the first migration is where you learn which of your assumptions were actually ingress-nginx behaviours.

The broader lesson is one I have written about before in boring cloud architectures: the components most likely to hurt you are the ones nobody thinks about, precisely because they have worked for years. An ingress controller maintained by one or two volunteers, sitting in front of half the cloud native world, was a concentration of risk long before it was archived. Worth auditing what else in your stack has that shape — and worth asking, as in when not to use Kubernetes, whether the platform is earning the operational surface it costs you.

Frequently asked questions

Is ingress-nginx safe to keep running for now?

It works, and it will keep working. But it will never receive another security patch — and note what the final release actually was: controller-v1.15.1 was the fix for CVE-2026-4342, a configuration injection reaching code execution in the controller and disclosure of cluster-wide Secrets, shipped the same day the advisory went out and five days before the repository went read-only. That was the sixth such bug in seven weeks. The next one has no fix. If you must run it for a few more weeks, at minimum restrict who can create Ingress objects, remove the controller's cluster-wide Secret access if your install grants it, and do not expose the admission webhook.

Is the Kubernetes Ingress API deprecated too?

No, and this is the most common misreading. The Ingress API is generally available, subject to the normal GA stability guarantees, and the Kubernetes project has stated it has no plans to remove it. It is frozen: no further development. Only the community NGINX controller was retired, not the API it implements.

What is the difference between ingress-nginx and nginx-ingress?

They are different projects from different organisations. kubernetes/ingress-nginx was maintained by the Kubernetes community and is archived. nginx/kubernetes-ingress is F5's NGINX Ingress Controller and is actively developed. The Kubernetes project's own wording: both use NGINX as the data plane, but are otherwise unrelated. Moving from one to the other is a real migration, not a rename.

Can ingress2gateway migrate my cluster automatically?

Partly. Version 1.0 covers over thirty ingress-nginx annotations, up from three, and it is the right starting point. But configuration-snippet has no equivalent and is unsupported, proxy-body-size has no Gateway API equivalent, proxy timeouts map only on a best-effort basis, and URL normalisation is not expressible at all. Read everything it prints to stderr — that output is your remaining manual work.

Should I move to Gateway API or just switch Ingress controllers?

Switching controllers is faster and keeps your existing objects, but you land on a frozen API and you still have to re-express every annotation in a new dialect — so you will likely do this again. Gateway API is a larger rewrite but it is where development is happening, and it gives you role separation between the platform team that owns the Gateway and the application teams that own their routes. Large estates of simple Ingress objects favour switching controllers; multi-team shared edges favour Gateway API.

Which Gateway API implementation should I choose?

Choose from the published conformance reports rather than from marketing pages. The Gateway API project lists, per release, exactly how many extended features each implementation passes for HTTPRoute, GRPCRoute and TLSRoute. Check the report for the version you actually intend to run, confirm the implementation supports the specific features your annotations translated into, and confirm it is supported on your platform.

Do I need to upgrade Kubernetes before installing Gateway API?

The project does not publish a fixed minimum Kubernetes version; its stated policy is to support the five most recent Kubernetes minor versions, so check that policy against your cluster rather than a number you read in a blog post. Install the Standard channel CRDs from the current patch release — v1.6.1, from 16 July 2026 — using server-side apply, which is how the project documents it. If you install the Experimental channel instead, its CRDs are definitely too large for a client-side kubectl apply, and experimental types now carry an X prefix in a separate API group precisely so you do not build production on them by accident.

The same discipline applies to the cryptography underneath: see post-quantum SSH and TLS for what to verify on the connections these systems depend on.

Sources

Every claim above is traceable to one of these. Primary and official sources only — Kubernetes project blog posts and documentation, repository state, security advisories and the Gateway API specification.

1. Kubernetes blog — Ingress NGINX Retirement: What You Need to Know (11 Nov 2025)
2. Kubernetes blog — Ingress NGINX: Statement from the Steering and Security Response Committees (29 Jan 2026)
3. Kubernetes blog — Before You Migrate: Five Surprising Ingress-NGINX Behaviors You Need to Know (27 Feb 2026)
4. GitHub — kubernetes/ingress-nginx (public archive, read-only since 24 Mar 2026)
5. GitHub — ingress-nginx controller-v1.15.1, the final release (19 Mar 2026)
6. Kubernetes Security Response Committee — [Security Advisory] Multiple issues in ingress-nginx (2 Feb 2026)
7. kubernetes/kubernetes#136678 — CVE-2026-24512, configuration injection via the Ingress path field
8. kubernetes/kubernetes#137560 — CVE-2026-3288, configuration injection via the rewrite-target annotation
9. kubernetes/kubernetes#137893 — CVE-2026-4342, comment-based configuration injection (fixed by the final release)
10. Kubernetes blog — Ingress-nginx CVE-2025-1974: What You Need to Know (24 Mar 2025)
11. Kubernetes documentation — Ingress (the API is generally available and frozen)
12. Kubernetes documentation — Ingress Controllers
13. Gateway API — API overview and channel status
14. Kubernetes blog — Gateway API v1.6: TCPRoute and UDPRoute Graduate to Standard (3 Aug 2026)
15. GitHub — Gateway API v1.6.0 release notes
16. GitHub — Gateway API v1.6.1, the current patch release (16 July 2026)
17. Gateway API — v1.6 conformance reports by implementation
18. GitHub — kubernetes-sigs/ingress2gateway
19. Kubernetes blog — Announcing Ingress2Gateway 1.0: Your Path to Gateway API (20 Mar 2026)
20. GitHub — nginx/kubernetes-ingress, the F5 NGINX Ingress Controller (a different project)
21. GitHub — nginx/nginx-gateway-fabric, F5's Gateway API implementation
22. Gateway API — versioning, release channels and graduation criteria