Introducing Ingress2Gateway 1.0: Your Gateway API Transition Tool

As the Ingress-NGINX controller prepares for its retirement in March 2026, organizations face a pivotal decision. The challenge isn’t just whether to transition to the Gateway API; it’s how to execute that migration thoughtfully and effectively. The shift from the familiar but simplistic Ingress API to the more sophisticated Gateway API requires a significant redesign of API frameworks. ### The Methodology Behind Migration Moving from Ingress to Gateway API is more than just changing endpoints—it's a fundamental rethinking of how APIs are structured. Gateway API introduces a modular and extensible approach, complete with enhanced support for Kubernetes-native Role-Based Access Control (RBAC). In contrast, the Ingress API, while user-friendly, often relies on complicated annotations and custom resources that can add complexity during migration. The task ahead involves not just migrating configurations but also capturing the intricate behaviors of the current Ingress controllers and translating those into the new API format. To aid in this transition, teams can turn to Ingress2Gateway, a tool designed to facilitate the migration from Ingress to Gateway API. This assistant translates existing Ingress resources into their Gateway API counterparts and alerts users about any configurations that can't be directly translated, while providing alternatives where possible. ### Announcing Ingress2Gateway 1.0 In an important announcement, SIG Network has launched the **1.0 version of Ingress2Gateway**. This release marks a significant step forward, offering a tested and stable solution for teams eager to update their networking practices. One standout feature of the new release is the enhanced support for Ingress-NGINX annotations. Prior to version 1.0, Ingress2Gateway only recognized a handful of these annotations—just three, to be precise. In this new release, the tool now encompasses support for over 30 frequently used annotations, such as those for Cross-Origin Resource Sharing (CORS), backend TLS configurations, regex matching, and path rewriting. ### Rigorous Testing for Reliable Performance But robust functionality isn't the only enhancement. This 1.0 launch emphasizes thorough integration testing. Each supported Ingress-NGINX annotation is subjected to controls that verify whether the behavior of the Gateway API configurations aligns with that of the Ingress-NGINX setup. These tests simulate real-time environments, ensuring not just the translation of configuration files but also the preservation of runtime behavior like routing and redirect processes. The testing protocol consists of several steps: initializing both an Ingress-NGINX controller and multiple Gateway API controllers, applying Ingress resources, translating them with Ingress2Gateway, and meticulously comparing the outcomes. This methodical approach provides critical assurances to teams migrating their configurations, especially when considering edge cases and unexpected defaults that may trip them up in production settings. ### Clarity in Migration Notifications Migration is rarely a straightforward process, and the 1.0 release addresses this by improving how it communicates issues during the transition. It's essential that teams identify subtleties within their configurations, particularly those that can't be translated directly. The enhancements in notification clarity mean teams will know precisely what's missing and how to resolve those gaps. ### The Approach to Using Ingress2Gateway It's essential to clarify that Ingress2Gateway is not merely a one-time solution but a comprehensive migration assistant. Its objectives include: - Translating supported Ingress configurations and behaviors into the Gateway API framework. - Highlighting unsupported configurations while offering alternative recommendations. - Prompting teams to reassess and potentially discard any undesirable configurations. As organizations navigate this migration, Ingress2Gateway provides clear instructions and examples to streamline the process, ensuring that teams can transition smoothly and effectively.

Translation Challenges in Annotations

The recent shift from Ingress to Gateway API has revealed some intriguing successes and notable gaps in how annotations are handled. For instance, the transition process has effectively reconceptualized the annotation `nginx.ingress.kubernetes.io/enable-cors`, translating it into a corresponding CORS filter within the Gateway API framework. This shows a direct pathway from traditional configurations to modern implementations that align with new standards. However, not everything has gone smoothly. The attempted conversions for `nginx.ingress.kubernetes.io/proxy-{read,send}-timeout` and `nginx.ingress.kubernetes.io/proxy-body-size` uncover some discrepancies. The lack of a perfect mapping here suggests that the existing logic behind these annotations may not fully align with Gateway API specifications. Such oversights can hinder the transition for existing application architectures, bringing questions to the forefront about the robustness of the translation mechanism. The logs produced during translation attempts hint at possible reasons for these shortcomings. They serve not only as documentation of what has been successfully mapped but also articulate the logic that guided the translation process. If you're developing or managing Kubernetes applications, understanding these nuances is essential. You risk potential misconfigurations if you blindly trust the translation without a thorough examination of the logs and omitted annotations. This careful scrutiny could save you from deploying solutions that don't function as intended given the specific requirements of your environment.

Final Thoughts on Transitioning to Gateway API

As the dust settles on the Ingress2Gateway 1.0 release, it's clear that this is more than just a simple transition; it's a pivotal moment for organizations relying on Ingress-NGINX. With the looming retirement of Ingress-NGINX in March 2026, teams must proactively navigate this migration to the Gateway API, which offers a more comprehensive framework for traffic management in Kubernetes. However, be prepared for the bumps along the road. The warnings identified throughout the migration process—whether it's the unsupported annotations or the need to modify regex patterns—highlight the careful calibration required to ensure a smooth transition. The fact that Ingress2Gateway doesn't translate certain configuration parameters, like proxy body size, means you’ll need to validate defaults in your Gateway API implementation. It’s crucial to ask: are these defaults suitable for your application? Testing in a development environment can't be an afterthought. You’ll want to confirm everything from timeout settings to URL normalization behavior well before hitting production. It's a delicate dance—one that requires not just technical adjustments, but also an understanding of your service's unique requirements. Moving beyond the mechanics, the community's role in this project cannot be overstated. The call for collaboration invites developers to contribute to enhancing configuration coverage, testing, and user experience. This is a shared journey, and a rich, engaged community can play a significant role in smoother migrations across the board. As we look to the future, the Gateway API presents an exciting framework that aligns with the evolving needs of cloud-native applications. If you’re in this space, don’t wait until the last minute. Start exploring these resources and engaging with the community now. The time to prepare for this transition is now, not later. With the right approach, you'll find not only safety in migration but also opportunity in the new capabilities the Gateway API unlocks.