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](https://netflix.github.io/chaosmonkey/), 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 ```mermaid 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 | | **Scheduling** | `--interval` | Recurring chaos at fixed intervals | ## Quick Start ### Install Download the [latest release](https://github.com/alexei-led/pumba/releases) for your platform, or use Docker: ```bash # 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 ```bash # 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 ``` ### Containerd Runtime ```bash # Kill a container by ID via containerd pumba --runtime containerd --containerd-namespace k8s.io kill # Add network delay via containerd (requires tc in the container image) pumba --runtime containerd --containerd-namespace moby \ netem --duration 5m delay --time 3000 ``` ### 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. ```bash # 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//cgroup` read), so run the pumba binary **inside** the `podman machine` VM: ```bash # 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 ``` | Flag | Default | Description | | ------------------------ | --------------------------------- | ---------------------------------------------------------------------------------------- | | `--runtime` | `docker` | Container runtime (`docker`, `containerd`, or `podman`) | | `--containerd-socket` | `/run/containerd/containerd.sock` | containerd socket path | | `--containerd-namespace` | `k8s.io` | containerd namespace (`k8s.io` for Kubernetes, `moby` for Docker) | | `--podman-socket` | _(auto-detected)_ | Podman socket URI (e.g. `unix:///run/podman/podman.sock`); empty triggers auto-detection | > **Tip:** For network chaos on containers without `tc`/`iptables`, use `--tc-image` to spawn a sidecar: > > ```bash > pumba --runtime containerd netem --tc-image ghcr.io/alexei-led/pumba-alpine-nettools:latest \ > --duration 5m delay --time 3000 > ``` ### Run with Docker ```bash 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](docs/guide.md)** | Container chaos commands, targeting, scheduling, configuration | | **[Network Chaos](docs/network-chaos.md)** | netem, iptables, advanced scenarios, architecture diagrams | | **[Stress Testing](docs/stress-testing.md)** | CPU/memory/IO stress testing with stress-ng | | **[Deployment](docs/deployment.md)** | Docker, Kubernetes DaemonSets, OpenShift | | **[Contributing](CONTRIBUTING.md)** | Build from source, run tests, project structure | ## Demo [![asciicast](https://asciinema.org/a/82428.png)](https://asciinema.org/a/82428) ## Community & Support - **Issues**: [GitHub Issues](https://github.com/alexei-led/pumba/issues) - **Blog**: [Pumba - Chaos Testing for Docker](https://medium.com/p/pumba-chaos-testing-for-docker-d55c91aee013) ## License [Apache License 2.0](LICENSE)