Migrating from Ingress to Gateway API: A Complete Guide to Ingress2Gateway 1.0

Overview

The Kubernetes networking world is approaching a significant milestone: the Ingress-NGINX controller is scheduled for retirement in March 2026. This shift is prompting organizations to consider migrating to the Gateway API, a more modular and extensible approach to managing ingress traffic. However, moving from Ingress to Gateway API is no small task—it involves a fundamental change in API design. The Ingress API is simple but relies heavily on implementation-specific annotations, ConfigMaps, and custom resource definitions (CRDs) to extend functionality. Gateway API, on the other hand, provides built-in support for role-based access control (RBAC) and is designed to be portable across multiple implementations.

Enter Ingress2Gateway, a migration assistant that helps teams transition confidently from Ingress to Gateway API. Today, the SIG Network team is proud to announce the 1.0 release, a stable and thoroughly tested tool. This guide will walk you through everything you need to know: the prerequisites, step-by-step instructions, common pitfalls, and best practices for a smooth migration.

Prerequisites

Before you start, ensure your environment meets the following requirements:

• A Kubernetes cluster (version 1.19 or later) with administrator access.
• kubectl installed and configured to communicate with your cluster.
• An existing Ingress-NGINX controller (for testing equivalence).
• Gateway API CRDs installed (version 0.8.0 or later). You can install them from the official docs.
• The ingress2gateway binary, available from the GitHub releases page.

Optionally, you may want a test namespace dedicated to migration experiments.

Step-by-Step Instructions

1. Download and Install Ingress2Gateway

First, grab the latest ingress2gateway binary for your operating system. For example, on Linux:

curl -Lo ingress2gateway https://github.com/kubernetes-sigs/ingress2gateway/releases/download/v1.0.0/ingress2gateway_linux_amd64
chmod +x ingress2gateway
sudo mv ingress2gateway /usr/local/bin/

Verify the installation:

ingress2gateway version

2. Prepare Your Existing Ingress Resources

Collect all Ingress resources you plan to migrate. You can export them from your cluster:

kubectl get ingress --all-namespaces -o yaml > all-ingresses.yaml

This file will serve as your input.

3. Run the Migration Assistant

Use ingress2gateway to translate the Ingress manifests to Gateway API. The basic command is:

ingress2gateway convert -f all-ingresses.yaml -o gateway-manifests.yaml

This will generate a YAML file containing HTTPRoute and Gateway resources. The tool also outputs warnings and notifications about untranslatable configurations—pay close attention to these.

4. Review Warnings and Notifications

The 1.0 release improves the clarity of warnings. For example, if an annotation like nginx.ingress.kubernetes.io/rewrite-target is mapped, you’ll see a confirmation. If something cannot be translated (e.g., custom snippets), you’ll get a clear message. Review the output carefully, and decide how to handle unsupported features manually.

5. Apply the Gateway API Manifests

Before applying to production, test in a non‑critical namespace:

kubectl create ns migration-test
kubectl apply -f gateway-manifests.yaml -n migration-test

Check that the Gateway API controller creates the expected routes and that traffic flows correctly.

6. Verify Behavioral Equivalence

The best way to ensure correctness is to run the integrated test suite that the Ingress2Gateway 1.0 uses. It spins up an Ingress-NGINX controller and multiple Gateway API controllers, applies the original Ingress resources, translates them, and compares runtime behavior (routing, redirects, rewrites, etc.). You can simulate this manually by setting up a test environment. For a quick check, use curl to hit a few endpoints on both the old and new setups.

Common Mistakes and How to Avoid Them

1. Ignoring Warnings

Many users treat migration as a “one-click” operation and overlook warnings. Do not skip the review step. Some features like custom ConfigMap overrides may not translate. Always address each warning before applying.

2. Using Unsupported Annotations

While the 1.0 release supports over 30 annotations (CORS, backend TLS, regex matching, path rewrite, etc.), some still remain unsupported. The tool will flag them. Either update your Ingress resources to use supported equivalents or plan a manual conversion.

3. Forgetting Gateway API Controller Installation

You must have a Gateway API controller installed before applying the translated manifests. Common choices include traefik, istio, or kong. Without one, your routes will not be reconciled.

4. Overlooking Integration Testing

The comprehensive test suite in Ingress2Gateway 1.0 catches edge cases and unexpected defaults. Running only a dry translation without verifying runtime behavior can lead to production issues. Always test in a staging environment first.

5. Assuming Perfect One-to-One Mapping

Ingress and Gateway API have different paradigms. For example, Ingress-NGINX annotations allow global behavior changes, while Gateway API encourages per-resource configuration. You may need to refactor your deployment to align with Gateway API’s design.

Summary

Migrating from Ingress to Gateway API is a strategic move that modernizes your Kubernetes networking stack. Ingress2Gateway 1.0 provides a stable, tested assistant that handles over 30 Ingress-NGINX annotations, offers clear notifications about untranslatable configuration, and is backed by comprehensive integration tests. By following the steps in this guide—preparing your resources, running the tool, reviewing warnings, and verifying behavior—you can safely transition before the Ingress-NGINX retirement deadline in March 2026. Remember, migration is a process, not a one-shot event; use Ingress2Gateway as your guide, and address issues incrementally.