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.4.x
  • 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
  • Prerequisites
    • Install Kong
    • Test connectivity to Kong
  • Create a namespace
  • Adding UDP listens
  • Add a UDP proxy Service
  • Update the Gateway
  • Deploy a UDP test application
  • Route UDP traffic
  • Test the configuration
You are browsing documentation for an outdated version. See the latest documentation here.

Exposing a UDP Service

Overview

This guide walks through deploying a simple Service that listens for UDP datagrams, and exposes this service outside of the cluster using Kong Gateway.

For this example, you will:

  • Deploy a UDP test application.
  • Route UDP traffic to it using UDPIngress or UDPRoute.

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

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:

     export PROXY_IP=$(kubectl get -o jsonpath="{.status.loadBalancer.ingress[0].ip}" service -n kong kong-gateway-proxy)
        
     echo "Proxy IP: $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.

Create a namespace

First, create a namespace:

Command
Response
kubectl create namespace udp-example
namespace/udp-example created

Other examples in this guide will use this namespace. When you’ve completed this guide, kubectl delete namespace udp-example will clean those resources up.

Adding UDP listens

Kong Gateway does not include any UDP listen configuration by default. To expose UDP listens, update the Deployment’s environment variables 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"
              }
            ]
          }
        ]
      }
    }
  }
}'

Response:

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, you’ll need to create a second Service:

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 -

Response:

service/kong-udp-proxy created

Note that this Service is typically added via the Kong Helm chart’s udpProxy configuration. This guide creates it manually to demonstrate the resources the chart normally manages for you 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, 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"
				}
			}
        }
    }
]'

Response:

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

Deploy a UDP test application

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 -

Response:

deployment.apps/tftp created
service/tftp created

echoserver-udp is a simple test server that accepts UDP TFTP requests and returns basic request information. As curl supports TFTP, it is a convenient option for testing 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 -

Response:

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 -

Response:

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

Test the configuration

First, retrieve the external IP address of the UDP proxy Service you created previously:

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

After, use curl to send a TFTP request through the proxy:

Command
Response
curl -s tftp://${KONG_UDP_ENDPOINT}:9999/hello
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