pumba

Ferramenta de teste de caos para Docker, containerd e Podman

Início Rápido · Guia do Usuário · Caos de Rede · Implantação · Contribuição

Pumba é uma ferramenta de teste de caos e emulação de rede para contêineres Docker, containerd e Podman. Inspirado no Netflix Chaos Monkey, o Pumba leva a engenharia do caos ao nível de contêineres — mate, pare, pause e remova contêineres, injete atrasos de rede e perda de pacotes ou teste a resistência dos recursos dos contêineres.

Como 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 suportados

Plataformas suportadas

O Pumba tem como alvo contêineres Linux — toda ação de caos depende de primitivas do Linux (netns, cgroups v2, iptables, qdiscs tc, sockets do runtime de contêiner). Binários publicados:

O Windows não é compilado intencionalmente. As primitivas de caos — gravações em netns/cgroups do Linux, injeção de sidecar tc/iptables, encaminhamento de sinais POSIX (SIGCONT/SIGSTOP/SIGUSR1/SIGUSR2 usados pelo runtime containerd) — não têm equivalente no Windows. Não há caso de uso plausível no Windows, mesmo com o backend WSL2 do Docker Desktop; portanto, nenhum binário para Windows é publicado. PRs que adicionem suporte ao Windows não serão aceitos; execute o pumba no Linux (nativo, contêiner ou VM).

Recursos

Início Rápido

Instalação

Baixe a última versão para sua plataforma ou 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

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

O Pumba se comunica com o Podman por meio do socket compatível com Docker. --podman-socket é opcional — se estiver vazio, o pumba verifica $CONTAINER_HOST, $PODMAN_SOCK, podman machine inspect, /run/podman/podman.sock e $XDG_RUNTIME_DIR/podman/podman.sock, nessa ordem.

# 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 exigem Podman rootful — o modo rootless falha rapidamente com uma mensagem clara apontando para podman machine set --rootful (macOS) ou para a unit systemd rootful (Linux).

Desenvolvimento no macOS com Podman

O Podman no macOS roda dentro de uma VM Linux. O Pumba deve ser executado no mesmo kernel dos contêineres alvo (leitura de /proc/<pid>/cgroup no lado do host); portanto, execute o binário pumba dentro da VM do 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>

Dica: Para caos de rede em contêineres sem tc/iptables, use --tc-image para iniciar um sidecar:

root@kitploit:~

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

Executar com 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"

Imagens Docker

As imagens são compiladas nativamente para linux/amd64 e linux/arm64 (sem QEMU).

Documentação

Demo

Comunidade e Suporte

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

Licença

Apache License 2.0