# Ingress NGINX retires in March 2026: a practical migration playbook for Gateway API - Link: https://thestackobserver.com/ingress-nginx-retires-in-march-2026-a-practical-migration-playbook-for-gateway-api/ - Published: 2026-02-15T09:44:35-05:00 - Author: Stackxx Kubernetes has a long history of “works everywhere” building blocks, and few have been as broadly deployed as the community Ingress NGINX controller. That ubiquity is exactly why this week’s announcement matters: Kubernetes SIG Network and the Security Response Committee have announced the upcoming _retirement of Ingress NGINX_, with best‑effort maintenance continuing until **March 2026**, and then no releases, no bug fixes, and no security updates going forward. The good news: existing deployments won’t suddenly stop routing traffic. The bad news: the clock starts ticking the moment you realize how many clusters “just have it” (often via a managed distro default), and how many security assumptions you’ve built around a component that will soon be unmaintained. ## What “retirement” actually changes There are two immediate changes you should plan around: * **Security posture changes**: post‑March 2026, newly discovered CVEs and exploitable misconfigurations will not be patched upstream. Even if your cluster is otherwise well‑maintained, your edge becomes the weakest link. * **Operational drift becomes permanent**: “we’ll upgrade later” becomes “there is no later.” The longer you delay, the more divergence you’ll have between your current Ingress usage and the future target (Gateway API or alternative controllers). ## Step 1: inventory where you’re using Ingress NGINX Start by answering three questions per cluster: * Is ingress-nginx installed? (Common label selector: `app.kubernetes.io/name=ingress- nginx`.) * How is it installed/managed? (Helm chart, raw manifests, managed add-on, GitOps.) * What features do you rely on beyond “basic Ingress”? The third question drives your migration complexity. The hardest cases are usually: * “Snippet” annotations and custom NGINX directives * Advanced auth patterns (OIDC, external auth, multiple auth backends) * Exotic rewrites, regex paths, and header manipulation * Large multi-tenant clusters with inconsistent conventions ## Step 2: decide on a target (Gateway API first, controller second) The Kubernetes community is very explicit in its recommendation: **consider migrating to Gateway API** as the modern replacement for Ingress. That’s a subtle but important framing: Gateway API is the _API_, not the implementation. You’ll still choose a controller (Envoy Gateway, HAProxy, Istio, Traefik, cloud load balancer integrations, etc.), but the promise is that you can swap implementations later with far less churn than Ingress-specific annotations ever allowed. For most teams, a good decision process looks like this: * **If you want a standardized, multi-team, policy-driven edge**: pick Gateway API plus a controller that matches your operating model (Kubernetes-native, multi- cluster, service mesh aligned, etc.). * **If you need a fast “drop-in” path**: pick an alternative Ingress controller now, then plan a Gateway API adoption phase later. ## Step 3: map Ingress objects to Gateway API resources At a conceptual level, the migration usually follows this mapping: * **Ingress** → **Gateway** + **HTTPRoute** * TLS settings → **Gateway** listeners + certificateRefs * Path rules / host routing → **HTTPRoute** matches * Per-route filters (headers, redirects, rewrites) → **HTTPRoute** filters Where people get stuck is not the 80% case. It’s the 20%: Ingress annotations that act like “escape hatches.” Those are often exactly the parts that created security risks (and maintenance burden) in the first place. Treat that as a feature: Gateway API forces you to express intent with portable constructs and explicit policies, rather than arbitrary NGINX config. ## Step 4: run a “shadow” deployment and compare behavior A safe migration pattern is to stand up your new Gateway API controller side-by- side, then migrate one hostname (or one path) at a time. Key techniques: * **Dual publishing**: create Gateway + Routes for a service while leaving its Ingress in place. * **Split traffic at the DNS/LB layer** (if possible): gradually shift a percentage of traffic to the new edge. * **Mirroring / canarying**: where your controller supports it, mirror requests to validate upstream behavior without user impact. What to verify before cutover: * Correct TLS chain + SNI behavior * HTTP/2 and gRPC correctness (if used) * Timeouts, request/response size limits, retries * Headers: `X-Forwarded-For`, `X-Request-Id`, auth headers * WAF / rate limiting / bot protection equivalence ## Step 5: remove Ingress NGINX dependencies with a “compatibility budget” To avoid turning this into a multi-quarter rewrite, define a small, explicit budget for compatibility deviations. For example: * “We will not replicate snippet annotations; we will replace them with supported filters or upstream middleware.” * “We will standardize on one auth mechanism per hostname.” * “We will drop regex path matching unless a concrete requirement exists.” This is the moment to align platform engineering, security, and app owners. The retirement is a forcing function: if your edge relies on ungoverned escape hatches, you can either keep paying that cost forever—or use the migration to make the platform safer and more supportable. ## Operational checklist (printable) * Identify clusters using ingress-nginx (including managed distro defaults). * Catalog Ingress usage patterns and “non-portable” annotations. * Select Gateway API controller(s) and define a reference architecture. * Build a golden-path Gateway + HTTPRoute template with policy defaults. * Run side-by-side validation, then migrate in small, reversible batches. * Decommission ingress-nginx before March 2026 (or accept owning the risk). ## Sources * [Ingress NGINX Retirement: What You Need to Know (kubernetes.dev)](https://www.kubernetes.dev/blog/2025/11/12/ingress-nginx-retirement/) * [Gateway API Guides (SIG Network)](https://gateway-api.sigs.k8s.io/guides/) * [Kubernetes documentation: Ingress controllers](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/)