From ingress-nginx to Gateway API: a migration checklist

The Kubernetes project announced that maintenance of ingress-nginx would end in March 2026, with no further fixes for either defects or vulnerabilities. The recommendation is to move to Gateway API. Source: retirement announcement.

Checklist

1. Inventory. List all Ingress resources, classes and nginx.ingress.kubernetes.io/* annotations in use. Annotations are the critical point: each one has to be translated.
2. Choosing an implementation. Gateway API is a specification; you need a controller that implements it (for example Cilium, Envoy Gateway, Istio, NGINX Gateway Fabric or your cloud provider’s own). Assess support, security and operating costs.
3. Trial conversion. The ingress2gateway tool, cited in the retirement announcement, generates a draft Gateway and HTTPRoute. It is not 100% automatic: review every rule.
4. Functional parity. Check path rewrites, TLS, timeouts, size limits, authentication, CORS and rate limiting. Anything without an equivalent must be handled with a policy of the chosen controller.
5. Test environment. Replicate the critical paths and run automated tests against the expected responses.
6. Parallel run. Put the new gateway alongside the old ingress, on a different address, and shift traffic gradually (DNS weighting or an upstream load balancer).
7. Observability. Compare response codes, latencies and logs between old and new before each step.
8. Rollback. Keep the old ingress active until you have a stable period of traffic on the new one.
9. Clean-up. Remove the controller, the annotations and any unused resources; update the documentation.

Common mistakes

• Treating the automatic conversion as finished.
• Forgetting certificates and automatic renewal.
• Changing the gateway and the Kubernetes version at the same time: two variables are too many.

If you want a plan tailored to your cluster, see Kubernetes and cloud native platforms.