Your ingress controller may still be routing traffic normally, but the project protecting it has stopped. Migration requires more than converting YAML.
It still works—which is why this is easy to postpone
Your Kubernetes applications are responding normally. TLS certificates renew. Routes still send traffic to the correct Services. Nothing on the dashboard says that your ingress layer has expired.
But if those routes depend on the Kubernetes community’s Ingress-NGINX controller, the software is now retired. The project repository was archived on 24 March 2026. There will be no more releases, bug fixes or security patches.
Existing installations were not remotely disabled. Images and Helm charts remain available. That is useful for operational continuity, but it also creates a dangerous impression: because the controller still runs, migration can wait.
The risk is not an immediate shutdown. It is continuing to place internet traffic through a component whose maintainers will no longer fix the next vulnerability.
First, separate three things that sound similar
The retirement announcement is easy to misread because Kubernetes networking uses several similar names.
| Name | What it is | Current position |
|---|---|---|
| Ingress API | A stable Kubernetes resource for describing basic HTTP and HTTPS routing | Not retired or deprecated |
| Ingress-NGINX | The Kubernetes-community controller that turns Ingress resources and NGINX-specific annotations into running proxy configuration | Retired on 24 March 2026 |
| NGINX Ingress Controller | A separate controller maintained by F5 | A different product; not covered by the Kubernetes retirement |
| Gateway API | A newer set of Kubernetes networking resources and conformance rules | The recommended direction for new designs and many migrations |
An Ingress resource is only a declaration. A controller reads that declaration and configures the actual traffic-handling software. Retiring one controller does not remove the Ingress API from Kubernetes.
Gateway API also does not give you a controller by itself. It defines resources such as GatewayClass, Gateway and HTTPRoute. You must still choose an implementation that supports the features and operating model you need.
Why replacing the YAML is not enough
Ingress-NGINX began with the relatively small Ingress API, then accumulated years of controller-specific behaviour through annotations, ConfigMaps and custom resources.
Two clusters may contain similar-looking Ingress resources but behave differently because of settings such as:
- path rewrites and regular expressions;
- request and connection timeouts;
- maximum request-body size;
- HTTP-to-HTTPS redirects;
- source-IP handling;
- authentication and rate limits;
- custom NGINX configuration snippets;
- TLS passthrough and certificate placement.
Some of these have standard Gateway API equivalents. Some require implementation-specific policy resources. Others should be reconsidered rather than copied.
For example, the Kubernetes migration guidance warns that Ingress-NGINX regular-expression matches can be case-insensitive prefix matches. A mechanically translated route may therefore accept different paths unless the team tests the actual behaviour. Body-size limits, URL normalization and custom configuration snippets can also lack a portable one-to-one mapping.
The object being migrated is not the manifest. It is the traffic behaviour.
Gateway API is a direction, not a product choice
Gateway API improves several limitations of the original Ingress model. It separates infrastructure ownership from application routing, provides a clearer permission model for shared clusters and supports richer routing without placing every extension inside annotations.
That does not make every Gateway API implementation equivalent. Implementations can support different route types, optional features and policy extensions. The Gateway API project publishes conformance results, but conformance can apply to a particular profile and route type rather than every possible feature.
Before selecting a controller, compare what your workloads require:
| Requirement | Question to verify |
|---|---|
| HTTP routing | Does the implementation pass current Gateway + HTTPRoute conformance? |
| TLS | Where are certificates stored, and does TLS terminate or pass through? |
| Authentication | Is it standard, an implementation-specific policy or an external service? |
| Traffic policy | How are timeouts, retries, body limits and rate limits expressed? |
| Multi-team ownership | Can platform and application teams manage separate resources safely? |
| Operations | How are upgrades, logs, metrics, tracing and rollback handled? |
| Portability | Which parts of the design depend on one controller’s extensions? |
The correct target might be a managed cloud Gateway controller, Envoy Gateway, Traefik, Istio or another conformant implementation. It could also be another maintained Ingress controller when an immediate Gateway API migration is not realistic. The retirement tells you to leave unsupported software; it does not make the same destination correct for every cluster.
A safer migration sequence
1. Find where Ingress-NGINX is actually used
Inventory clusters, controller versions, Helm releases, IngressClass objects, Ingress resources, annotations, ConfigMaps, snippets, TCP/UDP exposure and integrations such as cert-manager or ExternalDNS. Include non-production and disaster-recovery clusters; forgotten clusters are often the last to be migrated.
2. Record behaviour before selecting the replacement
For each important route, capture hosts, paths, redirects, headers, authentication, timeouts, body limits, TLS behaviour and failure responses. Add tests for this behaviour. Configuration alone may not reveal defaults introduced by the controller.
3. Choose the target implementation
Decide whether the immediate goal is another maintained Ingress controller or a Gateway API implementation. Evaluate conformance, platform support, extensions, operational ownership and the cost of changing behaviour.
4. Use Ingress2Gateway as an assistant
The Kubernetes SIG Network’s Ingress2Gateway 1.0 can translate common Ingress-NGINX annotations and warn about configuration it cannot represent. It supports more than 30 common annotations and tests translations against real controllers.
Its own documentation is explicit: it is a migration assistant, not a one-shot replacement. Treat every warning as unresolved work. Do not discard warnings simply because valid Gateway API YAML was generated.
5. Run both paths and compare results
Deploy the new controller and routes beside the existing path. Test normal traffic, failure cases, large requests, redirects, long-running requests, client IPs and certificate behaviour. Then move traffic gradually using weighted DNS, load-balancer controls or supported traffic splitting.
Keep a tested rollback path until the new route has survived real traffic and an appropriate observation period.
6. Remove the old controller completely
After cutover, remove old Ingress resources, admission components, controller workloads, service accounts, cluster roles, ConfigMaps, Services and load balancers. Leaving an unused internet-facing controller installed preserves attack surface and operational confusion.
What should teams do this week?
Do not begin by installing a fashionable replacement. Begin with evidence.
Run an inventory across every cluster and answer:
- Do we run the retired Kubernetes Ingress-NGINX controller?
- Which internet-facing services depend on it?
- Which annotations or custom configuration define behaviour that the basic Ingress resource does not show?
- Who owns the migration and what is the target date?
- How will we prove that the replacement behaves correctly before traffic moves?
If the answers are incomplete, record Ingress-NGINX as an unsupported platform dependency and give the migration an owner. A working controller is not the same as a supported controller.
Know, use or master?
Know: Developers should understand that the Ingress API, Ingress-NGINX and Gateway API are different things. Application teams need to know which routing behaviours their services rely on.
Use: Platform and DevOps engineers should inventory annotations, evaluate implementations, translate routes and test behaviour in parallel environments.
Master: Platform architects responsible for shared clusters should design GatewayClass, Gateway, route ownership, policy attachment, conformance validation and controller lifecycle governance.
Ingress-NGINX retirement is not a reason for a rushed controller swap. It is a reason to stop treating the ingress layer as invisible plumbing. Understand its behaviour, choose a maintained destination and migrate traffic with evidence.
References and further reading
- Ingress NGINX Retirement: What You Need to Know — Kubernetes, 11 November 2025. The official retirement announcement and explanation of what remains available. Reviewed September 2026.
- Kubernetes v1.36 Sneak Peek: Ingress NGINX retirement — Kubernetes, 30 March 2026. Confirms retirement on 24 March 2026 and the end of fixes and security updates. Reviewed September 2026.
- Before You Migrate: Five Surprising Ingress-NGINX Behaviors — Kubernetes, 27 February 2026. Shows controller behaviours that can be lost during a simple configuration conversion. Reviewed September 2026.
- Announcing Ingress2Gateway 1.0 — Kubernetes SIG Network, 20 March 2026. Describes the migration assistant, its tested annotation support and its limitations. Reviewed September 2026.
- Migrating from Ingress — Kubernetes Gateway API project. Maps core Ingress concepts to Gateway API and explains where implementation-specific features remain. Reviewed September 2026.
- Gateway API implementations and conformance — Kubernetes Gateway API project. Lists implementations and explains the scope of conformance reports. Reviewed September 2026.