Ingress NGINX Migration: A Practical Cutover and Acceptance Checklist

Inventory behavior before translating manifests

If your cluster still runs the community Ingress NGINX controller, migration is an operational task to schedule, not a distant roadmap item. Kubernetes announced its retirement for March 2026 and urged users to move to supported alternatives. See the Kubernetes steering and security committees' statement.

Be precise about the name: this concerns the community kubernetes/ingress-nginx project. It is not a statement that every NGINX-based product or the Kubernetes Ingress API has disappeared.

This guide focuses on migration acceptance and cutover. For a broader choice of proxy tools, use our existing NGINX, Traefik and Caddy comparison.

Find the controller and its real dependencies

Begin with read-only inventory commands against the intended cluster:

kubectl get ingressclass
kubectl get ingress -A
kubectl get deployments,daemonsets -A

Match ingress classes to the controller deployment, image and ownership information. Do not assume a namespace name proves which implementation is installed.

For every public hostname, record the application owner, certificate source, upstream service, exposed paths and any annotations or custom configuration. Include internal routes, preview environments and administrative endpoints. The route that receives no traffic during business hours may still be essential to a nightly integration.

Export only the configuration you need for the review and store it in an approved location. There is no reason to collect Kubernetes Secret values as part of this inventory.

Choose a supported target by required features

Gateway API is a set of APIs, not a replacement proxy you can install by itself. You need an implementation that supports the resources and features your applications require. Compare the implementation's current documentation, supported versions and operating model.

A supported Ingress controller may also be a reasonable destination. The acceptance criteria should decide the choice: authentication, traffic handling, observability, ownership and maintenance, rather than the number of lines saved in YAML.

Our suggested feature matrix has one row per requirement and columns for the current behavior, target behavior, migration mechanism and verification test. Mark unsupported behavior explicitly. An annotation that has no equivalent is a design decision, not a field to silently drop.

Treat generated configuration as a draft

Ingress2Gateway can help translate configuration, but its maintainers describe it as a migration assistant. Review its output against your chosen implementation and your applications.

The Kubernetes project also documents surprising Ingress NGINX behavior, including matching and redirects that may not transfer as expected. The practical lesson is to test externally observable behavior, not just whether an API server accepts the new resources.

For example, a route can return HTTP 200 while authentication has been bypassed, or a valid login can fail because a callback redirect changed. A manifest validation step will not tell you either story.

Build a small contract test for every important route

Write down representative requests and their expected outcomes before moving traffic:

• A permitted request reaches the correct upstream.
• An unauthenticated request is rejected or redirected as intended.
• Unknown paths and hosts return the intended error.
• HTTP-to-HTTPS and application redirects preserve the right destination.
• Large uploads, streaming responses and long-running requests behave as required.
• Forwarded headers and client identity reach the application correctly.
• Certificates validate for every served hostname.

Add application-specific cases such as WebSockets, gRPC, callbacks or IP restrictions where they exist. Do not test features simply because they appear in a generic checklist; test the features your customers depend on.

Preserve the old and new response evidence in a reviewable form. Redact session cookies, authentication headers and customer payloads before attaching it to a ticket.

Rehearse cutover and recovery separately

Bring up the target path alongside the existing path where your architecture permits it. Validate it with controlled test hostnames or an approved traffic-routing method. Review external DNS automation and certificate controllers so they do not unexpectedly compete over the same records or secrets.

Choose a low-risk application first. Monitor application error rates, latency, authentication failures and upstream health, then increase exposure deliberately. A load balancer reporting healthy targets is only one of those signals.

Define who can move traffic back, what triggers that decision and how long changes may take to propagate. Keep application teams available during the observation period. Do not remove the old path until the new one has passed the agreed tests and recovery no longer depends on it.

Agree on the deliverable, not just the replacement

A completed migration should leave the team with the supported controller configuration, route tests, certificate and DNS ownership, dashboards, recovery instructions and a maintenance owner. Record any intentionally changed behavior so support teams know what customers will see.

If the migration spans many services, book an introductory call with InstaDevOps. We can scope a route inventory, compatibility review and staged cutover. Ongoing maintenance can then be agreed separately through managed Kubernetes, with explicit coverage and responsibilities.