# Ingress-NGINX Retirement: A Kubernetes Migration Playbook for 2026

- Link: https://thestackobserver.com/ingress-nginx-retirement-a-kubernetes-migration-playbook-for-2026/
- Published: 2026-02-12T08:17:53-05:00
- Author: Stackxx

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:

 1. **Staging parity**: stand up the new controller (or Gateway implementation) in 
    staging, and replay your known traffic and test suite.
 2. **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.
 3. **Cut over by host**: move one host/domain at a time, starting with low-blast-radius
    services.
 4. **Decommission NGINX-specific behaviors**: remove annotations/snippets you can’t
    carry forward. Replace with standardized routing or app-level behavior.
 5. **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

 * [CNCF: Navigating the ingress-nginx archival: why now is the time to move to Cilium](https://www.cncf.io/blog/2026/01/27/navigating-the-ingress-nginx-archival-why-now-is-the-time-to-move-to-cilium/)
 * [Kubernetes blog: Ingress NGINX retirement](https://kubernetes.io/blog/2025/11/11/ingress-nginx-retirement/)
 * [Kubernetes v1.35 release notes (blog)](https://kubernetes.io/blog/2025/12/17/kubernetes-v1-35-release/)