After ingress-nginx retirement: validating a parallel Gateway API migration

What it is

Status as of 25 October 2026: the Kubernetes community's Ingress NGINX retirement notice set March 2026 as the end of best-effort maintenance, followed by no further releases, bug fixes or security updates. Existing deployments and installation artefacts remain usable. Re-check the retirement notice and the chosen replacement controller's support and conformance documentation before planning a change. This concerns the community ingress-nginx project; identify the actual controller rather than classifying everything named NGINX alike. Retirement notice.

Why it matters

An available image or working endpoint does not demonstrate ongoing maintenance. Gateway API changes the configuration model: a Gateway describes entry points, while HTTPRoute describes application routing. Controller-specific annotations need an explicit mapping. The general migration guide explains conversion but explicitly does not provide a complete live-migration procedure. Migration model.

The following staged procedure is a proposed operational plan. Its acceptance criteria must cover the application's existing routing and security requirements.

How to apply

• Inventory controllers in every authorised cluster. The retirement notice suggests kubectl get pods --all-namespaces --selector app.kubernetes.io/name=ingress-nginx. Review controller deployments and images as well: a label query alone cannot exclude renamed or customised installations. Record Ingress resources, classes, annotations, TLS references and controller configuration.

• Choose a maintained Gateway API implementation whose conformance and extension support cover the required features. Assign ownership of entry points and routes. The official welcome guide supports running the new controller alongside ingress-nginx with a different external IP, so arrange a separate validation endpoint before changing public traffic. Parallel migration guidance.

• With a reviewed ingress2gateway installation, generate a draft from exported manifests. The official 1.0 announcement documents this form:

  ingress2gateway print --input-file ingress.yaml --providers=ingress-nginx > gateway-draft.yaml
  

  Review the generated resources and all warnings before applying anything. Select the actual replacement GatewayClass and check names, namespaces and backend references. Conversion guidance.

• Resolve every unsupported feature explicitly. That announcement identifies unconverted configuration snippets, approximate timeout translations, body-size limits without a standard equivalent in its example, and URL-normalisation differences. Re-check those mappings against today's API and selected implementation; do not turn a historical converter limitation into a permanent claim about the specification.

• Validate the separate endpoint with the intended hostname and TLS identity. Test redirects, authentication requirements, route precedence, uploads, long-running requests and expected rejection behaviour. Keep this as normal application testing without attack payloads. Compare results with the documented requirements, not merely whether both endpoints return a successful response.

• Move traffic using the site's controlled DNS or load-balancer change process. Observe application errors and access logs, retain a time-limited rollback path, then remove the old controller and unused resources after the observation period succeeds.

Pitfalls

Do not assume generated YAML preserves access controls or that custom extensions are portable between controllers. Parallel deployment also requires clear ownership of DNS and certificate automation. Avoid leaving the retired controller exposed indefinitely as an undocumented backup. Conversion success, controller readiness and correct application behaviour are separate checks.