User Datagram Protocol (UDP)

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