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
Combined Effects	netem combine	Apply multiple effects in one owned netem qdisc
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; netem/iptables also offer opt-in --match-all
Scheduling	--interval	Recurring chaos at fixed intervals
Agents	schema, --output ndjson	CLI description as JSON; result events on stdout
Leftover check	status [--check], revert --run-id	Inspect faults and recover eligible run-tagged rules/sidecars

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

# Combine 100ms delay and 20% packet loss in one qdisc
pumba netem --duration 5m combine --delay --delay-time 100 --loss --loss-percent 20 -- 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

# Did a crashed run leave faults behind? Exit 0 only when clean
pumba status --check myapp

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

# Add network delay via Podman (requires rootful socket)
sudo pumba --runtime podman netem --duration 5m delay --time 3000 mycontainer

# Stress CPU via Podman (default child-cgroup mode)
sudo pumba --runtime podman stress --duration 60s --stressors="--cpu 4 --timeout 60s" mycontainer

# Explicit socket override
pumba --runtime podman --podman-socket unix:///run/podman/podman.sock kill mycontainer

netem, iptables, and stress require rootful Podman — rootless fails fast with a clear message pointing at podman machine set --rootful (macOS) or the rootful systemd unit (Linux).

macOS development with Podman

Podman on macOS runs inside a Linux VM. Pumba must run on the same kernel as the target containers (host-side /proc/<pid>/cgroup read), so run the pumba binary inside the podman machine VM:

# one-time setup
brew install podman
podman machine init --rootful --cpus 4 --memory 4096 --now
podman machine ssh sudo dnf install -y bats      # optional, for bats tests

# copy a linux/arm64 or linux/amd64 pumba binary into the VM
podman machine ssh sudo cp /path/to/pumba /usr/local/bin/

# run inside the VM
podman machine ssh sudo pumba --runtime podman --log-level debug ps
podman machine ssh sudo pumba --runtime podman netem --duration 10s delay --time 200 <container-id>

Tip: For network chaos on containers without tc/iptables, use --tc-image to spawn a sidecar:

pumba --runtime containerd netem --tc-image ghcr.io/alexei-led/pumba-alpine-nettools:latest \
  --duration 5m delay --time 3000 <container-id>

Global flags

Flag	Default	Environment variable	Description
--host, -H	unix:///var/run/docker.sock	DOCKER_HOST	Daemon socket to connect to
--runtime	docker	—	Container runtime: docker, containerd, or podman
--containerd-socket	/run/containerd/containerd.sock	—	containerd socket location
--containerd-namespace	k8s.io	—	containerd namespace
--podman-socket	Empty (auto-detected)	—	Podman socket URI; see Podman Runtime for discovery
--tls	false	—	Use TLS; implied by --tlsverify
--tlsverify	false	DOCKER_TLS_VERIFY	Use TLS and verify the remote
--tlscacert	/etc/ssl/docker/ca.pem	—	Trust certificates signed only by this CA
--tlscert	/etc/ssl/docker/cert.pem	—	Client certificate for TLS authentication
--tlskey	/etc/ssl/docker/key.pem	—	Client key for TLS authentication
--log-level, -l	warning	LOG_LEVEL	Log level: debug, info, warning, error, fatal, panic
--json, -j	false	LOG_JSON	JSON log output (Logstash/Splunk-friendly)
--slackhook	Empty	—	Slack incoming webhook URL for log events
--slackchannel	#pumba	—	Slack channel for log events
--interval, -i	0s (single run)	—	Recurring interval; accepts ms, s, m, or h
--label	Empty list	—	Filter by labels: --label k1=v1 --label k2=v2 or --label k1=v1,k2=v2 (AND logic); unsupported for containerd
--max-targets	unset	—	Refuse before any injection when targets exceed N after --limit/--random; 0 disables the cap; applies to dry-run and every interval tick
--random, -r	false	—	Pick one matching container at random
--dry-run	false	DRY-RUN	Preview without chaos or duration waits; netem/iptables print apply/revert commands to stdout
--skip-error	false	—	Skip chaos command errors and retry on the next interval tick
--output, -o	text	—	ndjson: result events (pumba.event/v1) on stdout, one per line; logs stay on stderr
--run-id	Generated	—	Name this run in result events and tag what it creates (sidecar labels, iptables comments); 1–48 characters from [A-Za-z0-9_.-]
--max-duration	0 (unlimited)	—	Time budget for active chaos and --interval; on expiry in-flight chaos is cleaned up and the run exits 1
--webhook	Empty	—	POST each result event as JSON to this http(s) URL; best effort, in every --output mode
--help, -h	false	—	Show help (built-in)
--version, -v	false	—	Print the version (built-in)

TLS certificate defaults use DOCKER_CERT_PATH instead of /etc/ssl/docker when set. --interval=0 runs once. Use --skip-error with intervals to continue after transient failures. Safety-cap refusals are never suppressed by --skip-error. Agents and scripts: pumba schema prints every command and flag as JSON (pumba.cli/v1) without a runtime socket; see docs/agents.md for it, the result event contract, error codes and exit codes.

Run with Docker

docker run -it --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/alexei-led/pumba --interval=10s --random kill "re2:^test"

Docker Images

Registry	Image	Status
GitHub Container Registry	ghcr.io/alexei-led/pumba	✠Primary
Docker Hub	alexeiled/pumba	⚠️ Deprecated

Images are built natively for linux/amd64 and linux/arm64 (no QEMU).

Documentation

Document	Description
User Guide	Container chaos commands, targeting, scheduling, configuration
Network Chaos	netem, iptables, advanced scenarios, architecture diagrams
Auth Outage Rehearsal	Bounded staging auth-dependency outage example
Stress Testing	CPU/memory/IO stress testing with stress-ng
Deployment	Docker, Kubernetes DaemonSets, OpenShift
Agents	NDJSON/webhook events, pumba schema, status --check, exit codes, run budget
Architecture	Module boundaries and the archfit policy that enforces them
Contributing	Build from source, run tests, project structure

Demo

Community & Support

• Issues: GitHub Issues
• Blog: Pumba - Chaos Testing for Docker

License

Apache License 2.0