Ingress-NGINX Retirement: A Kubernetes Migration Playbook for 2026

February 12, 2026•Stackxx•Kubernetes

Kubernetes rarely breaks you all at once. It breaks you with boring dependencies you stopped thinking about years ago: a controller that “just works”, an annotation you copied from a Helm chart, a default install you never revisited. That’s why the retirement/archival of ingress-nginx is a big deal. It’s not that NGINX suddenly stopped being good at proxying HTTP. It’s that a widely-deployed community controller is approaching a point where you should no longer assume upstream maintenance, fixes, or security patches.

This article is a playbook for platform teams: how to scope your risk, pick a migration path, and execute a controlled cutover without turning your cluster edge into a science fair project.

What “retirement” means in practice

When a project is archived/retired, the immediate operational impact is subtle: your cluster doesn’t stop routing traffic tomorrow. The problem is the future—new Kubernetes versions, new CVEs, new protocol expectations, and new integrations will keep coming. If your ingress controller isn’t getting updates, you’re slowly converting a core control-plane component into a liability.

The CNCF write-up frames the decision bluntly: either keep a critical component without upstream maintenance, or move to an actively supported alternative. It also notes that the ecosystem direction is increasingly aligned with the Gateway API as the long-term traffic-management model.

Step 1: Inventory what you actually use

Before you choose “Traefik vs HAProxy vs Cilium vs something else”, you need to know what you’re migrating. The trap is assuming you use “just basic Ingress”. Many orgs run an accidental API surface area of annotations and NGINX-specific behaviors.

Do a fast inventory across namespaces:

Hosts / paths: wildcard hosts, path rewrites, regex paths, sub-path apps.
TLS: cert-manager integration, SNI edge cases, legacy ciphers you forgot exist.
Annotations: rate limits, auth, custom snippets, timeouts, proxy buffer settings.
Traffic patterns: canarying, weighted routing, header-based routing, blue/green.
Operational expectations: metrics, logs, dashboards, alerting, runbooks.

Be honest about the “we used this once” features. Anything that depends on NGINX-only annotations is a migration task, not a checkbox.

Step 2: Choose your target path (Ingress replacement vs Gateway API)

You have two broad approaches:

Option A: Replace the Ingress controller (fastest)

If you need a low-risk, low-change path, a drop-in Ingress controller replacement can be the right first step. The CNCF post specifically points to Cilium Ingress as a drop-in option that lets you keep using Ingress resources while getting an actively maintained datapath and better observability/policy integration.

Why teams pick this approach:

Minimal app manifest churn (mostly ingressClassName and annotation cleanup).
Faster “get off the retirement cliff” timeline.
Allows a second phase later (Gateway API) once the bleeding edge is stabilized.

The cost: you may keep living with Ingress’ structural limitations, and you’ll still need a plan for features that were “easy” only because NGINX tolerated endless annotation knobs.

Option B: Adopt Gateway API (recommended long-term)

The Gateway API is positioned as the successor to Ingress. Instead of a single resource carrying infrastructure + app intent in one blob, it’s designed for clearer role separation (platform vs app teams) and richer routing primitives (header-based routing, traffic splitting, cross-namespace routes, and more).

Gateway API adoption is not “just a new YAML schema”. It changes how you manage ownership and change control:

Platform teams define GatewayClass and Gateway (edge infrastructure).
App teams define HTTPRoute / GRPCRoute and attach to approved gateways.
Policy teams can enforce consistent behavior with separate policy objects or controller features.

Step 3: Design your migration in phases (don’t big-bang it)

A practical sequence that keeps risk low:

Staging parity: stand up the new controller (or Gateway implementation) in staging, and replay your known traffic and test suite.
Dual-run in production (where possible): provision the new controller and routes, but keep traffic on the old ingress. Validate health, metrics, and failure behavior.
Cut over by host: move one host/domain at a time, starting with low-blast-radius services.
Decommission NGINX-specific behaviors: remove annotations/snippets you can’t carry forward. Replace with standardized routing or app-level behavior.
Lock in guardrails: admission policies, linting, and CI checks so new Ingress objects don’t re-introduce legacy patterns.

Compatibility traps to watch for

Rewrite semantics: different controllers interpret path rewrites differently. Verify, don’t assume.
Timeout defaults: what used to “just work” might now fail under load due to different timeouts.
Request/response sizes: buffer settings may differ; some apps rely on large headers or cookies.
Auth flows: external auth, OIDC, and mTLS termination vary widely by controller.
Observability drift: metrics names/labels change; dashboards need updates or they silently go stale.

Why this lines up with Kubernetes v1.35’s “operator reality”

Kubernetes continues to push features that reduce operational hacks and sidecars. For example, v1.35 highlights native building blocks like in-place resource updates for Pods and new workload identity/certificate primitives. The theme is consistent: fewer external duct-tape controllers, more standardized APIs, and more explicit separation of concerns.

Gateway API is the networking version of that same direction. If you treat ingress-nginx retirement as a forcing function to modernize your edge stack, you’re not just swapping proxies—you’re aligning with where Kubernetes is going.

A simple decision framework

If you’re heavily dependent on NGINX annotations/snippets and need speed: do an Ingress replacement first, then plan Gateway API as phase 2.
If you’re already practicing GitOps + clear platform/app separation: move to Gateway API sooner and use the migration to formalize ownership.
If you’re multi-tenant: prioritize solutions with strong policy integration and route isolation.

Sources

Next signal