pumba

Herramienta de pruebas de caos para Docker, containerd y Podman

Inicio rápido · Guía de usuario · Caos de red · Despliegue · Contribuciones

Pumba es una herramienta de pruebas de caos y emulación de red para contenedores Docker, containerd y Podman. Inspirado en Netflix Chaos Monkey, Pumba lleva la ingeniería del caos al nivel de contenedor — matar, detener, pausar y eliminar contenedores, inyectar retrasos de red y pérdida de paquetes, o realizar pruebas de estrés sobre los recursos de los contenedores.

Cómo funciona

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 compatibles

Plataformas compatibles

Pumba se dirige a contenedores Linux: cada acción de caos depende de primitivas de Linux (netns, cgroups v2, iptables, tc qdiscs, sockets del runtime de contenedores). Binarios publicados:

Windows no se compila intencionalmente. Las primitivas de caos — escrituras de netns/cgroup de Linux, inyección de sidecar tc/iptables, reenvío de señales POSIX (SIGCONT/SIGSTOP/SIGUSR1/SIGUSR2 utilizadas por el runtime containerd) — no tienen equivalente en Windows. No hay un caso de uso plausible para Windows ni siquiera con el backend WSL2 de Docker Desktop, por lo que no se publica ningún binario de Windows. No se aceptarán PRs que añadan soporte para Windows; por favor ejecuta pumba en Linux (nativo, contenedor o VM).

Características

Inicio rápido

Instalación

Descarga la última versión para tu plataforma, o 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

Primer caos

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

Pumba se comunica con Podman a través de su socket Docker-compat. --podman-socket es opcional: si está vacío, pumba sondea $CONTAINER_HOST, $PODMAN_SOCK, podman machine inspect, /run/podman/podman.sock y $XDG_RUNTIME_DIR/podman/podman.sock en ese orden.

# 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 y stress requieren Podman rootful; el modo rootless falla rápidamente con un mensaje claro que señala podman machine set --rootful (macOS) o la unidad systemd rootful (Linux).

Desarrollo en macOS con Podman

Podman en macOS se ejecuta dentro de una VM Linux. Pumba debe ejecutarse en el mismo kernel que los contenedores objetivo (lectura de /proc/<pid>/cgroup del lado del host), por lo que ejecuta el binario de pumba dentro de 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>

Consejo: Para caos de red en contenedores sin tc/iptables, usa --tc-image para desplegar 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>

Ejecutar 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"

Imágenes Docker

Las imágenes se compilan de forma nativa para linux/amd64 y linux/arm64 (sin QEMU).

Documentación

Demo

Comunidad y soporte

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

Licencia

Apache License 2.0