For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Migrate from Ingress

Introduction

Welcome to the documentation for migrating from Ingress to Gateway API and kgateway. Migration is supported using the kgateway ingress2gateway tool, which is a fork of Kubernetes ingress2gateway with the following additional features:

• Expanded Ingress NGINX Support: Converts a wide range of Ingress NGINX-specific annotations, e.g. session affinity, authentication, rate limiting, CORS, TLS passthrough, service-upstream, and backend protocol hints.
• Kgateway Emitter Support: Generates Gateway API and kgateway-specific resources, e.g. TrafficPolicy, BackendConfigPolicy, etc.

This upstream issue tracks merging these features into the Kubernetes ingress2gateway project.

Prerequisites

Before you start the migration, ensure you have the following:

1. Kgateway Installed: You need kgateway running in the Kubernetes cluster containing the Ingresses to migrate.
2. Kubernetes Cluster Access: Ensure you have access to your Kubernetes cluster and necessary permissions to manage resources.

Installation

The ingress2gateway tool can be installed on a variety of Linux platforms, macOS and Windows. Select your operating system below.

• Install ingress2gateway on macOS
• Install ingress2gateway on Linux
• Install ingress2gateway on Windows

Example Conversions

The following examples demonstrate how to use ingress2gateway to convert various Ingress resources to Gateway API and kgateway resources.

• Basic Ingress
• Session Affinity
• Rate Limiting
• CORS
• SSL Redirect
• External Auth
• Canary Release
• Backend TLS

Optional: Use the Ingress NGINX quickstart guide to test connectivity of the Ingress before converting.

Common workflows

1. Convert Ingresses from the namespace in your current kubeconfig context.

   ingress2gateway print \
     --providers=ingress-nginx \
     --emitter=kgateway

2. Convert one or more manifest files.

   ingress2gateway print \
     --providers=ingress-nginx \
     --emitter=kgateway \
     --input-file ./ingress.yaml \
     --input-file ./more-ingresses.yaml

3. Select a custom Ingress NGINX class.

   ingress2gateway print \
     --providers=ingress-nginx \
     --emitter=kgateway \
     --ingress-nginx-ingress-class=internal-nginx

4. The CLI also exposes --allow-experimental-gw-api for builds and features that use experimental Gateway API fields.

   ingress2gateway print \
     --providers=ingress-nginx \
     --emitter=kgateway \
     --allow-experimental-gw-api \
     --input-file ./ingress.yaml

5. Check the tool version.

   ingress2gateway version

Next steps

• Review the ingress-nginx provider to understand the supported Ingress NGINX annotations.
• Review the kgateway emitter to understand how providers such as ingress-nginx map to kgateway-specific resources.
• Read the emitter design to learn more about emitters and providers.