For years, the community Ingress NGINX controller was the default way to route HTTP traffic into Kubernetes clusters. Then, in November 2025, Kubernetes SIG Network and the Security Response Committee announced its retirement, with best-effort maintenance ending in March 2026. That date has passed. Existing installations still run, but no new releases, bug fixes or security patches will be published. The Kubernetes Steering and Security Response Committees described Ingress NGINX as critical infrastructure for about half of cloud native environments, which means a large share of production clusters are now running an unmaintained component at their most exposed point: the edge where internet traffic enters. This playbook explains what the retirement means, why Gateway API is the recommended destination and how to migrate application traffic safely without a big-bang cutover.
What Was Retired and What Was Not
Terminology causes a lot of confusion, so it is worth being precise. Google’s open source team summarized the distinctions clearly in early 2026:
- The Ingress API is the Kubernetes resource type. It is not being removed. It has been feature-frozen since it became generally available in Kubernetes 1.19 and receives no new capabilities.
- Ingress NGINX is the community-maintained controller in the kubernetes/ingress-nginx project. This is what was retired.
- The NGINX Ingress Controller from F5 is a separate product with open source and commercial editions, and it continues to be maintained.
Why retire such a widely used project? Two reasons stand out. The controller’s snippet annotations let users inject raw NGINX configuration, a flexible feature that created configuration-injection security risks that were very hard to fix without breaking users. And the project depended on a very small number of maintainers working in their spare time, which is not sustainable for security-critical infrastructure. The lesson extends beyond this controller: critical open source components need a realistic view of their maintenance health.
The practical consequence is that any vulnerability discovered in Ingress NGINX from now on will remain unpatched in the official project. Security and compliance teams will increasingly flag it, and cloud and platform vendors will steer customers away from it. Migration is no longer optional for production environments.
Why Gateway API Is the Recommended Destination
The Kubernetes project recommends migrating to Gateway API, the successor to Ingress, while noting that teams who must stay on the Ingress API can switch to another maintained Ingress controller. Gateway API is a family of resources designed to fix the limitations that pushed users toward annotations in the first place:
- Role-oriented design. Infrastructure providers define GatewayClasses, platform teams operate Gateways, and application teams attach Routes. Each role gets appropriate permissions through Kubernetes RBAC.
- Expressive routing in the specification. Header and query matching, traffic splitting, request mirroring, redirects and header modification are part of the API instead of vendor-specific annotations.
- Broader protocol support. Beyond HTTP, Gateway API supports gRPC, TLS, TCP and UDP routing.
- Portability. Implementations are tested against conformance suites, so core behavior is consistent across vendors, with explicit extension points for implementation-specific features.
- Stability. The standard channel resources are generally available and evolve without breaking changes.
Several mature implementations exist, including Envoy Gateway, Cilium, Istio, Emissary, NGINX Gateway Fabric and cloud-managed options such as GKE Gateway. Choosing among them is part of the migration plan, discussed below.
Step 1: Inventory Your Ingress Footprint
Start by finding every cluster and namespace that depends on Ingress NGINX. The Kubernetes guidance suggests checking for controller pods with the label app.kubernetes.io/name=ingress-nginx across all namespaces, and IngressClass objects whose controller is k8s.io/ingress-nginx. For each cluster, capture:
- All Ingress resources that use the ingress-nginx class, including those relying on a default class.
- Every nginx.ingress.kubernetes.io annotation in use, grouped by frequency. A small number of annotations usually account for most usage, with a long tail of rare ones.
- Global settings in the controller’s ConfigMap, such as timeouts, buffer sizes, header handling, SSL policies and custom error pages.
- Any configuration snippets, Lua plugins or custom templates, which will need special attention.
- TLS certificate management, typically cert-manager integrations, and external DNS automation.
- Upstream dependencies such as cloud load balancers, web application firewalls and CDN rules that point at the controller.
This inventory determines effort. A cluster with standard host and path routing and a handful of common annotations can migrate quickly; a cluster that relies on snippets for authentication, rate limiting or rewrites needs design work.
Step 2: Choose Your Implementation
Select a Gateway API implementation based on a few practical criteria:
- Feature coverage for your inventory: authentication integrations, rate limiting, rewrites, session affinity, WebSockets, gRPC and mutual TLS.
- Operational fit: whether you prefer a cloud-managed gateway tied to your provider’s load balancers or a portable, in-cluster data plane you operate yourself.
- Ecosystem alignment: if you already run a service mesh or a CNI with gateway capabilities, using the same project can reduce moving parts.
- Conformance and maturity: check the implementation’s conformance reports, release cadence and maintainer base, the very issue that led to Ingress NGINX’s retirement.
- Support model: community-only, vendor-supported or included in a managed platform.
Run a proof of concept with your most demanding real application rather than a hello-world service. The right choice for a single-cloud organization standardized on one provider may differ from that of a multi-cloud platform team that values portability.
Step 3: Translate Configuration
The Kubernetes SIGs project ingress2gateway converts Ingress resources and provider-specific configuration into Gateway API resources, and version 1.0 was announced in March 2026 specifically to support the Ingress NGINX exodus. Use it to generate a first draft of Gateways and HTTPRoutes, then review the output carefully. Automated translation handles host and path rules well, but annotations and global settings need human judgment:
- Map common annotations, such as rewrites, redirects, timeouts and backend protocol, to native HTTPRoute filters or implementation policies.
- Replace snippet-based logic with supported features, external authorization services or policy attachments; do not try to recreate arbitrary configuration injection.
- Translate ConfigMap-level defaults into Gateway or implementation-level policies so behavior does not silently change.
- Decide on ownership: one shared Gateway per environment managed by the platform team, with application teams owning their own Routes, is a common and effective model.
The Kubernetes blog published a dedicated warning before migrations began: Ingress NGINX has several surprising defaults and side effects, and a translation that looks correct on paper can still cause outages if it ignores them. Examples of areas to verify include path matching semantics, regular expression behavior, default timeouts, request body size limits, header forwarding and how redirects and trailing slashes are handled.
Treat the Ingress NGINX retirement as an edge migration, not a YAML conversion. The risk lives in implicit defaults and annotations, so test real traffic behavior before you move a single production hostname.
Step 4: Test, Run in Parallel and Cut Over
The safest migrations run the old and new data planes side by side. Deploy the Gateway implementation alongside Ingress NGINX, with its own load balancer address. Then proceed service by service:
- Create Routes for one low-risk application and test it directly against the new gateway address using host overrides.
- Compare behavior with automated tests and recorded requests: status codes, headers, redirects, response bodies, latency and TLS details.
- Shift a small share of production traffic using DNS weighting or an upstream load balancer, and monitor error rates and latency.
- Increase traffic progressively until the application is fully on the new gateway, keeping the Ingress resource as a rollback path for a defined period.
- Repeat for remaining applications, then remove Ingress NGINX and its load balancer once all traffic has moved.
Coordinate with teams that own DNS, certificates, firewalls and CDNs. Many migration incidents come not from the gateway itself but from a forgotten allowlist of load balancer IP addresses or a certificate that was issued to the old endpoint.
Worked Example: A SaaS Platform with Three Clusters
Consider a hypothetical SaaS company running production, staging and a regional cluster, each with Ingress NGINX fronting around 60 services. The inventory shows that most Ingresses use only host and path routing with TLS, but about a dozen rely on annotations for URL rewrites, larger request bodies for file uploads and long timeouts for reporting endpoints, and two use configuration snippets to add security headers and basic authentication.
The platform team chooses a portable Gateway API implementation that matches the CNI it already runs, and creates one shared Gateway per cluster with listeners for each domain. ingress2gateway generates draft HTTPRoutes, which squads review in pull requests. Rewrites and timeouts map to native filters and implementation policies; security headers move to response header modifiers; basic authentication is replaced by the company’s existing single sign-on through an external authorization integration. The team discovers during parallel testing that one service depended on Ingress NGINX’s regular expression path behavior and adjusts the route accordingly. Staging migrates first, then the regional cluster and finally production, with traffic shifted gradually per hostname. The old controller is removed after a two-week rollback window.
Beyond removing an unpatched component, the company gains clearer ownership: application teams manage their routes through Git with platform-defined guardrails, rather than requesting annotation changes from a central team.
Operating Gateway API After the Migration
Cutting over traffic is the midpoint, not the end. Gateway API changes how teams collaborate on the edge, and the operating model needs to catch up. Define which team owns GatewayClasses and Gateways, typically the platform team, and which teams may create Routes in which namespaces. Use ReferenceGrants and allowed-route settings on listeners deliberately, so application teams can attach routes to shared gateways without being able to hijack another team’s hostname. Manage all gateway and route definitions through Git with automated validation, and add policy checks that reject routes without TLS, routes that expose internal paths or routes that bypass required authentication.
Observability also deserves attention. Make sure the new data plane exports request metrics, access logs and traces into the same tools your teams already use, with labels for route, backend and namespace. Build dashboards per application so teams can see their own error rates and latency at the edge, and alert on certificate expiry and configuration rejections, since a Route that fails validation may simply not be programmed. Finally, keep the implementation itself current. One of the reasons this migration became urgent is that an edge component fell behind; schedule regular upgrades of the gateway controller and its data plane, and track the Gateway API release channels you depend on.
Migration Readiness Checklist
- Every Ingress NGINX installation and IngressClass identified across all clusters and environments.
- Annotation and ConfigMap inventory complete, with a mapping decision for each item.
- Snippets and custom templates replaced with supported features or external services.
- Gateway implementation selected after a proof of concept with a demanding real workload.
- Gateway ownership, RBAC and route attachment rules documented.
- Behavioral comparison tests prepared for redirects, headers, timeouts, body sizes and path matching.
- DNS, certificate, firewall and CDN owners engaged, with a rollback plan per hostname.
- Monitoring and alerting for the new data plane in place before the first production cutover.
If You Cannot Migrate Yet
Some organizations will not complete migration immediately. In that case, reduce risk while you work: disable snippet annotations if they are not needed, restrict who can create or modify Ingress resources, place the controller behind a web application firewall, monitor security advisories closely, and document a time-boxed risk acceptance. Alternatively, as an interim step, move to another maintained Ingress controller that supports the Ingress API, then migrate to Gateway API later. This two-step path can make sense for very large estates, but it means migrating twice, so weigh it carefully.
Whatever interim path you choose, give it an owner and a date. Edge components tend to be shared by many teams and owned by none, which is exactly how an unmaintained controller ends up in production years after its warnings began. Put the remaining clusters on a visible tracker, review progress in regular platform governance meetings and treat each migrated environment as a milestone. Budget for the work explicitly: an edge migration touches networking, security, certificates and every application team, and it rarely fits into spare capacity alongside feature work.
Outlook: The Edge as a Platform Product
Gateway API is becoming the common language for north-south traffic in Kubernetes, and increasingly for service mesh and AI inference routing as well, with community work extending gateways to model-serving workloads. Treating ingress as a platform product, with clear ownership, versioned policies and self-service routes, will matter more as clusters host more teams and more types of traffic. The retirement of Ingress NGINX is an uncomfortable deadline, but it is also an opportunity to replace annotation sprawl with a cleaner, more secure model.
Conclusion
If your clusters still run the community Ingress NGINX controller, you are operating an unmaintained component at the edge of your applications. The path forward is well understood: inventory your usage, choose a conformant Gateway API implementation, translate configuration with ingress2gateway and careful review, then migrate service by service with parallel running and progressive traffic shifting. Pay special attention to annotations, snippets and implicit defaults, because that is where outages hide. Done methodically, the migration closes a security gap and leaves you with a more expressive, role-based traffic layer for the next decade of Kubernetes.
How Hanoi Technology Can Help
Hanoi Technology helps platform teams inventory Ingress NGINX usage, select a Gateway API implementation and migrate production traffic safely with parallel running and progressive cutover.