Migrating from Ingress to Gateway API

Uses: Kong Ingress Controller

Why migrate to Gateway API?

The Gateway API offers several advantages over the legacy Ingress resources:

Standardization: Gateway API is an official Kubernetes networking standard, ensuring better interoperability and community support.
Enhanced expressiveness: Gateway API provides more flexible routing capabilities including advanced matching rules, traffic splitting, and policy attachment.
Protocol support: Native support for HTTP/HTTPS, TCP, UDP, and TLS protocols without requiring custom resources.
Role-based separation: Clear separation of concerns between infrastructure operators and application developers.
Future-proof: Active development and continuous improvement by the Kubernetes community.

Prerequisites

Before you can migrate the TCPIngress and UDPIngress custom resources, you must enable the GatewayAlpha feature gate and

Enable GatewayAlpha feature gate

Required: To use TCPRoute, UDPRoute, and TLSRoute resources in Kong Ingress Controller, you must enable the GatewayAlpha feature gate and install the ingress2gateway tool.

You can enable the GatewayAlpha feature gate in one of the following ways:

helm upgrade --install kong kong/kong \
  --set controller.ingressController.env.feature_gates="GatewayAlpha=true"

apiVersion: apps/v1
kind: Deployment
metadata:
  name: kong-controller
spec:
  template:
    spec:
      containers:
      - name: controller
        env:
        - name: CONTROLLER_FEATURE_GATES
          value: "GatewayAlpha=true"

Install the ingress2gateway tool

Download the kubernetes-sigs/ingress2Gateway CLI tool:

mkdir ingress2gateway && cd ingress2gateway
curl -L https://github.com/kubernetes-sigs/ingress2gateway/releases/download/v0.4.0/ingress2gateway_$(uname)_$(uname -m).tar.gz | tar -xzv
export PATH=$PATH:$(pwd)

To migrate your resources from Ingress API to Gateway API, you need all the Ingress-based yaml manifests. You can use these manifests as the source to migrate to the new API by creating copies that replace the Ingress resources with Gateway API resources. Then, use the ingress2gateway tool to create new manifests containing the Gateway API configurations.

Note: In this guide, the Ingress resources refer to Kubernetes networkingv1 Ingresses, Kong TCPIngresses, and Kong UDPIngresses. This means that all these resources should be included in the files used as a source for the conversion.

Export your source and destination paths:

 export SOURCE_DIR='YOUR SOURCE DIRECTORY'
 export DEST_DIR='YOUR DESTINATION DIRECTORY'

Convert the manifests and create new files in the destination directory:

 for file in $SOURCE_DIR/*.yaml; do ingress2gateway print --input-file ${file} -A --providers=kong > $DEST_DIR/$(basename -- $file); done

Check that the new manifest files are correctly created in the destination directory:
```
 ls $DEST_DIR
```
Copy your annotations from the ingress resources to the Routes. The routes’ names use the ingress name as prefix to help you track the route that the ingress generated. All the konghq.com/ annotations must be copied except for these, that have been natively implemented as Gateway API features:
- konghq.com/methods
- konghq.com/headers
- konghq.com/plugins

Check the new manifests

Check that the new manifests converted correctly. The manifests are converted as follows:

Ingresses are converted to Gateway and HTTPRoutes
TCPIngresses are converted to Gateway and TCPRoutes and TLSRoutes
UDPIngresses are converted to Gateway and UDPRoutes

Migrate from Ingress resources to Gateway resources

Apply the new manifest files into the cluster:
```
 kubectl apply -f $DEST_DIR
```

Wait for all the gateways to be programmed:

 kubectl wait --for=condition=programmed gateway -A --all

Verify the migration

Before deleting the original resources, verify that your Gateway API resources are working correctly:

Check Gateway status

Ensure all Gateways have the Programmed condition set to True:
```
 kubectl get gateway -A -o wide
```

Verify route status

Check that all routes (HTTPRoute, TCPRoute, UDPRoute) are correctly accepted:

Check HTTPRoutes:

kubectl get httproute -A -o custom-columns='NAME:.metadata.name,NAMESPACE:.metadata.namespace,ACCEPTED:.status.parents[0].conditions[0].status'

Check TCPRoutes:

kubectl get tcproute -A -o custom-columns='NAME:.metadata.name,NAMESPACE:.metadata.namespace,ACCEPTED:.status.parents[0].conditions[0].status'

Check UDPRoutes:

kubectl get udproute -A -o custom-columns='NAME:.metadata.name,NAMESPACE:.metadata.namespace,ACCEPTED:.status.parents[0].conditions[0].status'

Test connectivity

Perform connectivity tests to ensure your applications are accessible through the new Gateway API configuration:
1. For HTTP/HTTPS traffic:
```
curl -H "Host: $HOSTNAME" http://$GATEWAY_IP/your-path
```
2. For TCP traffic:
```
telnet $GATEWAY_IP $TCP_PORT
```
3. For UDP traffic
```
nc -u $GATEWAY_IP $UDP_PORT
```

Delete the previous configuration

After all the Gateways are correctly deployed and programmed, you can delete the legacy ingress resources.

Best Practice: Do not delete all the ingress resources at once. Instead, follow an iterative approach:

Delete one ingress resource at a time
Verify that no connectivity is lost
Monitor application logs and metrics
Continue with the next resource only after confirming the previous deletion was successful

Important: The Gateways should have the status condition Programmed set to True before you delete any ingress resources.

Step-by-step deletion process

You can delete resources one at a time. Verify after each deletion that services remain accessible and functional.

List all legacy resources to understand what must be removed.
1. List standard Ingresses:
```
kubectl get ingress -A
```
2. List deprecated TCPIngresses:
```
kubectl get tcpingress -A
```
3. List deprecated UDPIngresses:
```
kubectl get udpingress -A
```

Delete resources one by one, starting with the least critical.

Delete a specific TCPIngress:

kubectl delete tcpingress $TCP_INGRESS_NAME -n $NAMESPACE

Delete a specific UDPIngress:

kubectl delete udpingress $UDP_INGRESS_NAME -n $NAMESPACE

Delete a specific Ingress:

kubectl delete ingress $INGRESS_NAME -n $NAMESPACE