Migrare da Ingress NGINX senza incidenti

Seamless Migration from Ingress NGINX

2026-03-03
Migrare da Ingress NGINX senza incidenti

Sommario

Ingress NGINX va in retirement a marzo 2026 e molte organizzazioni stanno accelerando verso Gateway API. Il rischio non è “tradurre gli Ingress”, ma cambiare semantica senza accorgersene: redirect impliciti, regex permissive, normalizzazione degli URL e side effect delle annotation.

Contesto e problema

Il punto di partenza pragmatico è capire se un cluster dipende davvero da Ingress NGINX, non da “un ingress controller qualunque”. In ambienti grandi la risposta è spesso “sì” per inerzia, perché Ingress NGINX è stato il default di fatto per anni. Un controllo rapido, con privilegi da admin, è individuare i Pod etichettati dal progetto:

kubectl get pods --all-namespaces --selector app.kubernetes.io/name=ingress-nginx

Il motivo per cui questa migrazione è delicata non è la complessità della API Ingress, ma la semantica storica accumulata nelle annotation e in alcuni default “sorprendenti”. Nel post Kubernetes del 27 febbraio 2026, SIG Network evidenzia cinque comportamenti che, se tradotti alla lettera in Gateway API, possono generare regressioni.

  • Regex: Ingress NGINX tratta spesso le regex come prefix-based e case-insensitive.
  • Scope: nginx.ingress.kubernetes.io/use-regex può “contagiare” tutte le path di uno stesso host, anche su Ingress diversi.
  • Side effect: nginx.ingress.kubernetes.io/rewrite-target implica regex anche senza use-regex.
  • Trailing slash: Ingress NGINX può introdurre redirect 301 impliciti tra path che differiscono solo per lo slash finale.
  • Normalizzazione: Ingress NGINX normalizza gli URL prima del match (ad esempio segmenti . e .., slash ripetuti).

Il pattern ricorrente è che in Ingress NGINX molti team hanno beneficiato di una tolleranza implicita. In Gateway API, le stesse regole diventano più esplicite e quindi più prevedibili, ma solo se un team decide quali comportamenti preservare.

Sviluppo tecnico

Una migrazione enterprise ragionevole inizia con un inventario semantico, non solo con un inventario di risorse.

1) Classificare i casi a rischio. Se un Ingress usa regex, rewrite o si affida a redirect, un team deve trattarlo come “comportamento”, non come “config”. Nella stessa categoria entrano le path ImplementationSpecific, perché spesso dipendono dal controller.

2) Scegliere la semantica dell’implementazione Gateway API. In molte soluzioni Envoy-based le regex tendono a essere più vicine a un full match e spesso case-sensitive. Questo aumenta la prevedibilità, ma rompe configurazioni che in Ingress NGINX matchavano “per caso”.

3) Rendere esplicite le dipendenze. Se dei client dipendono dal redirect del trailing slash, la route deve dichiararlo. Se un rewrite stava assorbendo typo di casing o path, un team deve decidere se correggere i client o replicare consapevolmente la permissività.

In parallelo, Ingress2Gateway è utile come acceleratore e come strumento di discovery: traduce il boilerplate e segnala dove Ingress NGINX stava introducendo side effect. Quando uno strumento non può esprimere un comportamento, quel limite diventa una decisione architetturale, non un dettaglio di conversione.

Gateway API 1.5 (rilasciata il 27 febbraio 2026) aggiunge feature utili in contesti multi-team, come ListenerSet per gestire certificati TLS e un filtro CORS in HTTPRoute. Il valore, dal punto di vista platform, è separare ruoli e blast radius: policy e listener centralizzati, route delegate ai team.

Implicazioni pratiche in produzione

In un settore regolato, io tratto questa migrazione come un change di security boundary. Quando cambia la normalizzazione di un URL o il modo in cui una regex matcha, cambia anche il perimetro di ciò che arriva ai backend.

Due controlli che pagano subito: monitorare 404 e 301 durante canary e correlare per host e path. Quando compaiono 404 “nuovi” su path storicamente raggiungibili, spesso sta emergendo un comportamento permissivo di Ingress NGINX (case-insensitive, prefix, redirect impliciti) che la nuova implementazione non replica.

Conclusione

La migrazione da Ingress NGINX verso Gateway API non è un esercizio di conversione YAML, è un lavoro di chiarificazione semantica. Il modo più veloce per evitare incidenti è trattare regex, rewrite, redirect e normalizzazione come requisiti espliciti, scegliere consapevolmente la semantica della propria implementazione Gateway API, e usare strumenti come Ingress2Gateway per scoprire dove Ingress NGINX stava “aggiustando” il traffico a tua insaputa.

Summary

Ingress NGINX is retiring in March 2026, and many organizations are accelerating towards Gateway API. The risk isn’t “translating the Ingresses,” but changing semantics without realizing it: implicit redirects, permissive regex, URL normalization, and side effects of annotations.

Context and Problem

The pragmatic starting point is understanding whether a cluster truly depends on Ingress NGINX, not just “any ingress controller.” In large environments, the answer is often “yes” due to inertia, as Ingress NGINX has been the de facto default for years. A quick check, with admin privileges, is to identify Pods labeled by the project:

kubectl get pods --all-namespaces --selector app.kubernetes.io/name=ingress-nginx

The reason this migration is delicate isn’t the complexity of the Ingress API, but the historical semantics accumulated in annotations and some surprising defaults. In the February 27, 2026 Kubernetes post, SIG Network highlights five behaviors that, if translated literally into Gateway API, can generate regressions.

  • Regex: Ingress NGINX often treats regex as prefix-based and case-insensitive.
  • Scope: nginx.ingress.kubernetes.io/use-regex can “infect” all paths of the same host, even on different Ingresses.
  • Side effect: nginx.ingress.kubernetes.io/rewrite-target implies regex even without use-regex.
  • Trailing slash: Ingress NGINX can introduce implicit 301 redirects between paths that differ only by the trailing slash.
  • Normalization: Ingress NGINX normalizes URLs before matching (e.g., segments . and .., repeated slashes).

The recurring pattern is that in Ingress NGINX many teams have benefited from implicit tolerance. In Gateway API, the same rules become more explicit and therefore more predictable, but only if a team decides which behaviors to preserve.

Technical Development

A reasonable enterprise migration starts with a semantic inventory, not just a resource inventory.

1) Classify at-risk cases. If an Ingress uses regex, rewrite, or relies on redirects, a team must treat it as “behavior,” not “config.” Paths ImplementationSpecific also fall into this category, as they often depend on the controller.

2) Choose the semantics of the Gateway API implementation. In many Envoy-based solutions, regex tends to be closer to a full match and often case-sensitive. This increases predictability, but breaks configurations that matched “by chance” in Ingress NGINX.

3) Make dependencies explicit. If clients depend on the redirect of the trailing slash, the route must declare it. If a rewrite was absorbing casing typos or path errors, a team must decide whether to fix the clients or consciously replicate the permissiveness.

In parallel, Ingress2Gateway is useful as an accelerator and discovery tool: it translates the boilerplate and flags where Ingress NGINX was introducing side effects. When a tool cannot express a behavior, that limitation becomes an architectural decision, not a conversion detail.

Gateway API 1.5 (released February 27, 2026) adds useful features in multi-team contexts, such as ListenerSet for managing TLS certificates and a CORS filter in HTTPRoute. From a platform perspective, the value is separating roles and blast radius: centralized policies and listeners, routes delegated to teams.

Practical Implications in Production

In a regulated industry, I treat this migration as a security boundary change. When URL normalization or how a regex matches changes, so does the perimeter of what reaches the backends.

Two checks that pay off immediately: monitor 404s and 301s during canary and correlate by host and path. When “new” 404s appear on historically reachable paths, a permissive behavior of Ingress NGINX (case-insensitive, prefix, implicit redirects) that the new implementation does not replicate is often emerging.

Conclusion

Migrating from Ingress NGINX to Gateway API isn’t a YAML conversion exercise; it’s a semantic clarification effort. The fastest way to avoid incidents is to treat regex, rewrite, redirects, and normalization as explicit requirements, consciously choose the semantics of your Gateway API implementation, and use tools like Ingress2Gateway to discover where Ingress NGINX was “fixing” traffic without your knowledge.