Skip to content

Commit a5b49c9

Browse files
authored
fix image name (#269)
1 parent 95795d2 commit a5b49c9

13 files changed

+95
-83
lines changed

README.md

+33-24
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
Pumba is a chaos testing command line tool for Docker containers.
44
Pumba disturbs your containers by:
5+
56
- Crashing containerized applications
67
- Emulating network failures (latency, packet loss, etc.)
78
- Manipulating both incoming and outgoing network traffic
@@ -171,7 +172,7 @@ OPTIONS:
171172
--duration value, -d value network emulation duration; should be smaller than recurrent interval; use with optional unit suffix: 'ms/s/m/h'
172173
--interface value, -i value network interface to apply delay on (default: "eth0")
173174
--target value, -t value target IP filter; comma separated. netem will impact only on traffic to target IP(s)
174-
--tc-image value Docker image with tc (iproute2 package); try 'ghcr.io/alexei-led/pumba/pumba-debian-nettools'
175+
--tc-image value Docker image with tc (iproute2 package); try 'ghcr.io/alexei-led/pumba-debian-nettools'
175176
--help, -h show help
176177
```
177178

@@ -363,14 +364,15 @@ pumba netem --duration 5m corrupt --percent 10 mydb
363364
# Using the multi-arch nettools image explicitly
364365
# This is useful when you need to ensure both netem and iptables commands use the same image
365366
366-
pumba netem --tc-image ghcr.io/alexei-led/pumba/pumba-alpine-nettools:latest \
367+
pumba netem --tc-image ghcr.io/alexei-led/pumba-alpine-nettools:latest \
367368
--duration 5m \
368369
delay --time 1000 \
369370
--jitter 100 \
370371
myapp
371372
```
372373

373-
For more examples of combining netem with iptables commands, see the [Advanced Network Chaos Scenarios](#advanced-network-chaos-scenarios) section.
374+
For more examples of combining netem with iptables commands, see the [Advanced Network Chaos Scenarios](#advanced-network-chaos-scenarios)
375+
section.
374376

375377
##### Network Tools Images
376378

@@ -389,24 +391,27 @@ You have two options:
389391

390392
By default, Pumba now uses multi-tool container images that include both `tc` and `iptables` tools:
391393

392-
- `ghcr.io/alexei-led/pumba/pumba-alpine-nettools:latest` - Alpine-based image with both tc and iptables
393-
- `ghcr.io/alexei-led/pumba/pumba-debian-nettools:latest` - Debian-based image with both tc and iptables
394+
- `ghcr.io/alexei-led/pumba-alpine-nettools:latest` - Alpine-based image with both tc and iptables
395+
- `ghcr.io/alexei-led/pumba-debian-nettools:latest` - Debian-based image with both tc and iptables
394396

395397
These images provide several benefits:
398+
396399
- **Efficiency**: Both the `netem` and `iptables` commands can use the same container image
397400
- **Multi-architecture**: Images are built for both `amd64` and `arm64` architectures
398401
- **Command reuse**: A neutral entrypoint keeps the helper container alive between commands
399402

400403
**Usage Example**:
404+
401405
```bash
402406
# Use the same nettools image for both netem and iptables commands
403-
pumba netem --tc-image ghcr.io/alexei-led/pumba/pumba-alpine-nettools:latest delay --time 100 mycontainer
404-
pumba iptables --iptables-image ghcr.io/alexei-led/pumba/pumba-alpine-nettools:latest loss --probability 0.2 mycontainer
407+
pumba netem --tc-image ghcr.io/alexei-led/pumba-alpine-nettools:latest delay --time 100 mycontainer
408+
pumba iptables --iptables-image ghcr.io/alexei-led/pumba-alpine-nettools:latest loss --probability 0.2 mycontainer
405409
```
406410

407411
#### Architecture Support
408412

409413
The nettools images are built for multiple CPU architectures:
414+
410415
- `amd64` (x86_64) - Standard 64-bit Intel/AMD architecture
411416
- `arm64` (aarch64) - 64-bit ARM architecture (Apple M1/M2, AWS Graviton, etc.)
412417

@@ -468,7 +473,7 @@ OPTIONS:
468473
--destination value, --dest value destination IP filter; supports multiple IPs; supports CIDR notation
469474
--src-port value, --sport value source port filter; supports multiple ports (comma-separated)
470475
--dst-port value, --dport value destination port filter; supports multiple ports (comma-separated)
471-
--iptables-image value Docker image with iptables and tc tools (default: "ghcr.io/alexei-led/pumba/pumba-alpine-nettools:latest")
476+
--iptables-image value Docker image with iptables and tc tools (default: "ghcr.io/alexei-led/pumba-alpine-nettools:latest")
472477
--pull-image force pull iptables-image
473478
--help, -h show help
474479
```
@@ -493,7 +498,8 @@ OPTIONS:
493498

494499
#### Using the `iptables` Commands
495500

496-
Pumba's `iptables` command allows you to simulate packet loss for incoming network traffic, with powerful filtering options. This can be used to test application resilience to network issues.
501+
Pumba's `iptables` command allows you to simulate packet loss for incoming network traffic, with powerful filtering options. This can be
502+
used to test application resilience to network issues.
497503

498504
##### Examples
499505

@@ -525,34 +531,36 @@ You have two options:
525531

526532
1. Make sure the target container has the `iptables` tool installed
527533
(install the `iptables` package)
528-
534+
529535
2. Use the `--iptables-image` option to specify a Docker image with
530536
the `iptables` tool.
531-
537+
532538
Pumba will create a helper container from this image with `NET_ADMIN`
533539
capability and reuse the target container's network stack.
534-
540+
535541
The recommended images are:
536-
- `ghcr.io/alexei-led/pumba/pumba-alpine-nettools:latest` (Alpine-based)
537-
- `ghcr.io/alexei-led/pumba/pumba-debian-nettools:latest` (Debian-based)
538-
542+
- `ghcr.io/alexei-led/pumba-alpine-nettools:latest` (Alpine-based)
543+
- `ghcr.io/alexei-led/pumba-debian-nettools:latest` (Debian-based)
544+
539545
Both images support multiple architectures (amd64, arm64).
540546

541547
### Advanced Network Chaos Scenarios
542548

543-
Pumba allows you to create complex and realistic network chaos scenarios by combining multiple network manipulation commands. This is particularly useful for simulating real-world network conditions where multiple issues might occur simultaneously.
549+
Pumba allows you to create complex and realistic network chaos scenarios by combining multiple network manipulation commands. This is
550+
particularly useful for simulating real-world network conditions where multiple issues might occur simultaneously.
544551

545552
#### Asymmetric Network Conditions
546553

547-
In real networks, upload and download speeds/quality often differ. You can simulate this using a combination of `netem` for outgoing traffic and `iptables` for incoming traffic:
554+
In real networks, upload and download speeds/quality often differ. You can simulate this using a combination of `netem` for outgoing traffic
555+
and `iptables` for incoming traffic:
548556

549557
```bash
550558
# Add delay to outgoing traffic (slow uploads)
551-
pumba netem --tc-image ghcr.io/alexei-led/pumba/pumba-alpine-nettools:latest \
559+
pumba netem --tc-image ghcr.io/alexei-led/pumba-alpine-nettools:latest \
552560
--duration 5m delay --time 500 myapp &
553561

554562
# Add packet loss to incoming traffic (unreliable downloads)
555-
pumba iptables --iptables-image ghcr.io/alexei-led/pumba/pumba-alpine-nettools:latest \
563+
pumba iptables --iptables-image ghcr.io/alexei-led/pumba-alpine-nettools:latest \
556564
--duration 5m loss --probability 0.1 myapp &
557565
```
558566

@@ -562,11 +570,11 @@ Test how your application handles multiple concurrent network issues:
562570

563571
```bash
564572
# Limit bandwidth and add packet corruption
565-
pumba netem --tc-image ghcr.io/alexei-led/pumba/pumba-alpine-nettools:latest \
573+
pumba netem --tc-image ghcr.io/alexei-led/pumba-alpine-nettools:latest \
566574
--duration 10m rate --rate 1mbit myapp &
567575

568576
# Add packet loss to incoming traffic
569-
pumba iptables --iptables-image ghcr.io/alexei-led/pumba/pumba-alpine-nettools:latest \
577+
pumba iptables --iptables-image ghcr.io/alexei-led/pumba-alpine-nettools:latest \
570578
--duration 10m loss --probability 0.05 myapp &
571579
```
572580

@@ -576,19 +584,20 @@ Use Pumba to test how your microservices architecture responds to network failur
576584

577585
```bash
578586
# Add high latency between service A and service B
579-
pumba netem --tc-image ghcr.io/alexei-led/pumba/pumba-alpine-nettools:latest \
587+
pumba netem --tc-image ghcr.io/alexei-led/pumba-alpine-nettools:latest \
580588
--target service-b-ip --duration 5m delay --time 2000 --jitter 500 service-a &
581589

582590
# Add packet loss from service B to service C
583-
pumba iptables --iptables-image ghcr.io/alexei-led/pumba/pumba-alpine-nettools:latest \
591+
pumba iptables --iptables-image ghcr.io/alexei-led/pumba-alpine-nettools:latest \
584592
--source service-c-ip --duration 5m loss --probability 0.2 service-b &
585593
```
586594

587595
#### Example Script
588596

589597
You can find a complete example script for combined chaos testing in the [examples directory](examples/pumba_combined.sh).
590598

591-
For detailed guidance on advanced network chaos testing scenarios, best practices, and troubleshooting, see the [Advanced Network Chaos Testing Documentation](docs/advanced-network-chaos.md).
599+
For detailed guidance on advanced network chaos testing scenarios, best practices, and troubleshooting, see
600+
the [Advanced Network Chaos Testing Documentation](docs/advanced-network-chaos.md).
592601

593602
### Stress testing Docker containers
594603

cmd/main.go

+2-2
Original file line numberDiff line numberDiff line change
@@ -310,7 +310,7 @@ func initializeCLICommands() []cli.Command {
310310
cli.StringFlag{
311311
Name: "tc-image",
312312
Usage: "Docker image with tc (iproute2 package) and iptables",
313-
Value: "ghcr.io/alexei-led/pumba/pumba-alpine-nettools:latest",
313+
Value: "ghcr.io/alexei-led/pumba-alpine-nettools:latest",
314314
},
315315
cli.BoolTFlag{
316316
Name: "pull-image",
@@ -366,7 +366,7 @@ func initializeCLICommands() []cli.Command {
366366
cli.StringFlag{
367367
Name: "iptables-image",
368368
Usage: "Docker image with iptables and tc (iproute2 package)",
369-
Value: "ghcr.io/alexei-led/pumba/pumba-alpine-nettools:latest",
369+
Value: "ghcr.io/alexei-led/pumba-alpine-nettools:latest",
370370
},
371371
cli.BoolTFlag{
372372
Name: "pull-image",

deploy/pumba_kube.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@ spec:
6868
- --duration
6969
- 20s
7070
- --tc-image
71-
- ghcr.io/alexei-led/pumba/pumba-debian-nettools
71+
- ghcr.io/alexei-led/pumba-debian-nettools
7272
- delay
7373
- --time
7474
- "3000"

docs/advanced-network-chaos.md

+40-37
Original file line numberDiff line numberDiff line change
@@ -4,20 +4,23 @@ This guide provides detailed instructions for creating advanced network chaos te
44

55
## Overview
66

7-
Pumba now offers support for both outgoing traffic manipulation (using `tc` with `netem`) and incoming traffic manipulation (using `iptables`). By combining these tools, you can create more realistic and complex network chaos scenarios.
7+
Pumba now offers support for both outgoing traffic manipulation (using `tc` with `netem`) and incoming traffic manipulation (using
8+
`iptables`). By combining these tools, you can create more realistic and complex network chaos scenarios.
89

910
![Pumba Network Chaos Testing](img/nettools-diagram.svg)
1011

11-
The diagram above illustrates how Pumba uses a single nettools container to manipulate both incoming traffic (via iptables) and outgoing traffic (via tc/netem) for the target application container.
12+
The diagram above illustrates how Pumba uses a single nettools container to manipulate both incoming traffic (via iptables) and outgoing
13+
traffic (via tc/netem) for the target application container.
1214

1315
## Nettools Images
1416

1517
Pumba uses multi-architecture container images that include both `tc` and `iptables` tools:
1618

17-
- `ghcr.io/alexei-led/pumba/pumba-alpine-nettools:latest` - Alpine-based (smaller size)
18-
- `ghcr.io/alexei-led/pumba/pumba-debian-nettools:latest` - Debian-based (better compatibility)
19+
- `ghcr.io/alexei-led/pumba-alpine-nettools:latest` - Alpine-based (smaller size)
20+
- `ghcr.io/alexei-led/pumba-debian-nettools:latest` - Debian-based (better compatibility)
1921

2022
Both images support:
23+
2124
- amd64 (x86_64) architecture
2225
- arm64 (aarch64) architecture
2326

@@ -29,13 +32,13 @@ In real networks, upload and download characteristics often differ. You can simu
2932

3033
```bash
3134
# Slow uploads: Add 500ms delay to outgoing traffic
32-
pumba netem --tc-image ghcr.io/alexei-led/pumba/pumba-alpine-nettools:latest \
35+
pumba netem --tc-image ghcr.io/alexei-led/pumba-alpine-nettools:latest \
3336
--duration 5m \
3437
delay --time 500 --jitter 50 \
3538
myapp &
3639

3740
# Unreliable downloads: Add 10% packet loss to incoming traffic
38-
pumba iptables --iptables-image ghcr.io/alexei-led/pumba/pumba-alpine-nettools:latest \
41+
pumba iptables --iptables-image ghcr.io/alexei-led/pumba-alpine-nettools:latest \
3942
--duration 5m \
4043
loss --probability 0.1 \
4144
myapp &
@@ -47,13 +50,13 @@ Test how your application handles both bandwidth limitations and occasional pack
4750

4851
```bash
4952
# Limit bandwidth to 1Mbit/s
50-
pumba netem --tc-image ghcr.io/alexei-led/pumba/pumba-alpine-nettools:latest \
53+
pumba netem --tc-image ghcr.io/alexei-led/pumba-alpine-nettools:latest \
5154
--duration 10m \
5255
rate --rate 1mbit \
5356
myapp &
5457

5558
# Add 5% packet loss to incoming traffic
56-
pumba iptables --iptables-image ghcr.io/alexei-led/pumba/pumba-alpine-nettools:latest \
59+
pumba iptables --iptables-image ghcr.io/alexei-led/pumba-alpine-nettools:latest \
5760
--duration 10m \
5861
loss --probability 0.05 \
5962
myapp &
@@ -65,13 +68,13 @@ You can target specific protocols for different types of network chaos:
6568

6669
```bash
6770
# Add latency to all outgoing HTTP traffic
68-
pumba netem --tc-image ghcr.io/alexei-led/pumba/pumba-alpine-nettools:latest \
71+
pumba netem --tc-image ghcr.io/alexei-led/pumba-alpine-nettools:latest \
6972
--duration 15m \
7073
delay --time 200 \
7174
myapp &
7275

7376
# Drop 20% of incoming UDP packets only
74-
pumba iptables --iptables-image ghcr.io/alexei-led/pumba/pumba-alpine-nettools:latest \
77+
pumba iptables --iptables-image ghcr.io/alexei-led/pumba-alpine-nettools:latest \
7578
--duration 15m \
7679
--protocol udp \
7780
loss --probability 0.2 \
@@ -84,14 +87,14 @@ Test how your microservices handle degraded network conditions between specific
8487

8588
```bash
8689
# Add high latency between Service A and Service B
87-
pumba netem --tc-image ghcr.io/alexei-led/pumba/pumba-alpine-nettools:latest \
90+
pumba netem --tc-image ghcr.io/alexei-led/pumba-alpine-nettools:latest \
8891
--target service-b-ip \
8992
--duration 10m \
9093
delay --time 1000 --jitter 200 \
9194
service-a &
9295

9396
# Add packet loss from Service B to Service C
94-
pumba iptables --iptables-image ghcr.io/alexei-led/pumba/pumba-alpine-nettools:latest \
97+
pumba iptables --iptables-image ghcr.io/alexei-led/pumba-alpine-nettools:latest \
9598
--source service-c-ip \
9699
--duration 10m \
97100
loss --probability 0.15 \
@@ -104,14 +107,14 @@ You can target specific ports to simulate more targeted network issues:
104107

105108
```bash
106109
# Add packet corruption to outgoing database traffic (port 5432)
107-
pumba netem --tc-image ghcr.io/alexei-led/pumba/pumba-alpine-nettools:latest \
110+
pumba netem --tc-image ghcr.io/alexei-led/pumba-alpine-nettools:latest \
108111
--target db-server-ip \
109112
--duration 5m \
110113
corrupt --percent 5 \
111114
myapp &
112115

113116
# Add packet loss to incoming HTTP traffic (port 80)
114-
pumba iptables --iptables-image ghcr.io/alexei-led/pumba/pumba-alpine-nettools:latest \
117+
pumba iptables --iptables-image ghcr.io/alexei-led/pumba-alpine-nettools:latest \
115118
--dst-port 80 \
116119
--duration 5m \
117120
loss --probability 0.1 \
@@ -128,29 +131,29 @@ spec:
128131
template:
129132
spec:
130133
containers:
131-
- name: pumba-netem
132-
image: gaiaadm/pumba:latest
133-
args:
134-
- --random
135-
- --interval=30s
136-
- netem
137-
- --tc-image=ghcr.io/alexei-led/pumba/pumba-alpine-nettools:latest
138-
- --duration=5m
139-
- delay
140-
- --time=500
141-
- "re2:app-.*"
142-
- name: pumba-iptables
143-
image: gaiaadm/pumba:latest
144-
args:
145-
- --random
146-
- --interval=30s
147-
- iptables
148-
- --iptables-image=ghcr.io/alexei-led/pumba/pumba-alpine-nettools:latest
149-
- --duration=5m
150-
- --protocol=tcp
151-
- loss
152-
- --probability=0.1
153-
- "re2:app-.*"
134+
- name: pumba-netem
135+
image: gaiaadm/pumba:latest
136+
args:
137+
- --random
138+
- --interval=30s
139+
- netem
140+
- --tc-image=ghcr.io/alexei-led/pumba-alpine-nettools:latest
141+
- --duration=5m
142+
- delay
143+
- --time=500
144+
- "re2:app-.*"
145+
- name: pumba-iptables
146+
image: gaiaadm/pumba:latest
147+
args:
148+
- --random
149+
- --interval=30s
150+
- iptables
151+
- --iptables-image=ghcr.io/alexei-led/pumba-alpine-nettools:latest
152+
- --duration=5m
153+
- --protocol=tcp
154+
- loss
155+
- --probability=0.1
156+
- "re2:app-.*"
154157
```
155158
156159
## Best Practices

examples/pumba_combined.sh

+1-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
# to create more complex and realistic network chaos scenarios.
55

66
# Common image for both commands
7-
NETTOOLS_IMAGE="ghcr.io/alexei-led/pumba/pumba-alpine-nettools:latest"
7+
NETTOOLS_IMAGE="ghcr.io/alexei-led/pumba-alpine-nettools:latest"
88

99
# Pull the image in advance (optional)
1010
docker pull $NETTOOLS_IMAGE

examples/pumba_delay.sh

+1-1
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,4 @@ set -o xtrace
55
pumba netem delay --help
66
read -p "Press enter to continue"
77

8-
pumba --log-level=info --interval=20s netem --tc-image=ghcr.io/alexei-led/pumba/pumba-debian-nettools --duration=10s delay --time=3000 --jitter=20 ping
8+
pumba --log-level=info --interval=20s netem --tc-image=ghcr.io/alexei-led/pumba-debian-nettools --duration=10s delay --time=3000 --jitter=20 ping

examples/pumba_loss.sh

+1-1
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,4 @@ set -o xtrace
55
pumba netem loss --help
66
read -p "Press enter to continue"
77

8-
pumba --log-level=info netem --duration 20s --tc-image ghcr.io/alexei-led/pumba/pumba-debian-nettools --percent 20 client
8+
pumba --log-level=info netem --duration 20s --tc-image ghcr.io/alexei-led/pumba-debian-nettools --percent 20 client

0 commit comments

Comments
 (0)