Introduction

Configuring UDP with ingress-nginx is different from ordinary HTTP ingress, and that difference is what usually causes confusion. UDP is not configured through a standard Ingress resource. Instead, ingress-nginx expects a controller-level TCP or UDP mapping, usually through a ConfigMap plus matching service ports on the controller.

Why normal Ingress YAML is not enough

A standard Ingress object is for HTTP and HTTPS routing. It understands host and path semantics, which do not apply to generic UDP traffic.

So if you try to solve UDP exposure with only this kind of resource:

kind: Ingress

you are usually solving the wrong problem. For UDP on ingress-nginx, you need stream-level forwarding configuration.

The ingress-nginx UDP pattern

The controller reads a ConfigMap that maps an exposed UDP port on the ingress controller to a Kubernetes service and target port.

Example UDP services ConfigMap:

1apiVersion: v1
2kind: ConfigMap
3metadata:
4  name: udp-services
5  namespace: ingress-nginx
6data:
7  "5353": "default/dns-proxy:5353"

This means:

• expose UDP port 5353 on the ingress-nginx controller
• forward it to service dns-proxy in namespace default
• use backend service port 5353

Tell the controller to use that ConfigMap

The controller deployment or Helm values must reference the UDP ConfigMap.

Helm-style example:

controller:
  udp:
    5353: "default/dns-proxy:5353"

Or, in an argument-based deployment setup, the controller may need:

args:
  - /nginx-ingress-controller
  - --udp-services-configmap=ingress-nginx/udp-services

If the controller never receives this configuration, the ConfigMap can exist and still do nothing.

Expose the UDP port on the controller service

Another common omission is forgetting to expose the same UDP port on the ingress-nginx service itself.

1apiVersion: v1
2kind: Service
3metadata:
4  name: ingress-nginx-controller
5  namespace: ingress-nginx
6spec:
7  ports:
8    - name: http
9      port: 80
10      protocol: TCP
11      targetPort: 80
12    - name: udp-5353
13      port: 5353
14      protocol: UDP
15      targetPort: 5353

Without a matching service port, the external load balancer or node-level service cannot receive that UDP traffic at all.

Verify the full path

When UDP still does not work, validate each layer separately:

1. the backend service exists and listens on the expected UDP port
2. the UDP ConfigMap is present and correct
3. the controller is configured to watch that ConfigMap
4. the ingress-nginx service exposes the UDP port
5. the external load balancer or firewall allows UDP on that port

Useful checks:

kubectl -n ingress-nginx get configmap udp-services -o yaml
kubectl -n ingress-nginx get svc ingress-nginx-controller -o yaml
kubectl -n ingress-nginx logs deploy/ingress-nginx-controller

Cloud and load balancer limitations

Even if Kubernetes configuration is correct, some environments add another constraint:

• the cloud load balancer may not forward UDP automatically
• security groups may allow TCP but not UDP
• a managed ingress setup may support HTTP only

So a working TCP ingress does not prove UDP will work on the same infrastructure.

Common Pitfalls

The most common mistake is trying to configure UDP through a normal Ingress resource. Another is creating the UDP ConfigMap but forgetting to expose the same UDP port on the controller service. Teams also often overlook the controller argument or Helm setting that tells ingress-nginx which ConfigMap to read. Cloud firewalls and load balancers are another frequent blind spot because they may be configured for TCP only. Finally, people often debug the ingress controller first when the backend service is not actually listening on the expected UDP port.

Summary

• UDP on ingress-nginx is not configured through ordinary HTTP ingress rules.
• Use a UDP mapping ConfigMap or the equivalent Helm configuration.
• Make sure the ingress controller is explicitly pointed at that UDP config.
• Expose the same UDP port on the ingress-nginx controller service.
• Verify backend service, controller config, and external network policy separately.
• Treat UDP support as a controller-plus-service-plus-infrastructure problem, not just an ingress manifest problem.