Migrating from Ingress to Gateway API with Ingress2Gateway 1.0

Moving Beyond Ingress-NGINX

The Kubernetes networking landscape is changing. With Ingress-NGINX approaching retirement in March 2026, organizations face a migration decision: how to modernize their networking stack without breaking existing workloads. For teams that have relied on Ingress-NGINX for years, this transition represents more than a simple API change—it is a fundamental shift in how Kubernetes handles external traffic.

SIG Network answer is Gateway API—a more flexible, role-oriented networking standard that separates infrastructure concerns from application configuration. Unlike the original Ingress API, which was deliberately minimal and required implementation-specific annotations for any sophisticated routing, Gateway API provides explicit, typed resources that express intent clearly. Today, the Ingress2Gateway project reached 1.0, providing a stable, battle-tested migration assistant that can translate complex Ingress configurations into their Gateway API equivalents.

This guide walks through migrating a real-world Ingress configuration to Gateway API. We will cover installation, translation strategies, common pitfalls, and the verification steps you need before cutting over production traffic. By the end, you will understand not just how to run the tool, but how to plan a safe migration that minimizes risk.

What Changed and Why It Matters

Gateway API replaces the annotation-heavy approach of Ingress with explicit, typed resources. Instead of cramming logic into metadata annotations—practically a DSL of its own—you declare:

Gateway: The entry point (replaces IngressClass)
HTTPRoute: Traffic rules for HTTP/HTTPS (replaces Ingress rules)
ReferenceGrant: Cross-namespace access controls

The shift matters because Gateway API supports advanced patterns that Ingress simply cannot express: header-based routing, traffic splitting for canary deployments, built-in retry policies, and cross-namespace references. For platform teams managing shared clusters, Gateway API also introduces role-based separation—platform administrators define Gateways while application teams specify HTTPRoutes. This separation of concerns reduces the coordination overhead that often slowed Ingress-based workflows.

Another significant improvement is the consistency across implementations. While Ingress implementations varied wildly—NGINX, HAProxy, Traefik, and others each had their own annotation dialect—Gateway API defines a standard that implementations must follow. This means skills learned on one Gateway controller transfer to others, and portable configurations become realistic.

Installing Ingress2Gateway

The Ingress2Gateway project provides a CLI tool that translates existing Ingress resources to Gateway API. Install using your preferred method:

# Homebrew

brew install ingress2gateway

# Go install

go install github.com/kubernetes-sigs/ingress2gateway@v1.0.0

# Download from GitHub releases

curl -L -o ingress2gateway https://github.com/kubernetes-sigs/ingress2gateway/releases/download/v1.0.0/ingress2gateway_linux_amd64

chmod +x ingress2gateway

Verify the installation by running ingress2gateway version. You should see v1.0.0 or later.

Running the Migration

Ingress2Gateway can read from files or directly from your cluster, making it flexible for different migration workflows. You might start with a file-based approach in a development environment before moving to cluster-level translation in staging.

# From files

ingress2gateway print –input-file my-ingress.yaml –providers=ingress-nginx > gateway-resources.yaml

# From namespace

ingress2gateway print –namespace production –providers=ingress-nginx > gateway-resources.yaml

# Entire cluster

ingress2gateway print –providers=ingress-nginx –all-namespaces > gateway-resources.yaml

The –providers flag is crucial— it tells Ingress2Gateway which Ingress implementation annotation dialect to parse. Version 1.0 supports over 30 Ingress-NGINX annotations including CORS configuration, regex matching, path rewriting, backend TLS, and timeout settings. This is a significant expansion from the three annotations supported in earlier versions.

Understanding the Output

For a typical Ingress with CORS, regex matching, and timeout annotations, Ingress2Gateway produces several resources:

A Gateway resource with HTTPS listeners on port 443 and HTTP listeners on port 80
An HTTPRoute with filters for CORS headers, regex path matching, and request timeouts
A separate HTTPRoute for HTTP-to-HTTPS redirects with a 308 status code
Warning logs for unsupported annotations that require manual attention

The generated Gateway includes listeners for both HTTP and HTTPS. The HTTP listener typically serves only redirect routes—matching traffic that should be moved to TLS. This matches the default behavior of Ingress-NGINX while making the security policy explicit in the configuration.

Required Manual Steps

Not everything translates automatically. Review these common gaps and plan your response:

configuration-snippet annotations: Gateway API has no equivalent for raw Nginx configuration. You must implement these behaviors through your Gateway controller’s extension mechanisms or policy resources.
URL normalization: Gateway API does not configure URL path normalization. Verify your Gateway controller’s defaults match your application’s expectations for encoded characters and trailing slashes.
Cookie/session affinity: Only some Gateway implementations support sticky sessions. Check before migrating stateful workloads that depend on session affinity.
Body size limits: These are implementation-specific settings. The standard Gateway API has no equivalent field for maximum request body size.
Custom error pages: Ingress-NGINX allows custom error pages through ConfigMaps. Gateway API implementations handle this differently.

Verification Strategy

Before switching production traffic, run through this checklist:

Deploy Gateway resources alongside existing Ingress in your cluster
Test with a canary DNS entry pointing to the new Gateway IP or hostname
Run integration tests that exercise path matching, redirects, CORS, and file uploads
Monitor for HTTP 404s, latency spikes, or certificate errors in your observability platform
Update DNS or modify IngressClass references to complete the migration once validated
Keep the old Ingress resources as rollbacks until you are confident

When to Skip the Tool

Ingress2Gateway excels at capturing existing configuration, but it is not the right tool in every situation:

If you are redesigning routing rules entirely, write new Gateway resources from scratch
If you rely heavily on custom Nginx Lua snippets, you will need architectural changes regardless
If you need advanced rate limiting or WAF rules, check what your Gateway implementation supports

Key Takeaways

Ingress2Gateway 1.0 is production-ready with comprehensive integration testing across multiple Gateway implementations
Over 30 Ingress-NGINX annotations now translate to Gateway API equivalents, up from three in earlier versions
Always review generated manifests—some features will always require manual intervention
The tool enables a safe, gradual migration path without requiring big-bang cutovers that risk production stability
Gateway API represents the future of Kubernetes networking—migrating now prepares your platform for continued evolution