Navigating the ingress-NGINX Retirement: Migration Paths for Production Clusters

Summary

The ingress-nginx community controller reached end-of-life in March 2026. The Kubernetes Ingress API itself remains supported — only this specific controller implementation is retiring. Running ingress-nginx past EOL means operating on unpatched CVEs with no upstream support or feature updates. Migration is not optional.

Pre-requisites

• Inventory all ingress-nginx resources and custom nginx.ingress.kubernetes.io/* annotations in your cluster
• Identify which annotations have no direct equivalent in target controller (these require manual rework)
• Run kubectl get ingress --all-namespaces to scope the migration surface area
• Test both paths in a non-production environment before production rollout

Migration Paths

Path A: Lift-and-Shift to Alternative Ingress Controller

The lower-effort path. Migrate to an actively maintained Ingress controller while keeping your existing Ingress YAML resources.

Recommended controller: Envoy-based alternatives (e.g., Contour)

1. Install the target controller in parallel with ingress-nginx
2. Audit all nginx.ingress.kubernetes.io/* annotations — these are controller-specific and will break silently on a different controller
3. Translate annotations to the target controller’s equivalents using the controller’s migration documentation
4. Test routing behavior in staging
5. Shift traffic incrementally using canary or blue/green patterns
6. Remove ingress-nginx after validation

Trade-off: Keeps the existing Ingress API surface. No Gateway API benefit — you remain on a feature-frozen API specification with no upstream roadmap.

Path B: Gateway API Adoption

The higher-effort path with the strongest long-term position. The Kubernetes Gateway API is the upstream-backed successor to the Ingress API — role-oriented, actively developed, with advanced routing capabilities built into the core spec.

1. Install a Gateway API-compatible controller (Envoy Gateway, Istio Gateway, Cilium, others)
2. Use the ingress2gateway CLI tool to translate existing Ingress resources to Gateway API equivalents: ingress2gateway print --namespace <ns>
3. Review translated output — complex nginx annotations will require manual Gateway API equivalents (HTTPRoute filters, middleware chains)
4. Deploy Gateway API resources alongside existing Ingress resources
5. Validate routing parity in staging
6. Incrementally shift traffic and remove Ingress resources

Trade-off: Higher migration effort, more objects to manage (GatewayClass, Gateway, HTTPRoute vs. single Ingress). Benefits: active upstream development, role separation between infra operators and application developers, advanced routing without annotations.

The Trap

Don’t assume annotation compatibility. The most common failure mode in ingress-nginx migrations is treating nginx.ingress.kubernetes.io/* annotations as portable. They’re not — they’re implementation details of the nginx controller. Every annotation in production must be audited and mapped to the target controller’s feature set before cutover. Silent routing failures after migration almost always trace back to untranslated annotations.

Cited References

• CNCF: Navigating the ingress-NGINX Retirement
• Kubernetes Gateway API documentation
• ingress2gateway migration tool

Source: CNCF Blog

Content created with AI assistance and reviewed for accuracy.