pumba

Chaos testing tool for Docker, containerd, and Podman

Quick Start · User Guide · Network Chaos · Deployment · Contributing

---

Pumba is a chaos testing and network emulation tool for Docker, containerd, and Podman containers. Inspired by Netflix Chaos Monkey, Pumba brings chaos engineering to the container level — kill, stop, pause, and remove containers, inject network delays and packet loss, or stress-test container resources.

How It Works

graph LR
    A[Pumba CLI] -->|Docker API / containerd API / Podman compat API| B[Container Runtime]
    B -->|List & Filter| C[Target Containers]

    A -->|kill / stop / pause / rm| C

    A -->|netem / iptables| D[Helper Container / Direct Exec]
    D -->|Shares network namespace| C
    D -->|Runs tc / iptables| E[Network Chaos]

Supported runtimes

Runtime	Socket (default)	netem / iptables / stress	Notes
Docker	/var/run/docker.sock	Works as root or with socket access	Default runtime.
containerd	/run/containerd/containerd.sock	Requires root (overlayfs mounts for sidecar)	Namespaces: k8s.io (Kubernetes), moby (Docker-managed), default (pure containerd).
Podman	/run/podman/podman.sock (rootful)	Requires rootful Podman (fails fast else)	Uses Podman's Docker-compat API; on macOS pumba runs inside podman machine (see below).

Supported platforms

Pumba targets Linux containers — every chaos action depends on Linux primitives (netns, cgroups v2, iptables, tc qdiscs, container runtime sockets). Released binaries:

OS	amd64	arm64	Notes
Linux	✅	✅	Primary target. Run pumba on the same kernel as the targeted containers.
macOS	✅	✅	Developer ergonomics only. Use it to drive a remote Docker/Podman/containerd VM (e.g. Colima, podman machine).
Windows	❌	❌	Not supported and not planned. See below.

Windows is intentionally not built. The chaos primitives — Linux netns/cgroup writes, tc/iptables sidecar injection, POSIX signal forwarding (SIGCONT/SIGSTOP/SIGUSR1/SIGUSR2 used by the containerd runtime) — have no Windows equivalent. There is no plausible Windows use case even with Docker Desktop's WSL2 backend, so no Windows binary is published. PRs adding Windows support will not be accepted; please run pumba on Linux (native, container, or VM).

Features

Category	Commands	Description
Container Chaos	kill, stop, pause, rm, restart	Disrupt container lifecycle
Execute	exec	Run commands inside containers
Network Delay	netem delay	Add latency to egress traffic
Packet Loss	netem loss, iptables loss	Drop packets (egress and ingress)
Network Effects	netem duplicate, corrupt, rate	Duplicate, corrupt, or rate-limit packets
Stress Testing	stress	CPU, memory, I/O stress via stress-ng (child cgroup or same-cgroup injection)
Targeting	names, regex (re2:), labels, --random	Flexible container selection
Scheduling	--interval	Recurring chaos at fixed intervals

Quick Start

Install

Download the latest release for your platform, or use Docker:

# Binary
curl -sL https://github.com/alexei-led/pumba/releases/latest/download/pumba_linux_amd64 -o pumba
chmod +x pumba

# Docker (recommended)
docker pull ghcr.io/alexei-led/pumba:latest

First Chaos

# Kill a random container matching "test" every 30 seconds
pumba --interval=30s --random kill "re2:^test"

# Add 3 seconds network delay to mydb for 5 minutes
pumba netem --duration 5m delay --time 3000 mydb

# Drop 10% of incoming packets to myapp for 2 minutes
pumba iptables --duration 2m loss --probability 0.1 myapp

# Stress CPU of mycontainer for 60 seconds
pumba stress --duration 60s --stressors="--cpu 4 --timeout 60s" mycontainer

Containerd Runtime

# Kill a container by ID via containerd
pumba --runtime containerd --containerd-namespace k8s.io kill <container-id>

# Add network delay via containerd (requires tc in the container image)
pumba --runtime containerd --containerd-namespace moby \
  netem --duration 5m delay --time 3000 <container-id>

Podman Runtime

Pumba talks to Podman via its Docker-compat socket. --podman-socket is optional — if empty, pumba probes $CONTAINER_HOST, $PODMAN_SOCK, podman machine inspect, /run/podman/podman.sock, and $XDG_RUNTIME_DIR/podman/podman.sock in order.

# Kill a container by name via Podman (rootful socket auto-detected)
sudo pumba --runtime podman kill mycontainer