pumba

Strumento di chaos testing per Docker, containerd e Podman

Avvio rapido · Guida utente · Chaos di rete · Distribuzione · Contribuire

Pumba è uno strumento di chaos testing ed emulazione di rete per i container Docker, containerd e Podman. Ispirato a Netflix Chaos Monkey, Pumba porta l'ingegneria del caos a livello di container: kill, stop, pause e rimozione dei container, iniezione di ritardi di rete e perdita di pacchetti, oppure stress test delle risorse dei container.

Come funziona

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]

Runtimes supportati

Piattaforme supportate

Pumba ha come target i container Linux: ogni azione di chaos dipende da primitive Linux (netns, cgroups v2, iptables, tc qdisc, socket dei runtime dei container). Binari rilasciati:

Windows non viene volutamente compilato. Le primitive del chaos — scritture netns/cgroup Linux, iniezione sidecar tc/iptables, inoltro dei segnali POSIX (SIGCONT/SIGSTOP/SIGUSR1/SIGUSR2 usati dal runtime containerd) — non hanno un equivalente su Windows. Non esiste un caso d'uso plausibile su Windows nemmeno con il backend WSL2 di Docker Desktop, quindi non viene pubblicato alcun binario Windows. Le PR che aggiungono il supporto Windows non saranno accettate; esegui pumba su Linux (nativo, in container o in VM).

Funzionalità

Avvio rapido

Installazione

Scarica l'ultima release per la tua piattaforma, oppure usa 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

Primo 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

Runtime containerd

# 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>

Runtime Podman

Pumba comunica con Podman tramite il socket Docker-compat. --podman-socket è opzionale — se vuoto, pumba controlla in ordine $CONTAINER_HOST, $PODMAN_SOCK, podman machine inspect, /run/podman/podman.sock e $XDG_RUNTIME_DIR/podman/podman.sock.

# 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 e stress richiedono Podman rootful: in modalità rootless il comando fallisce subito con un messaggio chiaro che indica podman machine set --rootful (macOS) o l'unità systemd rootful (Linux).

Sviluppo su macOS con Podman

Podman su macOS viene eseguito all'interno di una VM Linux. Pumba deve girare sullo stesso kernel dei container target (lettura di /proc/<pid>/cgroup lato host), quindi esegui il binario di pumba dentro la VM podman machine:

# 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>

Suggerimento: per il chaos di rete su container senza tc/iptables, usa --tc-image per avviare un sidecar:

root@kitploit:~

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

Eseguire con 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"

Immagini Docker

Le immagini sono compilate nativamente per linux/amd64 e linux/arm64 (niente QEMU).

Documentazione

Demo

Community e supporto

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

Licenza

Apache License 2.0