Migrate from Ingress NGINX to Gateway API

The ingress2gateway tool reads existing Ingress resources and emits Gateway API objects, such as Gateway and HTTPRoute resources, that your team can review and apply. Its purpose is to shorten the translation work for the hosts, paths, backends and TLS references you already run, so reviewers spend their time on routing behavior instead of retyping YAML. Treat its output as a starting draft. The core Ingress fields are the easiest part to map. The harder part is that Ingress NGINX adds much of its behavior through controller-specific annotations, and a converter can only carry over what it knows how to translate. Plan the migration around that gap from the first run.

Annotations are where most of the review effort belongs. Ingress NGINX relies heavily on annotations for URL rewriting, request body size limits, timeouts, authentication, redirects and custom configuration snippets. Expect the tool to translate some of these categories into Gateway API filters or policies, to report others as unsupported, and to skip some with only a log message or no message at all. A clean run does not prove that every annotation was carried over. Before you rely on the output, check the tool's own documentation for the annotation keys it handles, what it emits for each one, and where its warnings are written so you can collect them as part of the change record.

Confirm several details in the tool's documentation before you plan around it. Check the current release version, the input sources it accepts (a live cluster, exported manifests or both), the output options and any provider-specific settings, and how it names and groups the generated objects. This page does not state those details, and they can change between releases. Record the exact tool version and the command-line options you used in the migration change record, so the conversion can be reproduced during review and repeated if the source Ingress objects change before cutover.

Compare the generated manifests with what the live cluster actually serves. Export the current Ingress objects, then check hostnames, path matching rules, TLS secret references and backend services against the generated Gateway and route objects. Review the controller's global settings as well, because options set in the Ingress NGINX ConfigMap apply across all routes and will not appear in any Ingress object the converter reads. For each unsupported or ignored annotation, record either a replacement in the target implementation or a documented decision to drop it. The conversion also does not select a Gateway API implementation, set its addresses or define how traffic moves between the old and new controllers, so those decisions stay with your team.

The first decision is which annotations your estate actually uses, because that inventory sets the shortlist. Gateway API is a specification, and each controller implements a subset of it. Ingress NGINX users relied on many behaviors expressed as annotations, such as rewrites, body size limits, timeouts and authentication hooks. The specification has no standard field for many of these, so each implementation covers them through its own extensions, custom resources or filters, or does not cover them at all. Export the annotation usage from every Ingress object, group it by behavior, and mark which behaviors the converted routes must keep. Then check each candidate against that list line by line.

Next, decide whether you need policy attachment for authentication and rate limits. In Gateway API, policies attach to Gateways, listeners or routes through objects that differ between implementations, so the same intent may be written in different ways and may be supported only in certain controller releases. Ask who will own those policy objects, whether they live in Git next to the routes, and how the team will detect a policy that fails to attach. Ask each vendor to show the attachment status of a test policy on a test route, and confirm that the status is visible to the platform team without cluster admin access.

Third, examine how the controller integrates with the load balancer and certificate management. Ingress NGINX often ran behind a load balancer or node ports that the platform team had already set up, so the replacement may need a different service type, a new external address or a changed firewall rule. Confirm how the controller obtains its external address, whether it reads TLS material from the same Secrets used today, how certificate renewal reaches the listeners without a restart, and whether the cluster's network policies allow the new data path. Write these answers down before the pilot starts, because they often decide the cutover window.

Fourth, choose an operating model the platform team can support. Check the controller's release cadence, how it handles upgrades of its own custom resources, which logs and metrics it exposes, and where its troubleshooting documentation lives. Decide who will answer a production incident at two in the morning and whether that person has access to the controller's configuration. Because the controller sits on the request path, its own upgrade plan belongs in the selection decision, not in a later phase.

Before committing, run a conformance and feature check against your own route set. Take a representative sample of converted routes, including the most annotation-heavy ones, deploy them to a non-production cluster running each candidate, and compare responses, headers, redirects, timeouts, body limits and authentication outcomes with the live Ingress NGINX behavior. A conformance suite result shows that the controller meets the specification, but it does not test your behaviors. A clean ingress2gateway run shows only that the conversion produced objects. It does not prove that the target controller handles those objects the same way. Record every difference as accepted, fixed or blocking.

Run both controllers at the same time, each behind its own entry point, so Ingress NGINX keeps serving today's traffic while the Gateway API implementation is proven on the same hostnames. In practice, the existing Ingress NGINX controller keeps its Service and external load balancer address, and the new Gateway implementation gets its own Gateway resource with a separate address. Review the Ingress and Gateway resources side by side before applying anything, and confirm that no two resources claim the same hostname in a way that could split traffic unexpectedly. Record both addresses in a cutover inventory that lists every hostname, its owner and the entry point it uses today.

Choose one method for moving hostnames and use it for the whole cutover, so operators read one set of signals. The first method is a DNS record change per hostname, where the record moves from the old address to the new one after its TTL has been lowered in advance. The second is weighted routing at the load balancer or DNS platform, which sends a fraction of requests to the new entry point. The third is a dedicated test hostname that only the new path serves, used by internal testers and a small client group before the production name moves. Weighted routing details differ by load balancer and DNS platform, including record types, weight granularity and how health checks interact with weights. Confirm each capability with your provider before you design the sequence.

Certificates must work on both paths before any traffic moves. Each hostname needs a certificate that both controllers can present, either from the same Kubernetes TLS Secret referenced by the Ingress and the Gateway listener, or from a second copy issued by the same certificate authority. Check the full chain, the subject alternative names and the expiry on each entry point with a test client that sets the server name explicitly, because a path that answers with a default certificate can look healthy in a basic probe. At the load balancer, configure health checks for each entry point against the controller's readiness and backend health signals. Add weight to the new path only after its targets pass consistently through the observation window your team agreed.

Monitor each path separately from the first moment it receives traffic. Label or segment metrics by entry point or controller so error rates, latency percentiles and request volume for the Ingress NGINX path and the Gateway path can be compared hostname by hostname. Set thresholds for 5xx responses, timeouts and tail latency before the first shift, and agree who watches them and who may stop the shift. Compare the new path against a baseline taken from the old path over the same period, since traffic mix changes through the day. Confirm with your platform team which monitoring stack collects controller metrics in your environment, because metric names and labels vary between controller implementations.

Write a rollback step for each hostname before its first shift, and rehearse it in a non-production environment. The step should name the exact record or weight to change, the value it returns to, how long clients may take to see the change given the TTL, and the person authorized to run it. Keep the Ingress resources and the old controller running until every hostname has stayed stable through the agreed window, because removing them early removes the fastest rollback path. Lower TTLs speed rollback but increase resolver load, so decide the TTL for each hostname and record that choice in the cutover plan.