ingress-nginx Retired: How to Migrate to Gateway API

Lire cet article en français

If you run ingress-nginx, you are in a big group: the Kubernetes Steering Committee's statement cites Datadog research saying about half of cloud native environments rely on it. The work is the same for everyone: inventory, pick a target, translate, test, cut over. This guide walks through those steps in order. Each command and version below comes from the official docs or from our own lab run on 24 October 2026 (kind with Kubernetes v1.37.0, ingress-nginx v1.15.1, Envoy Gateway v1.9.2, ingress2gateway v1.2.0).

Last verified: 24 October 2026. Versions change quickly, so check the release pages linked in the sources before you copy a version number.

What exactly was retired, and what still works?

The community ingress-nginx controller (kubernetes/ingress-nginx) was retired. The Ingress API was not. Your Ingress objects stay valid Kubernetes resources. The controller that turned them into NGINX config gets no more releases, bug fixes or security patches.

The official timeline is short:

Date	Event	Source
11 Nov 2025	Retirement announced: best-effort maintenance until March 2026	Kubernetes blog
29 Jan 2026	Joint statement from the Steering and Security Response Committees: "begin migration ... immediately"	Kubernetes blog
27 Feb 2026	Gateway API 1.5 released (ListenerSet and the HTTPRoute CORS filter graduate)	Kubernetes blog
19 Mar 2026	Last releases: controller v1.15.1, v1.14.5, v1.13.9 (Helm chart 4.15.1)	GitHub releases
20 Mar 2026	ingress2gateway 1.0	Kubernetes blog
24 Mar 2026	Repository archived, read-only	GitHub
Nov 2026	End of Microsoft's critical-patch support for the AKS application routing add-on's NGINX	Microsoft Learn

Three things often get mixed up here:

• Existing deployments keep working. The project says so explicitly, and images and Helm charts stay downloadable. Nothing breaks on a given day, which is exactly why the committees warned that "you may not know you are affected until you are compromised."
• F5's NGINX Ingress Controller is a different product. The Kubernetes blog spells it out: Ingress-NGINX (community, retired) and NGINX Ingress (F5, nginx/kubernetes-ingress) both use NGINX but are otherwise unrelated. The F5 one is not part of this retirement.
• InGate, the planned successor, was retired too. There is no official drop-in replacement. Every path is a migration.

Am I affected? How do I find ingress-nginx in my clusters?

Run the command the Kubernetes project gives, with cluster-admin rights, in every cluster:

kubectl get pods --all-namespaces --selector app.kubernetes.io/name=ingress-nginx

Any pod in the output means you run the retired controller. That label catches standard Helm and manifest installs. It misses forks and installs with custom labels, so we also look at the classes and at what the Ingress objects ask for:

# Which controllers are registered?
kubectl get ingressclass -o custom-columns=NAME:.metadata.name,CONTROLLER:.spec.controller

# Which Ingresses use the nginx class, and how many annotations do they carry?
kubectl get ingress -A -o json | jq -r '
  .items[] | select(.spec.ingressClassName=="nginx"
     or .metadata.annotations["kubernetes.io/ingress.class"]=="nginx")
  | "\(.metadata.namespace)/\(.metadata.name)\t\(.metadata.annotations // {} | keys | map(select(startswith("nginx.ingress"))) | length) nginx annotations"'

The controller value k8s.io/ingress-nginx belongs to the retired project. F5's controller registers nginx.org/ingress-controller.

That second command also gives you a first idea of the size of the job. The number of Ingress objects says little. The number of distinct nginx.ingress.kubernetes.io/* annotations matters much more, and configuration-snippet and server-snippet matter most, because nothing translates them automatically.

Is it really risky to stay on ingress-nginx for a while?

Yes, and the risk grows each month, because the controller sits on the internet edge and new CVEs will not be patched. This is not theoretical: in March 2025 the Kubernetes Security Response Committee described CVE-2025-1974 ("IngressNightmare") and related flaws as vulnerabilities "that could make it easy for attackers to take over your Kubernetes cluster". Those were patched because the project was still maintained. The next ones will not be. The retirement post calls the snippet design "insurmountable technical debt".

If you cannot migrate this quarter, reduce exposure while you plan:

• Make sure you run the last release of your line (v1.15.1, v1.14.5 or v1.13.9).
• Keep allow-snippet-annotations set to false (the default in current releases) and remove snippet annotations you no longer need.
• Do not expose the admission webhook outside the cluster. Restrict who can create Ingress objects through RBAC.
• Put a WAF or a cloud load balancer with rate limiting in front, so the controller is not your only line of defence.
• Write the migration date down. "Later" becomes "never" very easily with an ingress layer that still works.

Commercial extended support exists from some vendors. It can buy time, but it does not change the outcome, because no community fix will ever land again.

Should I move to Gateway API or just switch to another Ingress controller?

For most teams, Gateway API is the better long-term target. Another Ingress controller is the faster short-term exit. Choose based on how many custom annotations you depend on and how much time you have.

	Gateway API (Envoy Gateway, Istio, Cilium, NGINX Gateway Fabric, kgateway, Traefik...)	Another Ingress controller (Traefik, HAProxy, F5 NGINX...)
Future	Where SIG Network develops new features; Ingress is frozen	Works today; Ingress API gets no new features
Migration effort	Rewrite into Gateway + HTTPRoute (tool-assisted)	Often smaller: keep Ingress objects, change annotations or class
Portability	Standard fields for redirects, rewrites, header changes, weights, timeouts, CORS	Annotations are vendor-specific, same lock-in as before
Team model	Platform team owns Gateway, app teams own routes (RBAC-friendly)	One object mixes both
Best when	You have time for one proper migration and want to stop translating annotations	You must leave ingress-nginx this month, or you rely on features no Gateway implementation offers yet

Traefik deserves a specific note: Traefik v3 has a kubernetesIngressNGINX provider that reads many ingress-nginx annotations directly. Its docs list which ones are implemented and warn about different defaults (request buffering, for example). That makes it a practical bridge. Just do not mistake it for an endpoint, because the annotations stay non-portable.

On managed clusters, check the provider first. On AKS, Microsoft's application routing add-on is built on the same NGINX controller, and Microsoft supports it with critical patches only until November 2026. Its documented path is the add-on's own Gateway API implementation, which can run side by side with the old one for a DNS cutover.

Which Gateway API implementation should I pick?

Pick the one that passes conformance for the features you use and that your team can operate. Familiarity with the data plane (Envoy or NGINX) is a perfectly valid tie-breaker. The Gateway API project keeps an implementations list and conformance reports. Read those, not vendor comparison tables.

How we narrow it down:

1. Already have a mesh or a CNI with Gateway support? Istio and Cilium both implement Gateway API. Using what you already run saves you one more component.
2. Want a standalone, Envoy-based gateway? Envoy Gateway is a CNCF Envoy sub-project. ingress2gateway has a dedicated emitter for it, which helps with body size and similar settings.
3. Your team knows NGINX well? NGINX Gateway Fabric (v2.8.0 at the time of writing) keeps NGINX as the data plane, behind the standard API.
4. On a cloud with a native implementation? GKE Gateway, AKS application routing (Gateway API) and AWS Load Balancer Controller move the data plane out of the cluster. ingress2gateway even has a gce emitter.

We used Envoy Gateway in the lab for one practical reason: it installs with one Helm command and brings the Gateway API CRDs with it.

What does the Gateway API model look like compared with Ingress?

One Ingress object becomes (at least) a Gateway, which holds listeners, ports, hostnames and TLS, plus one or more HTTPRoutes, which hold matching, filters and backends. A GatewayClass names the controller, much like IngressClass does.

This split is the main benefit. It is also the main source of migration surprises:

• TLS moves out of the app team's object. The certificate reference now sits on a Gateway listener, so whoever owns the Gateway owns certificates. cert-manager supports this: add the cert-manager.io/cluster-issuer (or issuer) annotation to the Gateway, and enable Gateway API support in cert-manager with config.gatewayAPI.enabled=true.
• Cross-namespace routing is explicit. An HTTPRoute in shop can attach to a Gateway in infra only if the listener's allowedRoutes allows it. A route that references a Service in another namespace needs a ReferenceGrant.
• Status is honest. kubectl get httproute -o yaml shows Accepted and ResolvedRefs conditions for each parent Gateway, and you will use them a lot.

How do I install the Gateway API CRDs and a controller?

Install the standard-channel CRDs with server-side apply (unless your controller's chart installs them for you), then install the controller and create a GatewayClass. The current stable release when we checked was v1.6.3 (6 October 2026). v1.7.0 was at release candidate 3.

kubectl apply --server-side -f \
  https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.3/standard-install.yaml

The experimental channel (experimental-install.yaml) adds resources and fields that may still change. Most migrations do not need it.

Envoy Gateway, as we installed it in the lab:

helm install eg oci://docker.io/envoyproxy/gateway-helm --version v1.9.2 \
  -n envoy-gateway-system --create-namespace --wait

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: eg
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller

How do I convert my Ingress resources with ingress2gateway?

Run ingress2gateway print --providers=ingress-nginx against a file or a namespace, save the YAML, and treat the warnings as your to-do list. The tool is a migration assistant. It does not replace review. Version 1.0 added support for more than 30 common ingress-nginx annotations, and v1.2.0 (7 July 2026) is the current release.

Install it with Homebrew, with go install, or from the release binaries (always check the checksum):

brew install ingress2gateway
# or
go install github.com/kubernetes-sigs/ingress2gateway@v1.2.0

Then point it at your manifests or your cluster:

# From files (what we recommend first: export, review, commit)
ingress2gateway print --input-file shop.yaml --providers=ingress-nginx > gwapi.yaml

# From one namespace, or from the whole cluster
ingress2gateway print --namespace shop --providers=ingress-nginx > gwapi.yaml
ingress2gateway print --all-namespaces --providers=ingress-nginx > gwapi.yaml

# Add implementation-specific extras (e.g. body size for Envoy Gateway)
ingress2gateway print --input-file shop.yaml --providers=ingress-nginx --emitter envoy-gateway

Here is the Ingress we fed it. It is a very common pattern: an API under /api with a capture-group rewrite, the website on /, plus a body limit and a rate limit:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: shop
  namespace: shop
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/proxy-body-size: "20m"
    nginx.ingress.kubernetes.io/limit-rps: "10"
spec:
  ingressClassName: nginx
  tls:
    - hosts: [shop.example.com]
      secretName: shop-tls
  rules:
    - host: shop.example.com
      http:
        paths:
          - path: /api(/|$)(.*)
            pathType: ImplementationSpecific
            backend:
              service: {name: shop-api, port: {number: 8080}}
          - path: /
            pathType: Prefix
            backend:
              service: {name: shop-web, port: {number: 80}}

And these are the warnings ingress2gateway v1.2.0 printed (shortened, wording unchanged):

What the tool did, and what it left for us:

• It created a Gateway with an HTTP and an HTTPS listener (TLS from shop-tls), an HTTPRoute for the HTTPS traffic, and a second HTTPRoute that redirects HTTP to HTTPS with a 308.
• It turned both paths into case-insensitive regular expressions: (?i)/api(/|$)(.*).* and, surprisingly, (?i)/.* for the plain / prefix. We explain why in the next section. It is not a tool bug.
• It skipped the rewrite (Path rewrites with capture group references are not supported), the rate limit (Unsupported annotation ... limit-rps) and the body size (Most Gateway API implementations have reasonable body size and buffering defaults).
• With --emitter envoy-gateway, it additionally produced a BackendTrafficPolicy with requestBuffer.limit: 20Mi, so the body size survives on Envoy Gateway.

So the tool produced the structure (Gateway, routes, redirect, TLS). What it left for us are exactly the parts that cause outages when nobody looks at them.

Which ingress-nginx behaviours will break after migration?

Four of them catch almost everyone: regex matching is a case-insensitive prefix match, use-regex and rewrite-target switch every path on the same host to regex, rewrite-target also applies to every path of that Ingress, and ingress-nginx adds redirects that Gateway API never adds by itself. The Kubernetes blog documents the first ones ("Five surprising Ingress-NGINX behaviors"). We reproduced them in the lab.

We sent the same five requests through ingress-nginx v1.15.1 and through Envoy Gateway v1.9.2, with a cleaned-up HTTPRoute (PathPrefix /api with a ReplacePrefixMatch rewrite to /, and PathPrefix / for the website). The backend is go-httpbin, which echoes the path it received:

Request path	ingress-nginx	Envoy Gateway (clean HTTPRoute)	Why
/api/anything/orders	200, backend got /anything/orders	200, backend got /anything/orders	Same: the rewrite works on both
/API/anything/orders	200	404	ingress-nginx regex is case-insensitive
/apiv2/anything	200, website got /	404 from the website	Falls through to /, see next row
/anything/home	200, but website got /	200, website got /anything/home	rewrite-target: /$2 also rewrote the / path
/Anything/home	200, website got /	404 from the website	The backend itself is case-sensitive

The fourth row is the one that surprised us. With the common "API plus website in one Ingress" pattern, ingress-nginx rewrote every website request to /, because rewrite-target applies to all paths of the Ingress that carries it. A single-page app that routes on the client side would hide this completely. After migration the website receives real paths. That is more correct, but it is a behaviour change you must test.

The quirks and how we handle them:

Regex paths are case-insensitive prefix matches

ingress-nginx compiles regex paths as case-insensitive and unanchored at the end, so /[A-Z]{3} also matches /uuid. Most Envoy-based implementations do a full, case-sensitive match. ingress2gateway preserves the old behaviour with (?i) and a trailing .*. Decide on purpose: keep it where clients rely on it, otherwise remove (?i) and .*, or better, replace the regex with PathPrefix or Exact.

use-regex and rewrite-target affect the whole host

If any Ingress for shop.example.com has use-regex: "true" or a rewrite-target, ingress-nginx treats all paths of that host, across all Ingresses, as regex. An Exact path /Header then also serves /headers. Gateway API never reinterprets Exact or PathPrefix, so a typo that "worked" for years starts returning 404. Search access logs for real paths before you clean them up.

Missing trailing slash gives a 301

For a Prefix or Exact path like /my-path/, ingress-nginx answers /my-path with 301 to /my-path/. Conformant Gateway API implementations never add redirects. If clients depend on it, add an explicit RequestRedirect rule.

URL normalisation differs

ingress-nginx normalises //, /./ and /../ before matching. Gateway API does not standardise this. Istio, Envoy Gateway and kgateway normalise . and .. by default, but details vary. If your backends do security checks on paths, test this explicitly.

Snippets have no equivalent

configuration-snippet and server-snippet hold raw NGINX config, so nothing can translate them automatically. List what each snippet does (headers, auth, buffering, more_set_headers) and map it to a filter, a policy of your implementation, or the application itself.

How do I rewrite paths, redirect to HTTPS and set timeouts in Gateway API?

Use the standard HTTPRoute filters: URLRewrite for rewrites, RequestRedirect for redirects, RequestHeaderModifier/ResponseHeaderModifier for headers, and the timeouts field for request timeouts. Here is the clean version of the shop route we tested on Envoy Gateway:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: shop
  namespace: shop
spec:
  parentRefs:
    - name: shop-gw
  hostnames: [shop.example.com]
  rules:
    - matches:
        - path: {type: PathPrefix, value: /api}
      filters:
        - type: URLRewrite
          urlRewrite:
            path: {type: ReplacePrefixMatch, replacePrefixMatch: /}
      backendRefs:
        - {name: shop-api, port: 8080}
      timeouts:
        request: 10s
    - matches:
        - path: {type: PathPrefix, value: /}
      backendRefs:
        - {name: shop-web, port: 80}

PathPrefix /api matches /api and /api/... but not /apiv2, because Gateway API prefix matching works on path elements. That is the behaviour most people actually wanted from /api(/|$)(.*).

Common annotations and where they go:

ingress-nginx annotation	Gateway API	Notes
ssl-redirect, force-ssl-redirect	RequestRedirect filter (scheme https), on the HTTP listener's route	ingress2gateway generates it (308)
rewrite-target (no capture groups)	URLRewrite filter	With capture groups: rewrite by hand (ReplacePrefixMatch)
use-regex	RegularExpression path match	Semantics are implementation-specific
enable-cors, cors-*	CORS filter	Standard since Gateway API 1.5
proxy-read-timeout, proxy-send-timeout	timeouts.request / timeouts.backendRequest	Not equivalent: ingress-nginx timeouts are TCP-level
canary, canary-weight	backendRefs with weight	Header-based canary: header matches
backend-protocol: HTTPS	BackendTLSPolicy	Check implementation support
proxy-body-size	Implementation policy (e.g. Envoy Gateway BackendTrafficPolicy)	No standard field
limit-rps, limit-connections	Implementation policy	No standard field
auth-url (external auth)	Implementation policy (e.g. SecurityPolicy in Envoy Gateway)	No standard field
configuration-snippet, server-snippet	None	Redesign case by case

How do I switch traffic without downtime?

Run the new Gateway next to ingress-nginx with its own address, test it with real hostnames, then shift traffic gradually with weighted DNS or your load balancer. Delete the old controller only after a quiet period. Both controllers can watch the same cluster without conflict, because ingress-nginx only reads Ingress and the Gateway controller only reads Gateway API resources.

Our checklist, in order:

1. Export and commit the current Ingress objects and the ingress-nginx ConfigMap. Global ConfigMap settings (timeouts, body size, use-forwarded-headers, ssl-protocols) are easy to forget because they live outside the Ingress objects.
2. Generate, review and commit the Gateway API YAML. Keep ingress2gateway's warnings in the pull request description, so reviewers see what was not translated.
3. Deploy the Gateway and check status: the Gateway should report Programmed=True with an address, and each HTTPRoute should report Accepted=True and ResolvedRefs=True.

kubectl -n shop get gateway shop-gw \
  -o jsonpath='{range .status.conditions[*]}{.type}={.status} ({.reason}){"\n"}{end}'
kubectl -n shop get httproute shop \
  -o jsonpath='{range .status.parents[0].conditions[*]}{.type}={.status} ({.reason}){"\n"}{end}'

In kind, our Gateway showed Accepted=True but Programmed=False (AddressNotAssigned), because a kind cluster has no LoadBalancer implementation. Routing still worked through a port-forward. On a cloud cluster that condition must be True.

4. Test with the real Host header against the new address, replaying your most-used paths from access logs, not only the happy path:

NEW=203.0.113.50   # address of the new Gateway
curl -s -o /dev/null -w "%{http_code}\n" -H "Host: shop.example.com" "http://$NEW/api/health"
curl -sk -o /dev/null -w "%{http_code}\n" --resolve shop.example.com:443:$NEW https://shop.example.com/

5. Shift traffic gradually: weighted DNS records (lower the TTL a day earlier), or weights on the external load balancer. Watch 4xx/5xx rates, latency and backend logs at each step (10%, 50%, 100%).
6. Keep ingress-nginx running but idle for a few days, then remove the Ingress objects and uninstall the controller and its admission webhook.

What are the most common migration mistakes?

Trusting the generated YAML without reading the warnings, forgetting the global ConfigMap, and testing only the paths that the Ingress declares instead of the paths clients really call. A few more:

• Racing the admission webhook. In our lab, kubectl apply of the Ingress failed with failed calling webhook "validate.nginx.ingress.kubernetes.io" ... connection refused because the controller was "available" a few seconds before its webhook was listening. Pipelines that install the controller and apply Ingresses in one go hit this too. Retry, or wait on the webhook endpoint.
• Two owners for the CRDs (see the warning above).
• HTTP listener left open. ingress2gateway mirrors ingress-nginx and keeps port 80 with a redirect. If you never want plain HTTP, remove that listener and its route.
• Assuming defaults match. Body size limits, buffering, timeouts and header size limits are implementation defaults. Write down your old values and set the new ones deliberately.
• Forgetting the other ingress-nginx users. Helm charts of third-party apps often ship their own Ingress with nginx annotations. helm template them and check.

Can an AI assistant help with the migration?

Yes for reading and reviewing, no for applying. An assistant is good at explaining a 40-annotation Ingress, comparing generated HTTPRoutes with the original, or drafting test curl commands from access logs. It should not get credentials that can change the cluster or DNS during a cutover. We explain our guardrails for AI tools that touch infrastructure in the Terraform MCP server guide. Node operating system upgrades often happen in the same maintenance windows, and our Ubuntu 24.04 to 26.04 upgrade guide covers the cgroup v2 requirement that container hosts now have.

FAQ

Will my ingress-nginx stop working on a specific date?

No. Existing deployments keep running, and images and charts stay available. What stopped is maintenance: no releases, no bug fixes, no security patches after March 2026.

Is the Kubernetes Ingress API deprecated?

No. Ingress remains a stable (GA) API, but it is frozen. New traffic-management features go into Gateway API. You can keep using Ingress with a maintained controller.

Is the F5 NGINX Ingress Controller affected?

No. It is a separate project (nginx/kubernetes-ingress) with its own maintainers. Its annotations use the nginx.org/ prefix, so moving to it is still a migration.

What is the latest ingress-nginx version?

The final releases are controller v1.15.1 (with Helm chart 4.15.1), v1.14.5 and v1.13.9, all published on 19 March 2026. The repository was archived on 24 March 2026.

Does ingress2gateway convert everything automatically?

No. Version 1.x supports over 30 common ingress-nginx annotations and warns about the rest. Snippets, capture-group rewrites and rate limits need manual work, and you must review semantics such as case-insensitive regex.

Do I need the experimental Gateway API channel?

Usually not. Gateway, HTTPRoute, GRPCRoute, ReferenceGrant and the common filters are in the standard channel. Install the experimental channel only for a specific feature you need, and accept that it may change.

How do I get Let's Encrypt certificates with Gateway API?

Use cert-manager with Gateway API support enabled (config.gatewayAPI.enabled=true), then annotate the Gateway with cert-manager.io/cluster-issuer. cert-manager creates a Certificate for each HTTPS listener that has a hostname and a certificateRefs entry.

What should AKS users do?

Microsoft supports the application routing add-on's NGINX with critical security patches only through November 2026. Its documented path is the add-on's Gateway API implementation, which can run side by side for a DNS-based cutover. Application Gateway for Containers is another option.

Sources

• Kubernetes blog: Ingress NGINX Retirement: What You Need to Know (11 Nov 2025)
• Kubernetes blog: Statement from the Kubernetes Steering and Security Response Committees (29 Jan 2026)
• Kubernetes blog: Before You Migrate: Five Surprising Ingress-NGINX Behaviors (27 Feb 2026)
• Kubernetes blog: Announcing Ingress2Gateway 1.0 (20 Mar 2026)
• GitHub: kubernetes/ingress-nginx (archived) and releases
• GitHub: kubernetes-sigs/ingress2gateway (README, v1.2.0 release)
• Gateway API: Getting started / install, Welcome guide for Ingress-NGINX users, v1.6.3 release, implementations
• cert-manager: Annotated Gateway resource
• Traefik: Ingress with NGINX annotations
• Microsoft Learn: Ingress in AKS
• Envoy Gateway: documentation

How we tested: kind v0.33.0 (Kubernetes v1.37.0) on an arm64 VM, ingress-nginx controller v1.15.1 (official kind manifest), Envoy Gateway v1.9.2 (Helm), go-httpbin 2.26.0 as backend, ingress2gateway v1.2.0 (checksum verified). Requests went through kubectl port-forward, so load-balancer behaviour was not part of the test.

Header image: Illustration generated with Google Gemini for DevOpsCompass.