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, etc..
Kgateway Emitter Support: Generates Gateway API and kgateway-specific resources, e.g. TrafficPolicy, BackendConfigPolicy, etc..

We plan to merge these features upstream to the Kubernetes ingress2gateway project.

Prerequisites

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

Kgateway Installed: You need kgateway running in the Kubernetes cluster containing the Ingresses to migrate.
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.

Example Conversions

The following sections provide a few examples of using ingress2gateway to convert an Ingress resource to Gateway API and kgateway resources.

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

Example 1: Basic Conversion

This example performs a conversion of an Ingress that does not contain any Ingress NGINX annotations. The ingress2gateway tool will generate Gateway API (Gateway and HTTPRoute) resources.

Create the Ingress that will be converted:

cat <<'EOF' > basic-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo-localhost
spec:
  ingressClassName: nginx
  rules:
  - host: demo.localdev.me
    http:
      paths:
      - backend:
          service:
            name: echo-backend
            port:
              number: 8080
        path: /
        pathType: Prefix
EOF

Convert the Ingress manifest:

ingress2gateway print --providers=ingress-nginx --emitter=kgateway --input-file basic-ingress.yaml > basic-kgateway.yaml

Verify the contents of the basic-kgateway.yaml manifest generated by ingress2gateway:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  annotations:
    gateway.networking.k8s.io/generator: ingress2gateway-v0.3.0
  name: nginx
spec:
  gatewayClassName: kgateway
  listeners:
  - hostname: demo.localdev.me
    name: demo-localdev-me-http
    port: 80
    protocol: HTTP
status: {}
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  annotations:
    gateway.networking.k8s.io/generator: ingress2gateway-v0.3.0
  name: demo-localhost-demo-localdev-me
spec:
  hostnames:
  - demo.localdev.me
  parentRefs:
  - name: nginx
  rules:
  - backendRefs:
    - name: echo-backend
      port: 8080
    matches:
    - path:
        type: PathPrefix
        value: /
status:
  parents: []

Apply the manifest to your cluster:
```
kubectl apply -f basic-kgateway.yaml
```

Check the status of the resources:

kubectl get gateways
kubectl get httproutes

Example 2: Advanced Conversion

This example performs a conversion of an Ingress that contains Ingress NGINX session affinity annotations. The ingress2gateway tool will generate Gateway API (Gateway and HTTPRoute) and kgateway (BackendConfigPolicy) resources.

Create the Ingress that will be converted:

cat <<'EOF' > session-affinity-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/affinity: "cookie"
    nginx.ingress.kubernetes.io/session-cookie-name: "session-id"
    nginx.ingress.kubernetes.io/session-cookie-path: "/api"
    nginx.ingress.kubernetes.io/session-cookie-domain: "example.com"
    nginx.ingress.kubernetes.io/session-cookie-samesite: "Strict"
    nginx.ingress.kubernetes.io/session-cookie-expires: "3600"
    nginx.ingress.kubernetes.io/session-cookie-max-age: "604800"
    nginx.ingress.kubernetes.io/session-cookie-secure: "true"
  name: session-affinity-localhost
spec:
  ingressClassName: nginx
  rules:
  - host: session.affinity.localdev.me
    http:
      paths:
      - backend:
          service:
            name: echo-backend
            port:
              number: 8080
        path: /session/affinity
        pathType: Prefix
EOF

Convert the Ingress manifest:

ingress2gateway print --providers=ingress-nginx --emitter=kgateway --input-file session-affinity-ingress.yaml > session-affinity-kgateway.yaml

Verify the contents of the session-affinity-kgateway.yaml manifest generated by ingress2gateway:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  annotations:
    gateway.networking.k8s.io/generator: ingress2gateway-v0.3.0
  name: nginx
spec:
  gatewayClassName: kgateway
  listeners:
  - hostname: session.affinity.localdev.me
    name: session-affinity-localdev-me-http
    port: 80
    protocol: HTTP
status: {}
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  annotations:
    gateway.networking.k8s.io/generator: ingress2gateway-v0.3.0
  name: session-affinity-localhost-session-affinity-localdev-me
spec:
  hostnames:
  - session.affinity.localdev.me
  parentRefs:
  - name: nginx
  rules:
  - backendRefs:
    - name: echo-backend
      port: 8080
    matches:
    - path:
        type: PathPrefix
        value: /session/affinity
status:
  parents: []
---
apiVersion: gateway.kgateway.dev/v1alpha1
kind: BackendConfigPolicy
metadata:
  name: echo-backend-backend-config
spec:
  loadBalancer:
    ringHash:
      hashPolicies:
      - cookie:
          name: session-id
          path: /api
          sameSite: Strict
          secure: true
          ttl: 168h0m0s
  targetRefs:
  - group: ""
    kind: Service
    name: echo-backend
status:
  ancestors: null

Apply the manifest to your cluster:

kubectl apply -f session-affinity-kgateway.yaml

Check the status of the resources:

kubectl get gateways
kubectl get httproutes
kubectl get backendconfigpolicies

Troubleshoot any issues by reviewing the status of the resources and kgateway controller logs.

Common workflows

Convert a file and write output to a directory

ingress2gateway print   --providers=ingress-nginx   --emitter=kgateway   --input-file ./ingress.yaml   --output-dir ./out

Convert a folder of YAMLs

ingress2gateway print   --providers=ingress-nginx   --emitter=kgateway   --input-dir ./manifests   --output-dir ./out

Check 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 are mapped to kgateway-specific resources.
Read the emitter design to understand more about emitters and providers.