Kubernetes UDP Ingress and Load Balancing Guide

Kubernetes manages UDP traffic primarily at Layer 4 of the OSI model rather than through traditional Layer 7 HTTP-based Ingress routing. While the standard Kubernetes Ingress resource is designed specifically for HTTP and HTTPS protocols, Kubernetes handles UDP load balancing and external access using native Service types, specialized Ingress controller stream features, the modern Gateway API, and internal routing managed by kube-proxy.

Layer 4 Kubernetes Services

The primary and most straightforward method for handling UDP traffic in Kubernetes is through a standard Service resource configured with protocol: UDP.

• Service Type LoadBalancer: When deployed in a cloud environment (such as AWS, GCP, or Azure) or on-premises with tools like MetalLB, a LoadBalancer service provisions an external Layer 4 network load balancer that forwards incoming UDP datagrams directly to the cluster nodes and target pods.
• Service Type NodePort: Exposes a static port on each node’s IP address configured for UDP. External traffic hitting <NodeIP>:<NodePort> is forwarded to the corresponding backend pods.

UDP Handling with Ingress Controllers

Standard Kubernetes Ingress resources only route HTTP/HTTPS traffic based on hostnames and paths. To bypass this limitation, several popular Ingress controllers provide custom Layer 4 streaming capabilities:

• NGINX Ingress Controller: Uses a dedicated ConfigMap (typically named udp-services) to map external UDP ports to internal Kubernetes services using NGINX’s stream module.
• Traefik and HAProxy: Support native Layer 4 TCP/UDP ingress definitions via custom resource definitions (CRDs) or entry point configurations, allowing UDP packets to pass through the ingress layer directly to target workloads.

The Kubernetes Gateway API and UDPRoute

The Kubernetes Gateway API provides a modern, expressive replacement for the legacy Ingress resource. It natively incorporates Layer 4 protocols via the UDPRoute resource.

With UDPRoute, administrators can define a Gateway listener bound to the UDP protocol and attach route rules that direct UDP traffic to specific backend services. This approach standardizes UDP ingress without requiring controller-specific ConfigMaps or non-standard annotations.

Internal Routing and kube-proxy Behavior

Once UDP traffic arrives at a node, kube-proxy handles internal distribution to target pods using iptables or IPVS modes:

• Connection Tracking: Because UDP is connectionless, the Linux kernel’s conntrack table creates pseudo-connections based on source and destination IP/port tuples to maintain routing state for return traffic.
• Session Affinity: Kubernetes supports setting sessionAffinity: ClientIP on UDP services to ensure datagrams from the same client are routed consistently to the same pod for a specified timeout period.
• Source IP Preservation: Setting externalTrafficPolicy: Local on the Service prevents an extra network hop and preserves the client’s original IP address, though it requires the incoming traffic to hit a node that currently runs a healthy pod instance.