Slow container network? How to use iperf3 for diagnostics
Learn how to use iperf3 to measure network performance between your Docker microservices. Easily identify bandwidth limits and latency in your virtual networks.
Summary
- iperf3 allows for precise measurement of real bandwidth and latency between two isolated containers.
- Running the tool in server and client modes is the standard for network stress testing in Docker environments.
- Overlay or bridge networks introduce overhead that can be quantified through throughput tests.
- Identifying network bottlenecks helps rule out performance issues unrelated to CPU or RAM limitations.
- Network tests must be performed under controlled conditions to avoid interference from real application traffic.
Understanding container network communication
As your microservices exchange data, the network becomes a critical infrastructure component. In Docker environments, whether using standard Bridge networks or Overlay networks in Swarm or Kubernetes clusters, traffic passes through abstraction layers that can cause hidden bottlenecks. Measuring the efficiency of this communication is crucial before assuming that application code is the cause of latency.
What is iperf3 and why it matters
iperf3 is a command-line tool widely used for measuring network performance, focusing on throughput (data transfer rate over time) and latency. Unlike a simple ping, iperf3 can saturate your bandwidth in a controlled manner, revealing the maximum limit your virtual network infrastructure can handle before it begins dropping packets.
Setting up your test environment
To run the test between containers, you need the utility installed on both sides. If your service images are lightweight (like Alpine), you can install the package manually or use a temporary container attached to the same network. It is effectively like connecting two computers via a cable to measure actual network speed while ignoring high-level application protocols.
Executing the test in practice
The process is straightforward: one container acts as the server waiting for connections, while the other acts as the client sending the traffic. Follow these steps:
- On the server container, start the listener:
iperf3 -s - On the client container, initiate traffic to the server IP:
iperf3 -c <SERVER_IP> - Review the transfer report which displays the bit rate and jitter (latency variation).
If you suspect latency issues beyond bandwidth, as discussed when using tcpdump to troubleshoot network latency and errors, iperf3 can also run UDP tests to measure packet loss instead of just TCP flow.
Interpreting network bottlenecks
If the throughput is lower than expected, check if there are CPU or memory bottlenecks in the containers, as packet encapsulation (especially in Overlay networks) consumes significant processing cycles. If CPU usage hits 100%, the bottleneck is the host, not the network infrastructure itself. To explore these architectural concepts further in production, see our related technical analysis on How to measure capacitor ESR in-circuit without removal.
Final thoughts on network performance
Diagnosing Docker networks is not just about executing commands, but interpreting what the system delivers under stress. Always test in isolated environments so real application traffic doesn't skew your results. By mastering iperf3, you gain the ability to validate whether your infrastructure is ready for scale or requires routing optimizations.