How to Simulate Network Latency and Packet Loss in Docker with Pumba

Introduction

In microservice testing, Docker is the preferred way to build, ship, and run services, but reproducing network faults is difficult. Pumba, a chaos‑testing tool inspired by Netflix's Chaos Monkey, provides a simple way to inject network latency and packet loss into Docker containers.

Pumba Overview

Pumba operates on containers (not VMs) and can kill, stop, restart, or pause processes inside them. For network emulation it leverages Linux's netem queuing discipline via the tc utility. The target container must have iproute2 installed.

Netem Commands

Pumba exposes the following netem sub‑commands:

netem delay : adds artificial latency.

netem loss , loss‑state , loss‑gemodel : simulate packet loss using different statistical models.

All commands accept options such as --duration, --interface, --time, --jitter, --correlation, and container selectors (by name or RE2 regex).

Delay Example (netem delay)

The following demo runs two containers: one that continuously pings a host, and a Pumba container that adds a 3‑second delay for one minute.

# Open two terminals (1) and (2)
# Terminal (1): create a container with iproute2 and start ping
$ docker run -it --rm --name tryme alpine sh -c "apk add --update iproute2 && ping www.example.com"
# Terminal (2): run Pumba to add 3s delay for 1 minute
$ docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock gaiaadm/pumba \
    pumba netem --interface eth0 --duration 1m delay --time 3000 tryme
# Observe that each ping is delayed by ~3000 ms for the minute.
# Press Ctrl‑C to stop early.

Advanced Delay Usage

More complex delay scenarios can be expressed with additional flags:

# Add 3s delay with 30 ms jitter and 20% packet loss for containers matching "hp*" on eth1
$ docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock gaiaadm/pumba \
    pumba netem --duration 5m --interface eth1 \
    delay --time 3000 --jitter 30 --correlation 20 re2:^hp

# Randomly select containers and apply a normal‑distributed delay
$ docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock gaiaadm/pumba \
    pumba netem --duration 5m --random delay \
    --time 3000 --jitter 40 --distribution normal container1 container2 container3

Loss Example (netem loss)

To demonstrate packet loss, three containers are used: an iperf server, an iperf client, and a Pumba container that drops packets from the client.

# Terminal (1): start iperf UDP server
$ docker run -it --rm --name tryme-srv alpine sh -c "apk add --update iperf && iperf -s -u -i 1"
# Terminal (2): start iperf client with iproute2
$ docker run -it --rm --name tryme alpine sh -c "apk add --update iproute2 iperf && iperf -c 172.17.0.3 -u"
# Terminal (3): apply 20% packet loss for 1 minute
$ docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock gaiaadm/pumba \
    pumba netem --duration 1m loss --percent 20 tryme
# The server will report the lost datagrams.

Pumba supports three loss models: loss: Bernoulli (independent) loss. loss-state: 2‑, 3‑, or 4‑order Markov models. loss-gemodel: Gilbert or Gilbert‑Elliott models.

Additional Resources

For more examples, refer to the official Pumba repository:

https://github.com/alexei-led/pumba

Binary releases for Windows, Linux, and macOS are available at:

https://github.com/alexei-led/pumba/releases

Docker images can be pulled from:

https://hub.docker.com/r/gaiaadm/pumba/