ingress2gateway

Ingress to Gateway

Ingress2gateway helps translate Ingress and provider-specific resources (CRDs) to Gateway API resources. Ingress2gateway is managed by the Gateway API SIG-Network subproject.

Scope

Ingress2gateway is primarily focused on translating Ingress and provider-specific resources(CRDs) to Gateway API resources. Widely used provider-specific annotations and/or CRDs may still not be supported. Please refer to supported providers for the current supported providers and their documentation. Contributions for provider-specific annotations and/or CRDs support are mostly welcomed as long as they can be translated to Gateway API directly.

Note: Ingress2gateway is not intended to copy annotations from Ingress to Gateway API.

Providers vs Emitters

Ingress2gateway has two main components: providers and emitters.

• Providers read Ingress resources and provider-specific CRDs, then convert them into a generic intermediate representation (IR).
• Emitters take that IR and produce the final Gateway API output. The default standard emitter outputs core Gateway API resources (like Gateway and HTTPRoute), while other emitters can additionally output resources tailored to a specific Gateway API project (e.g. EnvoyGateway BackendTrafficPolicy or GKE HealthCheckPolicy).

For a detailed look at the architecture, see docs/emitters.md.

Supported Providers

• apisix
• cilium
• ingress-nginx
• istio
• gce
• kong
• nginx
• openapi
• traefik

If your provider, or a specific feature, is not currently supported, please open an issue and describe your use case.

To contribute a new provider support - please read CONTRIBUTING.md.

Supported Emitters

• standard (default)
• agentgateway
• airlock-microgateway
• envoy-gateway
• gce
• kgateway

Installation

Via go install

If you have a Go development environment locally, you can install ingress2gateway with go install github.com/kubernetes-sigs/[email protected]

This will put ingress2gateway binary in $(go env GOPATH)/bin

Alternatively, you can download the binary at the releases page

On macOS and linux via Homebrew

Make sure Homebrew is installed on your system.

brew install ingress2gateway

Build from Source

1. Ensure that your system meets the following requirements:

   • Install Git: Make sure Git is installed on your system to clone the project repository.
   • Install Go 1.25.5 or later: Make sure the Go language is installed on your system. You can download it from the official website (https://golang.org/dl/) and follow the installation instructions.

2. Clone the project repository

   git clone https://github.com/kubernetes-sigs/ingress2gateway.git && cd ingress2gateway
   

3. Build the project

   make build
   

4. Install the binary to your system

   go install .
   

Usage

Ingress2gateway reads Ingress resources and/or provider-specific CRDs from a Kubernetes cluster or a file. It will output the equivalent Gateway API resources in a YAML, JSON, or KYAML format to stdout. The simplest case is to convert all ingresses from one provider (in this example we use ingress-nginx):

ingress2gateway print --providers=ingress-nginx

The above command will:

1. Read your Kube config file to extract the cluster credentials and the current active namespace.
2. Search for ingress-nginx resources in that namespace.
3. Convert them to Gateway API resources.
4. Warn you of any untranslated fields or unsupported features.

Options

print command

Flag	Short	Default Value	Required	Description
all-namespaces	-A	false	No	If present, list the requested object(s) across all namespaces. Namespace in the current context is ignored even if specified with --namespace.
allow-experimental-gw-api		false	No	If present, include Experimental Gateway API fields (e.g. URLRewrite) in the output.
emitter		standard	No	The emitter to use for generating Gateway API resources.
input-file			No	Path to the manifest file(s). When set, the tool will read ingresses from the file(s) instead of reading from the cluster. Supports yaml and json. Can be specified multiple times.
kubeconfig			No	The kubeconfig file to use when talking to the cluster. If the flag is not set, a set of standard locations can be searched for an existing kubeconfig file.
namespace	-n		No	If present, the namespace scope for the invocation.
no-color		false	No	Disable ANSI color codes in the output.
output	-o	yaml	No	The output format. One of: yaml, json, kyaml.
providers			Yes	Comma-separated list of providers.

Provider-specific flags

Flag	Default Value	Required	Description
gce-gateway-class-name		No	Provider-specific: gce. The name of the GatewayClass to use for the Gateway.
ingress-nginx-ingress-class	nginx	No	Provider-specific: ingress-nginx. The name of the ingress class to select.
openapi3-backend		No	Provider-specific: openapi3. The name of the backend service to use in the HTTPRoutes.
openapi3-gateway-class-name		No	Provider-specific: openapi3. The name of the gateway class to use in the Gateways.
openapi3-tls-secret		No	Provider-specific: openapi3. The name of the secret for the TLS certificate references in the Gateways.

Gateway API version support

Ingress2gateway will support the latest stable version of the Gateway API at the time of release.

Ingress2gateway version	Supported Gateway API version
v1.0	v1.5.0 [^1]

[^1]: The output of Ingress2Gateway v1.0 is generally forward-compatible with Gateway API v1.4.

Conversion of Ingress resources to Gateway API

Processing Order and Conflicts

Ingress resources will be processed with a defined order to ensure deterministic generated Gateway API configuration. This should also determine precedence order of Ingress resources and routes in case of conflicts.

Ingress resources with the oldest creation timestamp will be sorted first and therefore given precedence. If creation timestamps are equal, then sorting will be done based on the namespace/name of the resources. If an Ingress rule conflicts with another (e.g. same path match but different backends) an error will be reported for the one that sorted later.

Since the Ingress v1 spec does not itself have a conflict resolution guide, we have adopted this one. These rules are similar to the Gateway API conflict resolution guidelines.

Ingress resource fields to Gateway API fields

Given a set of Ingress resources, ingress2gateway will generate a Gateway with various HTTP and HTTPS Listeners as well as HTTPRoutes that should represent equivalent routing rules.

Ingress Field	Gateway API configuration
ingressClassName	If configured on an Ingress resource, this value will be used as the gatewayClassName set on the corresponding generated Gateway. kubernetes.io/ingress.class annotation has the same behavior.
defaultBackend	If present, this configuration will generate a Gateway Listener with no hostname specified as well as a catchall HTTPRoute that references this listener. The backend specified here will be translated to a HTTPRoute rules[].backendRefs[] element.
tls[].hosts	Each host in an IngressTLS will result in a HTTPS Listener on the generated Gateway with the following: listeners[].hostname = host as described, listeners[].port = 443, listeners[].protocol = HTTPS, listeners[].tls.mode = Terminate
tls[].secretName	The secret specified here will be referenced in the Gateway HTTPS Listeners mentioned above w