alexei-led/pumba컨테이너용 카오스 테스팅, 네트워크 에뮬레이션 및 스트레스 테스팅 도구
Docker, containerd 및 Podman을 위한 카오스 테스팅 도구
빠른 시작 · 사용자 가이드 · 네트워크 카오스 · 배포 · 기여
Pumba는 Docker, containerd 및 Podman 컨테이너를 위한 카오스 테스팅 및 네트워크 에뮬레이션 도구입니다. Netflix Chaos Monkey에서 영감을 받은 Pumba는 카오스 엔지니어링을 컨테이너 수준으로 가져옵니다 — 컨테이너를 kill, stop, pause, remove하고, 네트워크 지연과 패킷 손실을 주입하거나, 컨테이너 리소스에 스트레스 테스트를 수행할 수 있습니다.
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]
Windows는 의도적으로 빌드되지 않습니다. 카오스 프리미티브 — Linux netns/cgroup 쓰기, tc/iptables 사이드카 주입, POSIX 신호 전달(SIGCONT/SIGSTOP/SIGUSR1/SIGUSR2, containerd 런타임에서 사용) — 은 Windows에 해당하는 기능이 없습니다. Docker Desktop의 WSL2 백엔드를 사용하더라도 Windows에서의 타당한 사용 사례가 없으므로 Windows 바이너리는 게시되지 않습니다. Windows 지원을 추가하는 PR은 수락되지 않습니다. Linux(네이티브, 컨테이너 또는 VM)에서 pumba를 실행하세요.
자신의 플랫폼에 맞는 최신 릴리스를 다운로드하거나 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 읽기), podman machine VM 내부에서 pumba 바이너리를 실행하세요:
# 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 | 루트 또는 소켓 접근 권한으로 동작 | 기본 런타임. |
| containerd | /run/containerd/containerd.sock | 루트 권한 필요(사이드카용 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 네임스페이스(k8s.io는 Kubernetes, moby는 Docker) |
--podman-socket | (자동 감지) | Podman 소켓 URI(예: unix:///run/podman/podman.sock); 비어 있으면 자동 감지 |
| 문서 | 설명 |
|---|
| 사용자 가이드 | 컨테이너 카오스 명령, 대상 지정, 스케줄링, 구성 |
| 네트워크 카오스 | netem, iptables, 고급 시나리오, 아키텍처 다이어그램 |
| 스트레스 테스트 | stress-ng를 사용한 CPU/메모리/IO 스트레스 테스트 |
| 배포 | Docker, Kubernetes DaemonSets, OpenShift |
| 기여 | 소스에서 빌드, 테스트 실행, 프로젝트 구조 |