User Datagram Protocol (UDP)

Requirements

Sandbox environment

Setup your sandbox environment with Docker and Docker Compose, and clone the Envoy repository with Git.

curl

Used to make HTTP requests.

netcat

Used to send UDP packets.

This sandbox provides a very simple example of Envoy proxying UDP.

It also demonstrates UDP traffic stats provided by the Envoy admin endpoint.

Step 1: Build the sandbox

Change directory to examples/udp in the Envoy repository.

Start the Docker composition:

$ pwd
envoy/examples/udp
$ docker compose pull
$ docker compose up --build -d
$ docker compose ps

    Name                 Command                   State      Ports
-----------------------------------------------------------------------------------------------------------------------
udp_envoy-udp_1     /docker-entrypoint.sh /usr ... Up     10000/tcp, 0.0.0.0:10000->10000/udp, 0.0.0.0:10001->10001/tcp
udp_service-udp_1   python -u /udplistener.py      Up     5005/tcp, 5005/udp

Envoy should proxy UDP on port 10000 to an upstream server listening on port 5005.

Envoy also provides an admin endpoint listening on port 10001.

Step 2: Send some UDP messages

You can use netcat to send packets to the upstream server, proxied by Envoy:

echo -n HELO | nc -4u -w1 127.0.0.1 10000
echo -n OLEH | nc -4u -w1 127.0.0.1 10000

Step 3: Check the logs of the upstream UDP listener server

Checking the logs of the upstream server you should see the packets that you sent:

$ docker compose logs service-udp
Attaching to udp_service-udp_1
service-udp_1  | Listening on UDP port 5005
service-udp_1  | HELO
service-udp_1  | OLEH

Step 4: View the Envoy admin UDP stats

You can view the UDP-related stats provided by the Envoy admin endpoint.

For example, to view the non-zero stats:

$ curl -s http://127.0.0.1:10001/stats | grep udp | grep -v "\: 0"
cluster.service_udp.default.total_match_count: 1
cluster.service_udp.max_host_weight: 1
cluster.service_udp.membership_change: 1
cluster.service_udp.membership_healthy: 1
cluster.service_udp.membership_total: 1
cluster.service_udp.udp.sess_tx_datagrams: 2
cluster.service_udp.update_attempt: 1
cluster.service_udp.update_success: 1
cluster.service_udp.upstream_cx_tx_bytes_total: 8
udp.service.downstream_sess_active: 2
udp.service.downstream_sess_rx_bytes: 8
udp.service.downstream_sess_rx_datagrams: 2
udp.service.downstream_sess_total: 2
cluster.service_udp.upstream_cx_connect_ms: No recorded values
cluster.service_udp.upstream_cx_length_ms: No recorded values