pumba

Ferramenta de teste de caos para Docker, containerd e Podman

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

---

Pumba é uma ferramenta de teste de caos e emulação de rede para contêineres Docker, containerd e Podman. Inspirada no Netflix Chaos Monkey, o Pumba traz a engenharia do caos para o nível de contêiner — encerre, pare, pause e remova contêineres, injete atrasos de rede e perda de pacotes, ou realize testes de estresse nos recursos do contêiner.

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

Runtime	Socket (padrão)	netem / iptables / stress	Notas
Docker	/var/run/docker.sock	Funciona como root ou com acesso ao socket	Runtime padrão.
containerd	/run/containerd/containerd.sock	Requer root (montagens overlayfs para sidecar)	Namespaces: k8s.io (Kubernetes), moby (gerenciado pelo Docker), default (containerd puro).
Podman	/run/podman/podman.sock (rootful)	Requer Podman rootful (falha rapidamente caso contrário)	Usa a API compatível com Docker do Podman; no macOS o pumba é executado dentro da podman machine (veja abaixo).

Plataformas suportadas

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

SO	amd64	arm64	Notas
Linux	✅	✅	Alvo principal. Execute o pumba no mesmo kernel dos contêineres alvo.
macOS	✅	✅	Apenas ergonomia para desenvolvedores. Use-o para controlar uma VM remota Docker/Podman/containerd (ex.: Colima, podman machine).
Windows	❌	❌	Não suportado e não planejado. Veja abaixo.

O Windows intencionalmente não é compilado. As primitivas de caos — gravações em netns/cgroup 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 adicionando suporte a Windows não serão aceitos; execute o pumba no Linux (nativo, contêiner ou VM).

Recursos

Categoria	Comandos	Descrição
Caos em Contêineres	kill, stop, pause, rm, restart	Interrompe o ciclo de vida do contêiner
Executar	exec	Executa comandos dentro dos contêineres
Atraso de Rede	netem delay	Adiciona latência ao tráfego de saída
Perda de Pacotes	netem loss, iptables loss	Descarta pacotes (saída e entrada)
Efeitos de Rede	netem duplicate, corrupt, rate	Duplica, corrompe ou limita a taxa de pacotes
Efeitos Combinados	netem combine	Aplica múltiplos efeitos em uma única qdisc netem própria
Teste de Estresse	stress	Estresse de CPU, memória e I/O via stress-ng (cgroup filho ou injeção no mesmo cgroup)
Direcionamento	nomes, regex (re2:), labels, --random	Seleção flexível de contêineres; netem/iptables também oferecem --match-all opcional
Agendamento	--interval	Caos recorrente em intervalos fixos
Agentes	schema, --output ndjson	Descrição da CLI como JSON; eventos de resultado no stdout
Verificação de resíduos	status [--check], revert --run-id	Inspeciona falhas e recupera regras/sidecars elegíveis marcados por execução

Início Rápido

Instalação

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

# Combine 100ms delay and 20% packet loss in one qdisc
pumba netem --duration 5m combine --delay --delay-time 100 --loss --loss-percent 20 -- mydb