### Podman Machine Setup and Usage

Source: https://github.com/alexei-led/pumba/blob/master/docs/guide.md

Initial setup for Podman machine on macOS, including installing Podman, initializing a rootful machine, and copying/installing Pumba within the VM for direct execution.

```bash
# one-time setup
brew install podman
podman machine init --rootful --cpus 4 --memory 4096 --now

# copy a linux/arm64 or linux/amd64 pumba binary into the VM
podman machine cp /path/to/pumba podman-machine-default:/tmp/pumba
podman machine ssh sudo install -m 0755 /tmp/pumba /usr/local/bin/pumba

# 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>
```

--------------------------------

### Pumba Quick Start Examples

Source: https://github.com/alexei-led/pumba/blob/master/README.md

Demonstrates basic Pumba commands for killing containers, adding network delay, dropping packets, and stressing CPU.

```bash
# 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
```

--------------------------------

### Example: Kill Containers by Pattern with Docker

Source: https://github.com/alexei-led/pumba/blob/master/docs/deployment.md

This example first starts 10 test containers and then uses Pumba to kill containers matching the 're2:^test' pattern every 10 seconds. It requires Docker socket access.

```bash
# Start some test containers
for i in $(seq 1 10); do docker run -d --name test_$i --rm alpine tail -f /dev/null; done

# Kill matching containers every 10 seconds
docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock 
    ghcr.io/alexei-led/pumba 
    --interval=10s --random --log-level=info 
    kill --signal=SIGKILL "re2:^test"
```

--------------------------------

### Update Main Application Initialization

Source: https://github.com/alexei-led/pumba/blob/master/docs/plans/completed/20260426-modularity-refactor.md

Adjusts the main application setup to accept and propagate the 'chaos.Runtime' dependency to command initializers.

```go
initializeCLICommands(runtime chaos.Runtime)
```

--------------------------------

### Combined Stress Example

Source: https://github.com/alexei-led/pumba/blob/master/docs/stress-testing.md

Simultaneously stress CPU and memory for 5 minutes on 'myapp'. This example combines multiple stress-ng options for comprehensive resource testing.

```bash
pumba stress --duration 5m \
    --stressors="--cpu 2 --vm 1 --vm-bytes 128M --timeout 300s" \
    myapp
```

--------------------------------

### Install Pumba Binary

Source: https://github.com/alexei-led/pumba/blob/master/README.md

Download the Pumba binary for Linux and make it executable.

```bash
curl -sL https://github.com/alexei-led/pumba/releases/latest/download/pumba_linux_amd64 -o pumba
chmod +x pumba
```

--------------------------------

### Update CLAUDE.md Code Conventions Example

Source: https://github.com/alexei-led/pumba/blob/master/docs/plans/completed/20260427-modularity-refactor.md

This example demonstrates the updated mockery syntax for NetemContainer, reflecting constructor injection and the use of *NetemRequest/*IPTablesRequest mock-literals.

```go
EXPECT().NetemContainer(ctx, container.NetemRequest{...})
```

--------------------------------

### Example Pumba Test Case

Source: https://github.com/alexei-led/pumba/blob/master/tests/README.md

An example test case demonstrating how to create a container, run Pumba commands against it, and assert the expected outcomes.

```bash
@test "Should do something specific" {
    # Given (some precondition)
    create_test_container "test_container"

    # When (some action is performed)
    run pumba some_command test_container

    # Then (expected outcome)
    [ $status -eq 0 ]

    # And (more assertions)
    run docker inspect -f {{.State.Status}} test_container
    [ "$output" = "expected_status" ]
}
```

--------------------------------

### Option A: Pass through *cli.Context Metadata

Source: https://github.com/alexei-led/pumba/blob/master/docs/modularity-review/2026-04-25/modularity-review.md

This option demonstrates how to pass the runtime client through the `*cli.Context`'s metadata. It requires modifying the main application setup and introducing a helper function to retrieve the client.

```go
// cmd/main.go
app.Metadata = map[string]any{"runtime": client}
```

```go
// pkg/chaos/command.go
func RuntimeFrom(c *cli.Context) container.Client {
    return c.App.Metadata["runtime"].(container.Client)
}
```

```go
// pkg/chaos/docker/cmd/stop.go
client := chaos.RuntimeFrom(c)
stopCommand := docker.NewStopCommand(client, params, restart, duration, waitTime, limit)
```

--------------------------------

### Install Pumba Binary and Run as Docker Container

Source: https://context7.com/alexei-led/pumba/llms.txt

Download the Pumba binary for Linux or run it directly as a Docker container by mounting the Docker socket.

```bash
# Download binary (Linux amd64)
curl -sL https://github.com/alexei-led/pumba/releases/latest/download/pumba_linux_amd64 -o pumba
chmod +x pumba

# Run as Docker container (mounts Docker socket)
docker run -it --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/alexei-led/pumba --help

# Pull the image
docker pull ghcr.io/alexei-led/pumba:latest
```

--------------------------------

### Podman macOS Development Setup

Source: https://github.com/alexei-led/pumba/blob/master/README.md

Instructions for setting up Pumba for development on macOS using Podman, which involves running Pumba inside the Podman VM.

```bash
# 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/
```

--------------------------------

### I/O Stress Example

Source: https://github.com/alexei-led/pumba/blob/master/docs/stress-testing.md

Stress 4 I/O workers for 30 seconds on 'myapp'. Configure the number of I/O workers and duration according to your I/O subsystem testing requirements.

```bash
pumba stress --duration 30s \
    --stressors="--io 4 --timeout 30s" \
    myapp
```

--------------------------------

### Install Pumba Docker Image

Source: https://github.com/alexei-led/pumba/blob/master/README.md

Pull the latest Pumba Docker image for use.

```bash
docker pull ghcr.io/alexei-led/pumba:latest
```

--------------------------------

### Pumba Test Setup and Teardown

Source: https://github.com/alexei-led/pumba/blob/master/tests/README.md

Defines setup and teardown functions for Pumba tests, ensuring containers are cleaned up before and after test runs.

```bash
setup() {
    # Clean any leftover containers from previous test runs
    cleanup_containers "test_pattern"
}

teardown() {
    # Clean up containers after each test
    cleanup_containers "test_pattern"
}
```

--------------------------------

### Pumba with Containerd Runtime

Source: https://github.com/alexei-led/pumba/blob/master/README.md

Examples of using Pumba with the Containerd runtime to kill containers or add network delay.

```bash
# 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>
```

--------------------------------

### CPU Stress Example

Source: https://github.com/alexei-led/pumba/blob/master/docs/stress-testing.md

Stress 4 CPU workers for 60 seconds on a container named 'myapp'. Ensure the duration and timeout values are appropriate for your testing needs.

```bash
pumba stress --duration 60s \
    --stressors="--cpu 4 --timeout 60s" \
    myapp
```

--------------------------------

### Pumba with Podman Runtime

Source: https://github.com/alexei-led/pumba/blob/master/README.md

Examples of using Pumba with Podman, including auto-detection of the socket and explicit socket override. Note: netem, iptables, and stress require rootful Podman.

```bash
# 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
```

--------------------------------

### Kubernetes Demo: Network Delay and Process Pause with Pumba

Source: https://github.com/alexei-led/pumba/blob/master/examples/README.md

This example shows how to apply network delay and process pausing chaos to Pods in a Kubernetes environment using Pumba. It involves deploying two interactive Pods and a Pumba DaemonSet.

```bash
./k8s_pause_demo.sh
```

```bash
./k8s_delay_demo.sh
```

--------------------------------

### Memory Stress Example

Source: https://github.com/alexei-led/pumba/blob/master/docs/stress-testing.md

Stress 2 memory workers, each allocating 256MB, for 2 minutes on 'myapp'. Adjust VM count and byte allocation based on available memory.

```bash
pumba stress --duration 2m \
    --stressors="--vm 2 --vm-bytes 256M --timeout 120s" \
    myapp
```

--------------------------------

### Basic Bats Test Structure

Source: https://github.com/alexei-led/pumba/blob/master/tests/README.md

A minimal example demonstrating the basic structure of a bats test file, including the shebang and test definitions.

```bash
#!/usr/bin/env bats

```

--------------------------------

### Lint and Format Pumba Code

Source: https://github.com/alexei-led/pumba/blob/master/CONTRIBUTING.md

Run golangci-lint for code linting and `make fmt` for code formatting. The lint command will install golangci-lint if it's not already present.

```sh
# Run golangci-lint (installs if needed)
make lint

# Format code
make fmt
```

--------------------------------

### Multiple Containers Stress Example

Source: https://github.com/alexei-led/pumba/blob/master/docs/stress-testing.md

Stress all containers whose names start with 'worker' for 30 seconds. This command targets multiple containers matching a regular expression.

```bash
pumba stress --duration 30s \
    --stressors="--cpu 2 --timeout 30s" \
    "re2:^worker"
```

--------------------------------

### Option A: Pass through *cli.Context Metadata

Source: https://github.com/alexei-led/pumba/blob/master/docs/modularity-review/2026-04-25/modularity-review.html

Demonstrates how to pass runtime client information via CLI context metadata. This approach avoids constructor signature changes but uses `*cli.Context` as a service locator.

```go
app.Metadata = map[string]any{"runtime": client}
```

```go
func RuntimeFrom(c *cli.Context) container.Client {
    return c.App.Metadata["runtime"].(container.Client)
}
```

```go
client := chaos.RuntimeFrom(c)
stopCommand := docker.NewStopCommand(client, params, restart, duration, waitTime, limit)
```

--------------------------------

### Delay Network Traffic via Podman with Pumba

Source: https://github.com/alexei-led/pumba/blob/master/examples/README.md

Apply network latency to a Podman container using Pumba. This example starts a target container and then uses a Pumba script to introduce delays.

```dockerfile
podman run -d --name ping-target --privileged nicolaka/netshoot sh -c "ping 1.1.1.1"
```

```bash
./pumba_podman_delay.sh
```

--------------------------------

### CLI Context Usage in Main Application Logic

Source: https://github.com/alexei-led/pumba/blob/master/docs/modularity-review/2026-04-27/modularity-review.html

Demonstrates direct usage of `*cli.Context` methods like `GlobalString` and `GlobalBool` in the main application entry point, bypassing a dedicated adapter.

```go
before(c *cli.Context)
createRuntimeClient(c *cli.Context)
globalFlags(rootCertPath string)

c.GlobalString
c.GlobalBool
cli.StringFlag{}
```

--------------------------------

### Podman Client Implementation

Source: https://github.com/alexei-led/pumba/blob/master/docs/plans/completed/20260422-podman-runtime-support.md

Defines the Podman client structure and implements the NewClient function to establish a connection to the Podman API, detecting rootless mode.

```go
type podmanClient struct { ctr.Client; api *dockerapi.Client; rootless bool; socketURI string }
```

```go
func NewClient(explicitSocket string) (ctr.Client, error) {
	// resolve socket, construct SDK via docker.NewAPIClient, wrap as delegate via docker.NewFromAPI, query /info to detect rootless, return &podmanClient{Client: delegate, api: api, rootless: rootless, socketURI: uri}
}
```

```go
func (p *podmanClient) Close() error {
	return p.api.Close()
}
```

```go
func (p *podmanClient) NetemContainer(ctx context.Context, c *ctr.Container, netem *net.Netem, duration time.Duration, pause bool) error {
	if p.rootless {
		return rootlessError("netem", p.socketURI)
	}
	return p.Client.NetemContainer(ctx, c, netem, duration, pause)
}
```

```go
func (p *podmanClient) StopNetemContainer(ctx context.Context, c *ctr.Container) error {
	if p.rootless {
		return rootlessError("stop-netem", p.socketURI)
	}
	return p.Client.StopNetemContainer(ctx, c)
}
```

```go
func (p *podmanClient) IPTablesContainer(ctx context.Context, c *ctr.Container, ipt *net.IPTables, duration time.Duration, pause bool) error {
	if p.rootless {
		return rootlessError("iptables", p.socketURI)
	}
	return p.Client.IPTablesContainer(ctx, c, ipt, duration, pause)
}
```

```go
func (p *podmanClient) StopIPTablesContainer(ctx context.Context, c *ctr.Container) error {
	if p.rootless {
		return rootlessError("stop-iptables", p.socketURI)
	}
	return p.Client.StopIPTablesContainer(ctx, c)
}
```

--------------------------------

### Docker Client File Structure Recommendation

Source: https://github.com/alexei-led/pumba/blob/master/docs/modularity-review/2026-04-25/modularity-review.md

Proposed file structure for splitting the monolithic docker.go file into smaller, single-responsibility files. This aims to reduce agent context window size and improve code organization.

```go
pkg/runtime/docker/
  client.go        — NewClient, NewAPIClient, NewFromAPI, struct, Close
  inspect.go       — dockerInspectToContainer, ListContainers
  lifecycle.go     — Start/Stop/Kill/Restart/Remove/Pause/Unpause/StopContainerWithID
  exec.go          — ExecContainer + execOnContainer + runExecAttached
  netem.go         — NetemContainer, StopNetemContainer, tc helpers, removeSidecar
  iptables.go      — IPTablesContainer + helpers (currently //nolint:dupl twin of netem)
  stress.go        — StressContainer + cgroup resolution + driver detection
  pull.go          — pullImage + imagePullResponse JSON
```

--------------------------------

### Build Pumba with Docker

Source: https://github.com/alexei-led/pumba/blob/master/CONTRIBUTING.md

Build a Docker image for Pumba without requiring a local Go installation. This is useful for CI/CD pipelines or environments without Go.

```sh
DOCKER_BUILDKIT=1 docker build -t pumba -f docker/Dockerfile .
```

--------------------------------

### Build Pumba Binary

Source: https://github.com/alexei-led/pumba/blob/master/CLAUDE.md

Builds the Pumba binary for the current operating system and architecture. Use 'make all' for the full pipeline including formatting, linting, and testing.

```bash
make build
```

```bash
make all
```

--------------------------------

### Update Delay Parameters Parsing

Source: https://github.com/alexei-led/pumba/blob/master/docs/plans/completed/20260427-modularity-followups.md

Example of how a specific Netem action parser (`parseDelayParams`) is updated to use the `ParseRequestBase` helper. It augments the base request with action-specific fields.

```go
func parseDelayParams(c cliflags.Flags, gp *chaos.GlobalParams) (DelayParams, error) {
    base, err := netem.ParseRequestBase(c, gp)
    if err != nil { return DelayParams{}, err }
    base.Command = []string{"delay", fmt.Sprintf("%dms", time), ...}
    return DelayParams{Base: base, Limit: c.Int("limit")}, nil
}
```

--------------------------------

### Recurring Stress Example

Source: https://github.com/alexei-led/pumba/blob/master/docs/stress-testing.md

Run stress tests every 10 minutes against a random container matching the regex '^api'. This is useful for continuous stress testing in dynamic environments.

```bash
pumba --interval 10m --random stress --duration 60s \
    --stressors="--cpu 2 --timeout 60s" \
    "re2:^api"
```

--------------------------------

### Twitter/X Thread - Tweet 2 (Landmine #1)

Source: https://github.com/alexei-led/pumba/blob/master/docs/release-promo-1.1.0.md

Details the first compatibility issue: `ContainerExecStart` behavior differs between Docker and Podman.

```text
Landmine #1: ContainerExecStart.

  Docker: accepts ExecStartOptions{} — no attach, no detach. Works.
  Podman: rejects it. "must provide at least one stream to attach to."

One API. Four call sites. ~60 mock tests. Same SDK, different answer.
```

--------------------------------

### Simulate Asymmetric Network Conditions

Source: https://github.com/alexei-led/pumba/blob/master/docs/network-chaos.md

Apply different network conditions for uploads and downloads. Use `&` to run commands concurrently.

```bash
# Slow uploads: 500ms delay on outgoing traffic
pumba netem --tc-image ghcr.io/alexei-led/pumba-alpine-nettools:latest \
    --duration 5m delay --time 500 --jitter 50 myapp &

# Unreliable downloads: 10% loss on incoming traffic
pumba iptables --iptables-image ghcr.io/alexei-led/pumba-alpine-nettools:latest \
    --duration 5m loss --probability 0.1 myapp &
```

--------------------------------

### Pumba Network Chaos with Sidecar

Source: https://github.com/alexei-led/pumba/blob/master/README.md

Inject network latency using `netem` when the target container lacks `tc` or `iptables`. This example uses a sidecar container for network manipulation.

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

--------------------------------

### Docker.go File Split

Source: https://github.com/alexei-led/pumba/blob/master/docs/plans/completed/20260426-modularity-refactor.md

Illustrates the file structure after splitting `pkg/runtime/docker/docker.go` into multiple cohesive files based on existing sub-interfaces. This change has no impact on the public surface or consumer imports.

```go
pkg/runtime/docker/
  client.go    — NewClient, NewAPIClient, NewFromAPI, dockerClient struct, Close
  inspect.go   — dockerInspectToContainer, ListContainers (and listContainers)
  lifecycle.go — Start/Stop/Kill/Restart/Remove/Pause/Unpause, StopContainerWithID, waitForStop
  exec.go      — ExecContainer, execOnContainer, runExecAttached
  sidecar.go   — removeSidecar, sidecarRemoveTimeout (shared by netem/iptables/stress)
  netem.go     — NetemContainer, StopNetemContainer, tc helpers
  iptables.go  — IPTablesContainer, StopIPTablesContainer, helpers
  stress.go    — StressContainer + stressContainerConfig + stressContainerCommand
  cgroup.go    — cgroupDriver, containerLeafCgroup, defaultCgroupParent, inspectCgroupParent, stressResolveDriver
  pull.go      — pullImage, imagePullResponse JSON
```

--------------------------------

### Configure Advanced Packet Delay

Source: https://github.com/alexei-led/pumba/blob/master/docs/network-chaos.md

Configure a more complex delay with jitter and correlation on a specific network interface. This example targets traffic matching the regex "^test".

```bash
# Add 3000ms ± 30ms delay with 20% correlation on eth1
pumba netem --duration 5m --interface eth1 delay \
    --time 3000 --jitter 30 --correlation 20 "re2:^test"
```

--------------------------------

### Implement urfave/cli v1 Adapter

Source: https://github.com/alexei-led/pumba/blob/master/docs/plans/completed/20260426-modularity-refactor.md

Provides an adapter for the urfave/cli v1 library, mapping its context to the defined Flags interface. This is a partial implementation.

```go
type V1 struct{ ctx *cli.Context }
func (f V1) String(n string) string { return f.ctx.String(n) }
// ... etc
```

--------------------------------

### Kubernetes DaemonSet Node Selection

Source: https://github.com/alexei-led/pumba/blob/master/docs/deployment.md

Configure node selection for Pumba DaemonSets using `nodeSelector`. This example shows how to target specific node groups on EKS or node pools on GKE.

```yaml
spec:
  template:
    spec:
      # EKS node group
      nodeSelector:
        alpha.eksctl.io/nodegroup-name: my-node-group
      # Or GKE node pool
      # nodeSelector:
      #   cloud.google.com/gke-nodepool: node-pool
```

--------------------------------

### Run Unit Tests

Source: https://github.com/alexei-led/pumba/blob/master/CLAUDE.md

Executes unit tests. Requires CGO_ENABLED=1 for the race detector. For tests without the race detector or CGO toolchain, use 'CGO_ENABLED=0 go test ./...'.

```bash
make test
```

```bash
CGO_ENABLED=0 go test ./...
```

--------------------------------

### Containerd Runtime Deployment on Kubernetes

Source: https://github.com/alexei-led/pumba/blob/master/docs/deployment.md

Configure Pumba to target containerd directly on modern Kubernetes clusters. This setup requires mounting the containerd socket and specifies Kubernetes namespace for container resolution.

```yaml
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: pumba-containerd
  namespace: pumba
spec:
  selector:
    matchLabels:
      app: pumba
  template:
    metadata:
      labels:
        app: pumba
    spec:
      hostPID: true # needed for sidecar network namespace sharing
      containers:
        - name: pumba
          image: ghcr.io/alexei-led/pumba
          args:
            - --runtime
            - containerd
            - --containerd-socket
            - /run/containerd/containerd.sock
            - --containerd-namespace
            - k8s.io
            - --log-level
            - info
            - --label
            - io.kubernetes.pod.name=target-pod
            - --interval
            - 30s
            - netem
            - --duration
            - 20s
            - --tc-image
            - ghcr.io/alexei-led/pumba-alpine-nettools:latest
            - delay
            - --time
            - "3000"
          securityContext:
            privileged: true
          volumeMounts:
            - name: containerd-socket
              mountPath: /run/containerd/containerd.sock
      volumes:
        - name: containerd-socket
          hostPath:
            path: /run/containerd/containerd.sock
```

--------------------------------

### Generic Action Builder for CLI Commands

Source: https://github.com/alexei-led/pumba/blob/master/docs/modularity-review/2026-04-25/modularity-review.md

This generic builder simplifies the creation of CLI commands by abstracting common parsing and building logic. It requires Go 1.21+ and is useful for reducing boilerplate in command definitions.

```go
package chaos

import (
	"context"

	"github.com/urfave/cli"
	"github.com/alexei-led/pumba/pkg/chaos"
	"github.com/alexei-led/pumba/pkg/chaos/container"
)

type ParamParser[P any] func(c *cli.Context, gp *chaos.GlobalParams) (P, error)
type CommandFactory[P any] func(client container.Client, gp *chaos.GlobalParams, p P) (chaos.Command, error)

func NewAction[P any](
	ctx context.Context,
	name string,
	flags []cli.Flag,
	parse ParamParser[P],
	build CommandFactory[P],
) *cli.Command {
	return &cli.Command{
		Name:  name,
		Flags: flags,
		Action: func(c *cli.Context) error {
			gp, err := chaos.ParseGlobalParams(c)
			if err != nil { return err }
			p, err := parse(c, gp)
			if err != nil { return err }
			cmd, err := build(chaos.RuntimeFrom(c), gp, p)
			if err != nil { return err }
			return chaos.RunChaosCommand(ctx, cmd, gp)
		},
	}
}
```

--------------------------------

### Simplify Action Run Method with Helper in Go

Source: https://github.com/alexei-led/pumba/blob/master/docs/modularity-review/2026-04-27/modularity-review.md

This Go method demonstrates how to use the `RunOnContainers` helper to execute a specific action on containers. It reduces the boilerplate code for actions by delegating the execution logic.

```go
func (n *delayCommand) Run(ctx context.Context, random bool) error {
    netemCmd := n.buildNetemCmd()
    return chaos.RunOnContainers(ctx, n.client, n.gp, n.limit, random, true,
        func(ctx context.Context, c *container.Container) error {
            req := *n.req
            req.Container = c
            req.Command = netemCmd
            return runNetem(ctx, n.client, &req)
        })
}
```

--------------------------------

### Drop packets using sidecar image

Source: https://context7.com/alexei-led/pumba/llms.txt

Simulates packet loss using a sidecar image containing network tools, useful when the target container does not have 'tc' installed. This ensures packet loss can be injected.

```bash
pumba netem \
    --tc-image ghcr.io/alexei-led/pumba-alpine-nettools:latest \
    --duration 10m \
    loss --percent 15 "re2:^service"
```

--------------------------------

### Deploy Pumba as a Kubernetes DaemonSet

Source: https://context7.com/alexei-led/pumba/llms.txt

Deploy Pumba using Kubernetes manifests to run chaos experiments continuously across all nodes in a cluster. Includes examples for general Pumba deployment and specific stress testing configurations.

```bash
kubectl create -f deploy/pumba_kube.yml
```

```bash
kubectl create -f deploy/pumba_kube_stress.yml
```

--------------------------------

### Run All Integration Tests Including Stress Tests with Make

Source: https://github.com/alexei-led/pumba/blob/master/tests/README.md

Build the Docker test image and execute all Pumba integration tests, including stress tests, using the make command.

```bash
make integration-tests-all
```

--------------------------------

### Original netem delay command implementation

Source: https://github.com/alexei-led/pumba/blob/master/docs/plans/completed/20260427-modularity-followup-2.md

This snippet shows the original implementation of the netem delay command's `Run` method before refactoring. It includes manual handling of container listing, error aggregation, and concurrent execution using `sync.WaitGroup`.

```go
func (n *delayCommand) Run(ctx context.Context, random bool) error {
    log.Debug(...)
    log.WithFields(...).Debug("listing matching containers")
    containers, err := container.ListNContainers(...)
    if err != nil { ... }
    if len(containers) == 0 { ... }
    if random { ... }
    netemCmd := []string{...}
    var wg sync.WaitGroup
    errs := make([]error, len(containers))
    for i, c := range containers {
        wg.Add(1)
        go func(i int, c *container.Container) { ... }(i, c)
    }
    wg.Wait()
    for _, err := range errs { ... }
    return nil
}
```

--------------------------------

### Run Pumba with Docker

Source: https://github.com/alexei-led/pumba/blob/master/README.md

Execute Pumba as a Docker container, mounting the Docker socket to allow Pumba to interact with the Docker daemon. This example targets containers with names matching the regex "re2:^test" for a kill event.

```bash
docker run -it --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/alexei-led/pumba --interval=10s --random kill "re2:^test"
```

--------------------------------

### Run Core Integration Tests with Make

Source: https://github.com/alexei-led/pumba/blob/master/tests/README.md

Build the Docker test image and execute the core Pumba integration tests using the make command, typically used in CI environments.

```bash
make integration-tests
```

--------------------------------

### Docker Client File Split

Source: https://github.com/alexei-led/pumba/blob/master/docs/plans/completed/20260427-modularity-refactor.md

Organizes the docker client implementation into separate files based on responsibility. No method signatures or types are changed.

```go
pkg/runtime/docker/
  client.go        — NewClient, NewAPIClient, NewFromAPI, struct, Close
  inspect.go       — dockerInspectToContainer, ListContainers
  lifecycle.go     — Start/Stop/Kill/Restart/Remove/Pause/Unpause/StopContainerWithID
  exec.go          — ExecContainer, execOnContainer, runExecAttached
  netem.go         — NetemContainer, StopNetemContainer, tcContainerCommands, removeSidecar
  iptables.go      — IPTablesContainer, StopIPTablesContainer, ipTablesContainerCommands
  stress.go        — StressContainer, cgroup driver detection, defaultCgroupParent, stressContainerConfig
  pull.go          — pullImage, imagePullResponse
  http_client.go   — (unchanged)
```

--------------------------------

### CLI Integration for Podman Runtime

Source: https://github.com/alexei-led/pumba/blob/master/docs/plans/completed/20260422-podman-runtime-support.md

Adds a 'podman' case to the runtime switch in the command-line interface, enabling the selection of the Podman runtime and its associated socket.

```go
// add "podman" case to the runtime switch in the before-hook
chaos.DockerClient, err = podman.NewClient(c.GlobalString("podman-socket"))
```

```go
// add new cli.StringFlag for podman-socket
cli.StringFlag{Name: "podman-socket", Usage: "..."}
```

```go
// update --runtime flag usage string
// ... include "podman" ...
```

```go
import "github.com/alexei-led/pumba/pkg/runtime/podman"
```

--------------------------------

### Capture Runtime in Before Hook

Source: https://github.com/alexei-led/pumba/blob/master/docs/plans/completed/20260426-modularity-refactor.md

Ensures the runtime client is created and captured early in the application lifecycle, typically within an 'app.Before' hook, for subsequent use by commands.

```go
createRuntimeClient
pass it down
```

--------------------------------

### Simulate Gilbert-Elliot model with state probabilities

Source: https://context7.com/alexei-led/pumba/llms.txt

Applies the Gilbert-Elliot model with specific probabilities for entering bad states and recovering, as well as per-state loss probabilities. This provides fine-grained control over simulated network conditions.

```bash
pumba netem --duration 5m \
    loss-gemodel --pg 5 --pb 90 --one-h 1 --one-k 0 myapp
```

--------------------------------

### Enable JSON Logging

Source: https://github.com/alexei-led/pumba/blob/master/docs/guide.md

Produces JSON-formatted logs compatible with log aggregation tools.

```bash
pumba --json --log-level info kill myapp
```

--------------------------------

### Build Pumba Network Tools Images

Source: https://github.com/alexei-led/pumba/blob/master/docs/network-chaos.md

Commands to build Pumba's network tools images locally or push them to a registry. Pushing to GHCR requires authentication.

```bash
# Build single-arch images for local testing
make build-local-nettools
```

```bash
# Build multi-architecture images locally (doesn't push)
make build-nettools-images
```

```bash
# Build and push to GitHub Container Registry
make push-nettools-images
```

--------------------------------

### Run Advanced Go Integration Tests

Source: https://github.com/alexei-led/pumba/blob/master/CONTRIBUTING.md

Execute advanced Go-based integration tests located in `tests/integration/`. These tests require a running Docker daemon and potentially sudo for containerd tests.

```sh
# Run advanced Go integration tests (requires Docker, sudo for containerd tests)
make integration-tests-advanced
```

--------------------------------

### Generic CLI Command Builder

Source: https://github.com/alexei-led/pumba/blob/master/docs/plans/completed/20260426-modularity-refactor.md

Introduces a generic `NewAction` function in `pkg/chaos/cmd/builder.go` for creating CLI commands. It uses type parameters `P` for parameter parsing and `CommandFactory` for building commands, reducing boilerplate in individual command files.

```go
// pkg/chaos/cmd/builder.go (new)
type ParamParser[P any]    func(c *cli.Context, gp *chaos.GlobalParams) (P, error)
type CommandFactory[P any] func(client container.Client, gp *chaos.GlobalParams, p P) (chaos.Command, error)

func NewAction[P any](
    ctx context.Context,
    runtime chaos.Runtime,
    name, usage string,
    flags []cli.Flag,
    parse ParamParser[P],
    build CommandFactory[P],
) *cli.Command {
    ...
}
```