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 NGINX to Gateway API and agentgateway using the ingress2gateway tool

Introduction

Welcome to the documentation for migrating from Ingress to Gateway API and agentgateway. 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. authentication, rate limiting, CORS, backend TLS, etc.
• Agentgateway Emitter: Generates Gateway API and agentgateway-specific resources, e.g. AgentgatewayPolicy (traffic and backend behavior).

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

This guide uses ingress2gateway v0.5.0. The Ingress NGINX provider selects the nginx Ingress class by default. For a different source class, add --ingress-nginx-ingress-class=<class-name>. Generated Gateways use spec.gatewayClassName: agentgateway regardless of the source Ingress class.

Prerequisites

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

1. Agentgateway installed: You need agentgateway 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 agentgateway resources.

• Basic Ingress
• 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 a file and save the generated manifests.

   ingress2gateway print --providers=ingress-nginx --emitter=agentgateway \
     --input-file ./ingress.yaml > agentgateway.yaml

2. Convert multiple files together by repeating --input-file.

   ingress2gateway print --providers=ingress-nginx --emitter=agentgateway \
     --input-file ./ingress.yaml --input-file ./canary.yaml > agentgateway.yaml

3. Check the tool version.

   ingress2gateway version

Next steps

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