Expose UDP applications

What you’ll accomplish

After completing this guide, your application will be accessible over UDP through Envoy Gateway. Istio does not support UDP ingress, so UDS Core routes protocol: UDP expose entries through a separate Envoy Gateway control plane instead of the Istio tenant or admin gateways.

Caution

UDP traffic routed through Envoy Gateway is not protected by Istio AuthorizationPolicy or mTLS. Only expose UDP services when there is a clear requirement, and rely on your application’s own authentication or the network policy generated by the Package CR to restrict access.

Before you begin

UDS Core supports two Gateway modes for UDP exposes:

• Default Gateway: a single shared Gateway managed by UDS Core, used when you omit the gateway field on an expose entry. Simplest option; suitable when your application doesn’t need an isolated Gateway.
• User-managed Gateway: a Gateway you deploy and manage yourself, referenced by name in the gateway field. Use this when you need an isolated proxy, a dedicated load balancer IP, or independent lifecycle management for the Gateway.

Prerequisites

• UDS CLI installed
• UDS Registry account created and authenticated locally with a read token
• Access to a Kubernetes cluster with UDS Core deployed
• An application with a service listening on a UDP port
• Familiarity with Zarf packages and UDS Bundles

Steps

1. Enable Envoy Gateway in your UDS Core bundle

   Envoy Gateway is not deployed by default. Enable the controller and the default Gateway namespace by adding both as optional components:

   uds-bundle.yaml

   packages:
     - name: core
       repository: registry.defenseunicorns.com/public/core
       ref: x.x.x-upstream
       optionalComponents:
         - envoy-gateway          # The Envoy Gateway controller
         - envoy-default-gateway  # The default Gateway's namespace, only needed for default-Gateway mode

   Create and deploy the bundle:

   uds create --confirm && uds deploy uds-bundle-*.tar.zst --confirm

2. Expose your service over UDP

   Set protocol: UDP on an expose entry. The Package CR is denied if host, domain, advancedHTTP, or match are set on a UDP entry; routing is by port only.

   Default Gateway

   Omit gateway to route through the shared, UDS Core managed default Gateway:

   uds-package.yaml

   apiVersion: uds.dev/v1alpha1
   kind: Package
   metadata:
     name: my-udp-app
     namespace: my-udp-app
   spec:
     network:
       expose:
         - service: my-udp-app-service
           selector:
             app.kubernetes.io/name: my-udp-app
           protocol: UDP
           port: 5000

   This routes UDP traffic on port 5000 through the default Gateway’s LoadBalancer service.

   User-managed Gateway

   Set gateway to the name of a Gateway you manage yourself. UDS Core uses this value as both the Gateway name and its namespace.

   uds-package.yaml

   apiVersion: uds.dev/v1alpha1
   kind: Package
   metadata:
     name: my-udp-app
     namespace: my-udp-app
   spec:
     network:
       expose:
         - service: my-udp-app-service
           selector:
             app.kubernetes.io/name: my-udp-app
           protocol: UDP
           gateway: my-custom-gateway
           port: 5000

   Caution

   The my-custom-gateway namespace must be deployed through a Zarf package, so it receives the private registry image pull secret, and must be enrolled in the cluster’s service mesh (label the namespace istio.io/dataplane-mode: ambient), so the managed proxy can establish its mTLS-protected xDS connection to the Envoy Gateway controller. If either requirement is missing, the managed proxy fails to start.

3. Deploy your application

   (Recommended) Include the Package CR in your Zarf package and create/deploy. See Packaging applications for general packaging guidance.

   uds zarf package create --confirm
   uds zarf package deploy zarf-package-*.tar.zst --confirm

   Or apply the Package CR directly for quick testing:

   uds zarf tools kubectl apply -f uds-package.yaml

Verification

Check that the Package CR was reconciled:

uds zarf tools kubectl get package my-udp-app -n my-udp-app

Find the external address of the Gateway’s load balancer service (envoy-default-gateway namespace for default-Gateway mode, or your custom Gateway’s namespace for user-managed mode):

uds zarf tools kubectl get svc -n envoy-default-gateway

Test the connection with a UDP client on the load balancer IP and the port from your Package CR:

echo "ping" | nc -u <load-balancer-ip> 5000

Troubleshooting

Problem: Package CR shows no endpoint

Symptom: The Package CR reconciles but ENDPOINTS is empty or the status never becomes ready.

Solution:

• Confirm envoy-gateway (and envoy-default-gateway, for default-Gateway mode) are listed under optionalComponents in your bundle
• Check the Envoy Gateway controller is running: uds zarf tools kubectl get pods -n envoy-gateway-system
• For user-managed Gateways, confirm the Gateway’s namespace has the istio.io/dataplane-mode: ambient label and was deployed via a Zarf package

Problem: Connection timeout

Symptom: UDP client hangs without a response.

Solution:

• Verify the network policy allows ingress from the Envoy Gateway proxy: uds zarf tools kubectl get package my-udp-app -n my-udp-app
• Confirm the destination service and port are correct: uds zarf tools kubectl get svc -n my-udp-app
• Check the managed proxy pod logs in the Gateway’s namespace for xDS connection errors

Related documentation

• Networking & Service Mesh Concepts - how the service mesh, gateways, and network policies work together in UDS Core
• Package CR Reference - full CR schema and field reference for network, SSO, and monitoring configuration
• Expose applications on gateways - Expose HTTP applications through the Istio tenant or admin gateway.
• Set up non-HTTP ingress - Expose TCP applications through Istio.
• Create a custom gateway - Deploy an Istio gateway with independent domain, TLS, and security controls.