You are browsing unreleased documentation. See the latest documentation here.

Proxy UDP requests

Deploy a Service that listens for UDP datagrams, and exposes this service outside of the cluster using Kong Gateway.

Configure Kong Gateway

Kong Gateway does not include any UDP listen configuration by default

Add UDP listens

To expose UDP listens, set the KONG_STREAM_LISTEN environment variable and expose port 9999 in the Deployment:

kubectl patch deploy -n kong kong-gateway --patch '{
  "spec": {
    "template": {
      "spec": {
        "containers": [
          {
            "name": "proxy",
            "env": [
              {
                "name": "KONG_STREAM_LISTEN",
                "value": "0.0.0.0:9999 udp"
              }
            ],
            "ports": [
              {
                "containerPort": 9999,
                "name": "stream9999",
                "protocol": "UDP"
              }
            ]
          }
        ]
      }
    }
  }
}'

The results should look like this:

deployment.apps/kong-gateway patched

Add a UDP proxy Service

LoadBalancer Services only support a single transport protocol in Kubernetes versions prior to 1.26. To direct UDP traffic to the proxy Service, create a second Service named kong-udp-proxy.

This Service can be managed using the udpProxy configuration of the Kong Helm chart.

echo "apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/aws-load-balancer-backend-protocol: udp
    service.beta.kubernetes.io/aws-load-balancer-type: nlb
  name: kong-udp-proxy
  namespace: kong
spec:
  ports:
  - name: stream9999
    port: 9999
    protocol: UDP
    targetPort: 9999
  selector:
    app: kong-gateway
  type: LoadBalancer
" | kubectl apply -f -

The results should look like this:

service/kong-udp-proxy created

Update Gateway API Listeners

If you are using Gateway API (UDPRoute), your Gateway needs additional configuration under listeners. If you are using UDPIngress, you can skip this step.

kubectl patch --type=json gateway kong -p='[
    {
        "op":"add",
        "path":"/spec/listeners/-",
        "value":{
            "name":"stream9999",
            "port":9999,
            "protocol":"UDP",
            "allowedRoutes": {
                "namespaces": {
                  "from": "All"
                }
            }
        }
    }
]'

The results should look like this:

gateway.gateway.networking.k8s.io/kong patched

Deploy a UDP test application

echoserver-udp is a simple test server that accepts UDP TFTP requests and returns basic request information. Because curl supports TFTP you can use it to test UDP routing.

1. Create a namespace for deploying the UDP application.

    kubectl create namespace udp-example
   

   The results should look like this:

    namespace/udp-example created
   

   When you’ve completed this guide, use the kubectl delete namespace udp-example command to clean those resources.

2. Create a test application Deployment and an associated Service.

   echo "---
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: tftp
     namespace: udp-example
     labels:
       app: tftp
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: tftp
     template:
       metadata:
         labels:
           app: tftp
       spec:
         containers:
         - name: tftp
           image: cilium/echoserver-udp:latest
           args:
           - --listen
           - :9999
           ports:
           - containerPort: 9999
   ---
   apiVersion: v1
   kind: Service
   metadata:
     name: tftp
     namespace: udp-example
   spec:
     ports:
     - port: 9999
       name: tftp
       protocol: UDP
       targetPort: 9999
     selector:
       app: tftp
     type: ClusterIP
   " | kubectl apply -f -
   

   The results should look like this:

   deployment.apps/tftp created
   service/tftp created
   

Route UDP traffic

Now that Kong Gateway is listening on port 9999 and the test application is running, you can create UDP routing configuration that proxies traffic to the application:

echo "apiVersion: gateway.networking.k8s.io/v1alpha2
kind: UDPRoute
metadata:
  name: tftp
  namespace: udp-example
spec:
  parentRefs:
  - name: kong
    namespace: default
  rules:
  - backendRefs:
    - name: tftp
      port: 9999
" | kubectl apply -f -

udproute.gateway.networking.k8s.io/tftp created

echo "apiVersion: configuration.konghq.com/v1beta1
kind: UDPIngress
metadata:
  name: tftp
  namespace: udp-example
  annotations:
    kubernetes.io/ingress.class: kong
spec:
  rules:
  - backend:
      serviceName: tftp
      servicePort: 9999
    port: 9999
" | kubectl apply -f -

udpingress.configuration.konghq.com/tftp created

This configuration routes traffic to UDP port 9999 on the Kong Gateway proxy to port 9999 on the TFTP test server.

Test the UDP routing configuration

1. Retrieve the external IP address of the UDP proxy Service you created and set the KONG_UDP_ENDPOINT variable.

    export KONG_UDP_ENDPOINT="$(kubectl -n kong get service kong-udp-proxy \
    -o=go-template='{{range .status.loadBalancer.ingress}}{{.ip}}{{end}}')"
   

2. Send a TFTP request through the proxy.

    curl -s tftp://${KONG_UDP_ENDPOINT}:9999/hello
   

   The results should look like this:

    Hostname: tftp-5849bfd46f-nqk9x
       
    Request Information:
    	client_address=10.244.0.1
    	client_port=39364
    	real path=/hello
    	request_scheme=tftp