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
      Kong Gateway Operator
      Manage your Kong deployments on Kubernetes using YAML Manifests
      Insomnia
      Collaborative API development platform
      Kuma
      Open-source distributed control plane with a bundled Envoy Proxy integration
  • 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.1.x
  • Home icon
  • Kong Ingress Controller
  • Guides
  • UDPIngress with {{site.base_gateway}}
github-edit-pageEdit this page
report-issueReport an issue
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • Kong Gateway Operator
  • 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
  • Installation
  • Create a namespace
  • Deploy CoreDNS
  • Expose CoreDNS through a Service
  • Exposing UDP Ports on Kong
  • Deploying UDPIngress
  • Verification
You are browsing documentation for an outdated version. See the latest documentation here.

UDPIngress with Kong Gateway

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

Overview

Some of the most common UDP-based services available on the internet are DNS servers. These servers are an important part of the infrastructure of the internet, and are also present by default in Kubernetes clusters to allow Pods within the cluster to look up other pods’ IP addresses by name.

For this example, you will:

  • Deploy your own CoreDNS server, which is the default DNS server Kubernetes uses for internal DNS
  • Deploy a CoreDNS Pod and Service
  • Route UDP traffic to it using UDPIngress

This guide assumes that you’ve deployed the Kong Ingress Controller (KIC) using the Helm Chart. If you have deployed the KIC in a different way, you may need to make some manual adjustments to some of the provided instructions.

Installation

Follow the deployment documentation to install the Kong Ingress Controller on your Kubernetes cluster.

Note: This feature is compatible with:

  • Kong Gateway versions 2.0.0 and above.
  • Kong Ingress Controller versions 2.0.0 and above.

Create a namespace

First, create a namespace for testing DNS services and UDPIngress.

Manifest
kubectl

Apply the following manifest to the cluster to create the namespace:

apiVersion: v1
kind: Namespace
metadata:
  name: udpingress-example

Use the shorthand version with kubectl to deploy the namespace:

$ kubectl create namespace udpingress-example

You’ll be using this namespace in the upcoming sections, and when you’re done testing you can delete it.

Deploy CoreDNS

For this example, deploy a default CoreDNS server that only serves up DNS requests.

First, you need to configure CoreDNS with a Core File.

Save the following ConfigMap as corefile.yaml:

apiVersion: v1
kind: ConfigMap
metadata:
  name: coredns
  namespace: udpingress-example
data:
  Corefile: |-
    .:53 {
        errors
        health {
           lameduck 5s
        }
        ready
        kubernetes cluster.local in-addr.arpa ip6.arpa {
           pods insecure
           fallthrough in-addr.arpa ip6.arpa
           ttl 30
        }
        forward . /etc/resolv.conf {
           max_concurrent 1000
        }
        cache 30
        loop
        reload
        loadbalance
    }

This simple configuration tells our CoreDNS pods to forward all DNS requests to nameservers present in /etc/resolv.conf.

By default, /etc/resolve.conf points to the standard kube-dns service provided by the cluster.

Next, apply the corefile.yaml:

$ kubectl apply -f corefile.yaml

Now the cluster is ready for the Deployment manifest.

Save the following file as coredns-deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: coredns
  namespace: udpingress-example
  labels:
    app: coredns
spec:
  replicas: 1
  selector:
    matchLabels:
      app: coredns
  template:
    metadata:
      labels:
        app: coredns
    spec:
      containers:
      - args:
        - -conf
        - /etc/coredns/Corefile
        image: coredns/coredns
        imagePullPolicy: IfNotPresent
        name: coredns
        ports:
        - containerPort: 53
          protocol: UDP
        volumeMounts:
        - mountPath: /etc/coredns
          name: config-volume
      volumes:
      - configMap:
          defaultMode: 420
          items:
          - key: Corefile
            path: Corefile
          name: coredns
        name: config-volume

Note that this Deployment mounts the corefile configuration data we created above into the pods so that CoreDNS can load them.

Apply the Deployment configuration file:

$ kubectl apply -f coredns-deployment.yaml

Watch the pods with kubectl -n udpingress-example get pods. Once they are running, you can move on to the next sections: exposing the pods through Service and UDPIngress.

Expose CoreDNS through a Service

A Kubernetes Service is a fundamental network abstraction layer that allows you to load-balance traffic to pods in the cluster. Services are ultimately the DNS names that the Kong Gateway will be routing our UDP traffic to.

The following manifest exposes the CoreDNS Deployment from the previous section via a service.

Save this manifest as coredns-service.yaml:

apiVersion: v1
kind: Service
metadata:
  name: coredns
  namespace: udpingress-example
spec:
  ports:
  - port: 53
    protocol: UDP
    targetPort: 53
  selector:
    app: coredns
  type: ClusterIP

This configuration uses UDP port 53, which is the default port for DNS.

Apply the manifest:

$ kubectl apply -f coredns-service.yaml

Now that you have a Service to expose the pods, you can expose this DNS server outside of the cluster using Kong’s UDPIngress resource.

Exposing UDP Ports on Kong

The Kong Ingress Controller (KIC) doesn’t have a mechanism to automatically enable new UDP ports for exposing your Kubernetes UDP Services, so you need to explicitly configure Kong Gateway to expose these ports prior to deploying any UDPIngress resources.

If you’re maintaining a values.yaml configuration for your Helm deployment of Kong Gateway, add a section under udpProxy to enable the new UDP listener:

udpProxy:
  enabled: true
  type: LoadBalancer
  stream:
  - containerPort: 9999
    servicePort: 9999
    protocol: UDP

Once you’ve made the necessary configurations you can apply your changes:

$ helm upgrade --namespace {NAMESPACE} --version {CHART_VERSION} -f values.yaml {RELEASE_NAME} kong/kong

Replace {NAMESPACE}, {CHART_VERSION} and {RELEASE_NAME} with the values you deployed Kong Gateway with.

Alternatively, if you are using command line flags to deploy and manage Kong Gateway, the same configuration can be achieved with flags:

$ helm upgrade --namespace {NAMESPACE} --version {CHART_VERSION} {RELEASE_NAME} kong/kong \
  --set "udpProxy.enabled=true" \
  --set "udpProxy.type=LoadBalancer" \
  --set "udpProxy.stream[0].containerPort=9999"
  --set "udpProxy.stream[0].servicePort=9999"
  --set "udpProxy.stream[0].protocol=UDP"

Watch the services using kubectl get services and wait for the LoadBalancer service to be ready for the Gateway. Once the service up, Kong Gateway is ready to serve UDP traffic on the external port 9999 using UDPIngress resources.

Deploying UDPIngress

Now that Kong Gateway is listening on 9999, you can create a UDPIngress resource which will attach the CoreDNS service to that port so you can make DNS requests to it from outside the cluster.

Save the following file as coredns-udpingress.yaml:

apiVersion: configuration.konghq.com/v1beta1
kind: UDPIngress
metadata:
  name: minudp
  namespace: udpingress-example
  annotations:
    kubernetes.io/ingress.class: kong
spec:
  rules:
  - backend:
      serviceName: coredns
      servicePort: 53
    port: 9999

This configuration binds the Kong Gateway port 9999 to the Service port 53 for our DNS server.

Apply the coredns-udpingress.yaml manifests:

$ kubectl apply -f coredns-udpingress.yaml

You can now make DNS requests via Kong Gateway.

Verification

Now that setup is complete, all that’s left to do is verify that everything is working by making a DNS request to our CoreDNS server.

Note: This example assumes you have the dig command available on your local system. If you don’t, refer to your operating system documentation for a similar DNS lookup tool.

First, retrieve the IP address of the UDP load balancer service that we configured in previous sections:

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

Replace {NAMESPACE} and {RELEASE_NAME} with the values you originally provided to helm install in your own environment.

Now that you’ve stored the IP in the environment variable KONG_UDP_ENDPOINT, you can use that with dig to do a DNS lookup through the CoreDNS server you set up and exposed using UDPIngress:

Command
Response
$ dig @${KONG_UDP_ENDPOINT} -p 9999 konghq.com
;; ANSWER SECTION:
konghq.com.		30	IN	A	34.83.126.248

;; Query time: 60 msec
;; SERVER: <KONG_UDP_ENDPOINT>#9999
;; WHEN: Thu Aug 19 08:39:16 EDT 2021
;; MSG SIZE  rcvd: 77

Verify that the {KONG_UDP_ENDPOINT} in the SERVER section of the response above ends up being equal to your ${KONG_UDP_ENDPOINT} value.

Now you’re equipped to route UDP traffic into your Kubernetes cluster with Kong Gateway!

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