alexei-led/pumbaコンテナ向けカオステスト、ネットワークエミュレーション、およびストレステストツール
Docker、containerd、Podman 向けのカオステストツール
クイックスタート · ユーザーガイド · ネットワークカオス · デプロイメント · コントリビューション
Pumba は、Docker、containerd、Podman コンテナ向けのカオステストおよびネットワークエミュレーションツールです。Netflix Chaos Monkey に触発された Pumba は、カオスエンジニアリングをコンテナレベルにもたらします。コンテナの kill、stop、pause、削除、ネットワーク遅延やパケットロスの注入、コンテナリソースのストレステストが可能です。
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]
Pumba は Linux コンテナ を対象としています。すべてのカオスアクションは Linux のプリミティブ（netns、cgroups v2、iptables、tc qdisc、コンテナランタイムソケット）に依存します。リリース済みバイナリ:
Windows は意図的にビルドされていません。 カオスのプリミティブ — Linux の netns/cgroup への書き込み、tc/iptables サイドカー注入、POSIX シグナル転送（containerd ランタイムが使用する SIGCONT/SIGSTOP/SIGUSR1/SIGUSR2）— には Windows 版が存在しません。Docker Desktop の WSL2 バックエンドを使っても Windows で利用する合理的なユースケースはないため、Windows バイナリは公開されていません。Windows サポートを追加する PR は受け付けられません。pumba は Linux（ネイティブ、コンテナ、または VM）で実行してください。
お使いのプラットフォーム向けの 最新リリース をダウンロードするか、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
# 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
# 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>
Pumba は、Docker 互換ソケットを介して Podman と通信します。--podman-socket はオプションです。空の場合、pumba は $CONTAINER_HOST、$PODMAN_SOCK、podman machine inspect、/run/podman/podman.sock、$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、stress は rootful Podman を必要とします。rootless の場合は、podman machine set --rootful（macOS）または rootful systemd ユニット（Linux）を示す明確なメッセージとともに即座に失敗します。
macOS 上の Podman は Linux VM 内で実行されます。Pumba は対象コンテナと同じカーネル上で実行する必要があるため（ホスト側の /proc/<pid>/cgroup 読み取り）、pumba バイナリを podman machine VM 内で実行してください:
# 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>
ヒント:
tc/iptablesを持たないコンテナでネットワークカオスを行うには、--tc-imageを使用してサイドカーを起動してください:pumba --runtime containerd netem --tc-image ghcr.io/alexei-led/pumba-alpine-nettools:latest \ --duration 5m delay --time 3000 <container-id>
docker run -it --rm \
-v /var/run/docker.sock:/var/run/docker.sock \
ghcr.io/alexei-led/pumba --interval=10s --random kill "re2:^test"
| レジストリ | イメージ | ステータス |
|---|---|---|
| GitHub Container Registry | ghcr.io/alexei-led/pumba | ✅ プライマリ |
| Docker Hub | alexeiled/pumba | ⚠️ 非推奨 |
イメージは linux/amd64 と linux/arm64 向けにネイティブビルドされています（QEMU 不使用）。
| ランタイム | ソケット（デフォルト） | netem / iptables / stress | 備考 |
|---|
| Docker | /var/run/docker.sock | root またはソケットアクセスで動作 | デフォルトのランタイム。 |
| containerd | /run/containerd/containerd.sock | root が必要（サイドカーの overlayfs マウント） | 名前空間: k8s.io（Kubernetes）、moby（Docker 管理）、default（純粋な containerd）。 |
| Podman | /run/podman/podman.sock（rootful） | rootful Podman が必要（それ以外は即エラー終了） | Podman の Docker 互換 API を使用。macOS では pumba は podman machine 内で実行される（下記参照）。 |
| OS | amd64 | arm64 | 備考 |
|---|
| Linux | ✅ | ✅ | プライマリターゲット。対象コンテナと同じカーネル上で pumba を実行してください。 |
| macOS | ✅ | ✅ | 開発者向けの利便性のみ。リモートの Docker/Podman/containerd VM（例: Colima、podman machine）を操作するために使用します。 |
| Windows | ❌ | ❌ | サポート対象外であり、計画もありません。 下記参照。 |
| カテゴリ | コマンド | 説明 |
|---|
| コンテナカオス | kill, stop, pause, rm, restart | コンテナのライフサイクルを妨害 |
| 実行 | exec | コンテナ内でコマンドを実行 |
| ネットワーク遅延 | netem delay | 送信トラフィックに遅延を追加 |
| パケットロス | netem loss, iptables loss | パケットをドロップ（送信および受信） |
| ネットワーク効果 | netem duplicate, corrupt, rate | パケットの複製、破損、またはレート制限 |
| ストレステスト | stress | stress-ng による CPU、メモリ、I/O ストレス（子 cgroup または同一 cgroup への注入） |
| ターゲティング | names、regex（re2:）、labels、--random | 柔軟なコンテナ選択 |
| スケジューリング | --interval | 固定間隔でカオスを繰り返し実行 |
| フラグ | デフォルト | 説明 |
|---|
--runtime | docker | コンテナランタイム（docker、containerd、または podman） |
--containerd-socket | /run/containerd/containerd.sock | containerd ソケットのパス |
--containerd-namespace | k8s.io | containerd 名前空間（Kubernetes では k8s.io、Docker では moby） |
--podman-socket | (自動検出) | Podman ソケット URI（例: unix:///run/podman/podman.sock）。空の場合は自動検出 |
| ドキュメント | 説明 |
|---|
| ユーザーガイド | コンテナカオスコマンド、ターゲティング、スケジューリング、設定 |
| ネットワークカオス | netem、iptables、高度なシナリオ、アーキテクチャ図 |
| ストレステスト | stress-ng による CPU/メモリ/I/O ストレステスト |
| デプロイメント | Docker、Kubernetes DaemonSet、OpenShift |
| コントリビューション | ソースからのビルド、テストの実行、プロジェクト構成 |