Skip to content
2023 API Summit Hackathon: Experiment with AI for APIs (August 28 - September 27) Learn More →
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
      Lightweight, fast, and flexible cloud-native API gateway
      Kong Konnect
      Single platform for SaaS end-to-end connectivity
      Kong Mesh
      Enterprise service mesh based on Kuma and Envoy
      decK
      Helps manage Kong’s configuration in a declarative fashion
      Kong Ingress Controller
      Works inside a Kubernetes cluster and configures Kong to proxy traffic
      Insomnia
      Collaborative API development platform
      Kuma
      Open-source distributed control plane with a bundled Envoy Proxy integration
      Docs Contribution Guidelines
      Want to help out, or found an issue in the docs and want to let us know?
  • API Specs
  • Plugin Hub
    • Explore the Plugin Hub
      View all plugins View all plugins View all plugins arrow image
    • Functionality View all View all arrow image
      View all plugins
      Authentication's icon
      Authentication
      Protect your services with an authentication layer
      Security's icon
      Security
      Protect your services with additional security layer
      Traffic Control's icon
      Traffic Control
      Manage, throttle and restrict inbound and outbound API traffic
      Serverless's icon
      Serverless
      Invoke serverless functions in combination with other plugins
      Analytics & Monitoring's icon
      Analytics & Monitoring
      Visualize, inspect and monitor APIs and microservices traffic
      Transformations's icon
      Transformations
      Transform request and responses on the fly on Kong
      Logging's icon
      Logging
      Log request and response data using the best transport for your infrastructure
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
Kong Ingress Controller
2.11.x (latest)
  • Home icon
  • Kong Ingress Controller
  • Guides
  • Exposing a UDP Service
github-edit-pageEdit this page
report-issueReport an issue
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 2.11.x (latest)
  • 2.10.x
  • 2.9.x
  • 2.8.x
  • 2.7.x
  • 2.6.x
  • 2.5.x
  • 2.4.x
  • 2.3.x
  • 2.2.x
  • 2.1.x
  • 2.0.x
  • 1.3.x
  • 1.2.x
  • 1.1.x
  • 1.0.x
enterprise-switcher-icon Switch to OSS
On this pageOn this page
  • Overview
  • Install the Gateway APIs
  • Prerequisites
    • Install Kong
    • Test connectivity to Kong
  • Add UDP listens
  • Add a UDP proxy Service
  • Update the Gateway
  • Deploy a UDP test application
  • Route UDP traffic
  • Test the UDP routing configuration

Exposing a UDP Service

Overview

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

Before you begin ensure that you have Installed Kong Ingress Controller in your Kubernetes cluster and are able to connect to Kong.

Install the Gateway APIs

If you wish to use the Gateway APIs examples, ensure that you enable support for Gateway APIs in KIC.

Prerequisites

Install Kong

You can install Kong in your Kubernetes cluster using Helm.

  1. Add the Kong Helm charts:

     helm repo add kong https://charts.konghq.com
     helm repo update
    
  2. Install Kong Ingress Controller and Kong Gateway with Helm:

     helm install kong kong/ingress -n kong --create-namespace
    

Test connectivity to Kong

Kubernetes exposes the proxy through a Kubernetes service. Run the following commands to store the load balancer IP address in a variable named PROXY_IP:

  1. Populate $PROXY_IP for future commands:

     HOST=$(kubectl get svc --namespace kong kong-gateway-proxy -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
     PORT=$(kubectl get svc --namespace kong kong-gateway-proxy -o jsonpath='{.spec.ports[0].port}')
     export PROXY_IP=${HOST}:${PORT}
     echo $PROXY_IP   
    
  2. Ensure that you can call the proxy IP:

     curl -i $PROXY_IP
    

    The results should look like this:

     HTTP/1.1 404 Not Found
     Content-Type: application/json; charset=utf-8
     Connection: keep-alive
     Content-Length: 48
     X-Kong-Response-Latency: 0
     Server: kong/3.0.0
      
     {"message":"no Route matched with those values"}
    

    If you are not able to connect to Kong, read the deployment guide.

Add UDP listens

Kong Gateway does not include any UDP listen configuration by default. To expose UDP listens, update the environment variables of the Deployment and port configuration.

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.

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

This Service is typically added through the udpProxyconfiguration of the Kong Helm chart. Configure this manually to check the resources the chart manages and for compatibility with non-Helm installs.

Update the Gateway

If you are using Gateway APIs (UDPRoute) option, 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

  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
    

    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.

Route UDP traffic

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

Ingress
Gateway APIs
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 -

The results should look like this:

udpingress.configuration.konghq.com/tftp created
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 -

The results should look like this:

udproute.gateway.networking.k8s.io/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
    
Thank you for your feedback.
Was this page useful?
Too much on your plate? close cta icon
More features, less infrastructure with Kong Konnect. 1M requests per month for free.
Try it for Free
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023