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

Runtime	Socket (predefinito)	netem / iptables / stress	Note
Docker	/var/run/docker.sock	Funziona come root o con accesso al socket	Runtime predefinito.
containerd	/run/containerd/containerd.sock	Richiede root (mount overlayfs per il sidecar)	Namespace: k8s.io (Kubernetes), moby (gestito da Docker), default (containerd puro).
Podman	/run/podman/podman.sock (rootful)	Richiede Podman rootful (altrimenti fallisce subito)	Usa l'API Docker-compat di Podman; su macOS pumba viene eseguito dentro podman machine (vedi sotto).

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:

OS	amd64	arm64	Note
Linux	✅	✅	Target primario. Esegui pumba sullo stesso kernel dei container target.
macOS	✅	✅	Solo ergonomia per gli sviluppatori. Usalo per guidare una VM Docker/Podman/containerd remota (es. Colima, podman machine).
Windows	❌	❌	Non supportato e non pianificato. Vedi sotto.

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à

Categoria	Comandi	Descrizione
Chaos sui container	kill, stop, pause, rm, restart	Interrompi il ciclo di vita dei container
Esecuzione	exec	Esegui comandi all'interno dei container
Ritardo di rete	netem delay	Aggiungi latenza al traffico in uscita
Perdita di pacchetti	netem loss, iptables loss	Scarta pacchetti (in uscita e in ingresso)
Effetti di rete	netem duplicate, corrupt, rate	Duplica, corrompi o limita la velocità dei pacchetti
Stress test	stress	Stress di CPU, memoria e I/O tramite stress-ng (child cgroup o iniezione nello stesso cgroup)
Selezione dei target	nomi, regex (re2:), label, --random	Selezione flessibile dei container
Pianificazione	--interval	Chaos ricorrente a intervalli fissi

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