As the Kubernetes networking community prepares for the retirement of Ingress-NGINX in March 2026, organizations face the critical challenge of migrating to the more powerful Gateway API. This shift isn't just about swapping components—it's a fundamental change in API design. Ingress2Gateway 1.0, recently announced by SIG Network, emerges as a trusted migration assistant, helping teams translate existing Ingress configurations into Gateway API resources safely and efficiently. Below, we answer key questions about this release and how it can simplify your migration journey.

What is Ingress2Gateway and Why Was It Created?

Ingress2Gateway is a tool designed to assist Kubernetes users in migrating from the Ingress API (and its implementations like Ingress-NGINX) to the Gateway API. The Ingress API, while simple, often relies on implementation-specific annotations, ConfigMaps, and Custom Resource Definitions (CRDs) to extend functionality. This makes migration daunting because you must capture all nuances of your current controller and map them to Gateway API equivalents. Ingress2Gateway automates this translation process, converting Ingress resources and annotations into Gateway API manifests while flagging any untranslatable configuration and offering suggestions. Its creation stems from the need for a reliable, tested solution as the community moves toward Gateway API as the standard for Kubernetes networking.

What Key Improvements Does the 1.0 Release Bring?

The 1.0 release of Ingress2Gateway marks a major leap forward, especially in support for Ingress-NGINX annotations. Prior to this version, only three annotations were supported; now, over 30 common annotations are covered, including CORS, backend TLS, regex matching, and path rewrites. Additionally, the release includes comprehensive integration testing for each annotation and typical combinations, ensuring behavioral equivalence between the original Ingress-NGINX configuration and the generated Gateway API. This testing goes beyond YAML structure—it launches real controllers in live clusters and verifies runtime behavior such as routing, redirects, and rewrites. The result is a robust tool that catches bugs early and minimizes surprises in production.

How Does Ingress2Gateway Handle Annotations?

Annotations are a primary way Ingress-NGINX extends functionality, but they can be cryptic and implementation-specific. Ingress2Gateway 1.0 parses over 30 of the most common Ingress-NGINX annotations and translates them into the appropriate Gateway API equivalents. For example, an annotation enabling CORS is mapped to Gateway's HTTPRoute filters. The tool not only converts these annotations but also provides detailed notifications for each conversion, explaining what was translated and highlighting any configurations that couldn't be mapped. This transparency helps users understand exactly what their new Gateway API setup will do, reducing the risk of misconfiguration. The annotation support is tested with controller-level integration tests to ensure that the translated behavior matches the original exactly.

What Testing Ensures Reliability of the Translation?

Reliability is a cornerstone of Ingress2Gateway 1.0. The development team implemented a comprehensive integration test suite that goes beyond unit tests. Each test spins up a real Ingress-NGINX controller and multiple Gateway API controllers in a live cluster. It then applies Ingress resources with implementation-specific configuration, translates them using Ingress2Gateway, applies the generated Gateway API manifests, and finally verifies that both controllers exhibit equivalent runtime behavior. This approach catches not only bugs but also surprising edge cases and unexpected defaults. By testing in a realistic environment, the tool ensures that your migration won't introduce subtle behavioral differences that could cause issues in production.

How Does Ingress2Gateway Handle Errors and Untranslatable Configuration?

Migration isn't a one-click process; there will always be configurations that don't map cleanly to Gateway API. Ingress2Gateway 1.0 places strong emphasis on notification and error handling. The tool surfaces untranslatable behaviors with clear, formatted messages, detailing what is missing and how you can address it. For example, if an annotation has no direct equivalent, the tool explains the limitation and suggests alternative approaches. This proactive feedback helps you make informed decisions about workarounds or adjustments. The goal is to make the migration transparent and manageable, rather than leaving you to discover issues after deployment.

What Is the Recommended Way to Use Ingress2Gateway?

Ingress2Gateway is designed as a migration assistant, not a one-shot replacement tool. Its recommended usage involves an iterative process: start by running Ingress2Gateway on a subset of your Ingress resources, review the generated Gateway API manifests and the notifications, and then gradually roll out the changes to more workloads. This approach allows you to validate the translation incrementally, catch any issues early, and build confidence in the new configuration. The tool also supports dry-run modes so you can preview the output without applying it. By treating migration as a step-by-step process, Ingress2Gateway helps teams avoid the risks of a big-bang switch and ensures a smooth transition.

How Can Teams Get Started with Ingress2Gateway 1.0?

Getting started is straightforward. The Ingress2Gateway project provides a CLI tool that you can download and run against your existing Ingress manifests. Detailed documentation covers installation, usage examples, and explanations of supported annotations. The community also offers a testing framework to validate your specific configurations. To begin, install the tool, point it at your Ingress resources, and review the generated Gateway API YAML along with any notifications. Start with a low-risk service, verify the behavior, and then expand. The 1.0 release's robust testing means you can trust the translation, but always validate in a staging environment first. For more information, visit the official repository and join the SIG Network discussions.