Docker Networking Guide: Bridge, Host, Macvlan & DNS Explained

Understanding Docker networking is often the steepest part of the container learning curve. Welcome to the ultimate Docker networking guide. In this comprehensive deep dive, we'll strip away the magic and explore exactly how containers communicate with each other, the host operating system, and the outside world. Whether you are debugging a complex microservices architecture, investigating latency, or just trying to figure out why your web app can't reach its database, mastering network drivers is absolutely essential.

Before deploying complex network topologies or running multi-container stacks, it is highly recommended to validate your configurations. You can use our free, privacy-first, browser-only Docker Compose Validator to instantly check your YAML files for syntax and structural errors. Our tool ensures no data is ever uploaded to a server—everything happens securely and locally in your browser.

In this guide, we'll thoroughly explore the default docker bridge network, examine when to utilize the high-performance docker host network, discuss integrating with legacy physical networks using docker macvlan, and unravel the mysteries behind docker container DNS resolution. For a holistic view on connecting these networks via code, also check out our docker compose complete guide.

How Docker Networking Actually Works Under the Hood

Before diving into specific drivers, it is crucial to understand the Linux primitives that Docker leverages. Docker networking isn't magic; it is an elegant orchestration of Linux Network Namespaces, Virtual Ethernet (veth) pairs, and iptables.

When you install Docker, it creates a virtual network interface on your host machine, typically named docker0. A network namespace logically isolates the networking stack (interfaces, routing tables, and firewall rules). Every time you spin up a container, Docker creates a brand new network namespace for it.

To allow the container to talk to the host, Docker uses a veth pair—think of it as a virtual patch cable. One end of the cable is plugged into the container's network namespace (acting as eth0), and the other end is plugged into the docker0 bridge on the host. Traffic destined for the internet routes through the bridge, where host-level NAT (via iptables) translates the container's private IP into the host's public/routable IP.

The Docker Bridge Network: Default but Dangerous?

The docker bridge network is the default network driver. If you run a container without specifying a network, it automatically attaches to the default bridge (docker0). While convenient, relying on the default bridge in production is generally considered a bad practice.

Default Bridge vs. User-Defined Bridge

Docker provides two types of bridge networks: the default bridge network and user-defined bridge networks. The most critical difference between them is how they handle name resolution.

• Default Bridge: Containers can access each other by IP address. If you want them to communicate by container name, you must use the deprecated --link flag.
• User-Defined Bridge: Provides automatic DNS resolution. Containers can seamlessly resolve each other by container name or alias.

Let's create a user-defined bridge network and attach some containers to it:

# Create a user-defined bridge network
docker network create my-app-network

# Run a database container on the network
docker run -d --name db \
  --network my-app-network \
  postgres:15

# Run a web container that connects to the database
docker run -d --name web \
  --network my-app-network \
  -e DB_HOST=db \
  nginx:alpine

In the example above, the web container can seamlessly ping the db container simply by referencing the hostname db. Docker's internal DNS handles the translation from the hostname to the dynamically assigned IP address. Furthermore, user-defined bridges provide better isolation. Containers on the default bridge can see all other containers on the default bridge. By creating custom networks per application stack (e.g., one network for your CRM, one for your blog), you ensure strict microservice segmentation.

The Docker Host Network: Maximum Performance

If your container needs to handle millions of requests per second, the overhead of the bridge network's Network Address Translation (NAT) and port forwarding might become a bottleneck. Enter the docker host network.

When you use the host network driver, Docker does not create a separate network namespace for the container. Instead, the container shares the host's networking stack directly. This means if you run an NGINX container on port 80 using the host network, NGINX binds directly to port 80 of the host's physical network interface.

# Running a container on the host network
docker run -d --name load_balancer \
  --network host \
  nginx:alpine

When to Use Host Networking

• High-Throughput Services: Load balancers, API gateways, or database nodes that require minimal latency and maximum throughput.
• Dynamic Port Allocation: Applications that manage a wide range of ports dynamically (like WebRTC servers or SIP proxies) where mapping thousands of ports via the bridge would be incredibly inefficient.

The Trade-off: You lose network isolation. The container has full access to the host's network interfaces, and port conflicts are possible. If a host-level service is already using port 80, your container will fail to start. Additionally, the host driver is primarily optimized for Linux hosts; it has limited or varying behavior on Docker Desktop for Mac and Windows due to the underlying virtual machine architecture.

The Docker Macvlan Network: Bridging the Physical Gap

Sometimes, you have legacy applications that were never designed for containerized environments. They might require direct layer-2 network access, expect a unique MAC address, or demand to be on the same physical subnet as legacy bare-metal servers. This is exactly where the docker macvlan network driver shines.

The macvlan driver allows you to assign a MAC address to a container, making it appear as a physical device on your physical network. The Docker daemon routes traffic to containers based on their MAC addresses.

To configure a macvlan network, you need to specify the physical interface on your host (e.g., eth0 or enp3s0) and define the subnet that matches your physical network.

# Creating a macvlan network tied to the physical interface eth0
docker network create -d macvlan \
  --subnet=192.168.1.0/24 \
  --gateway=192.168.1.1 \
  -o parent=eth0 \
  physical_net

# Running a container with a static IP on the macvlan network
docker run -d --name legacy_app \
  --network physical_net \
  --ip 192.168.1.100 \
  my_legacy_app:latest

Important Considerations for Macvlan

While powerful, macvlan comes with severe networking caveats. By default, Linux security prevents the host machine from communicating directly with the macvlan interfaces attached to its own physical adapter. This means your host OS cannot ping the container, and the container cannot ping the host OS. (You can bypass this by creating a secondary macvlan interface on the host, but it requires advanced routing).

Additionally, you must ensure your physical network's DHCP server does not assign the static IPs you've reserved for your macvlan containers. Furthermore, your host's network adapter and the upstream switch must support "promiscuous mode" (allowing the interface to process traffic for multiple MAC addresses). Cloud providers like AWS and GCP often block promiscuous mode by default, making macvlan difficult to use in public clouds.

Demystifying Docker Container DNS Resolution (127.0.0.11)

If you have ever shelled into a container and inspected the /etc/resolv.conf file, you've likely seen something like this:

nameserver 127.0.0.11
options ndots:0

What exactly is 127.0.0.11? This is the IP address of the embedded docker container DNS resolution server.

In modern Docker, container IP addresses are dynamic. When a container restarts, it might receive a completely different IP. Hardcoding IP addresses is an anti-pattern. Instead, you rely on service discovery. When a container running on a user-defined bridge attempts to resolve a hostname (e.g., curl http://backend-api), the DNS query goes to 127.0.0.11.

The embedded DNS server maintains a mapping of container names and network aliases to their current IP addresses within that specific virtual network.

1. If the query matches a known container name or alias on the same network, Docker returns the container's internal IP.
2. If the query is for an external domain (like google.com), the embedded DNS server acts as a forwarder. It forwards the request to the upstream DNS servers configured on the host machine.

Network Aliases and Load Balancing

The embedded DNS server also provides basic round-robin load balancing. If you attach multiple containers to a network with the same network alias, DNS queries for that alias will return a randomized list of IP addresses, effectively distributing the load.

# Start multiple workers with the same alias
docker run -d --network my-net --network-alias api-backend worker-image
docker run -d --network my-net --network-alias api-backend worker-image
docker run -d --network my-net --network-alias api-backend worker-image

# Pinging 'api-backend' will now resolve to one of the three worker IPs

Troubleshooting Docker Networks Like a Pro

When containers can't communicate, the debugging process requires checking multiple layers of the networking stack. Here is the ZeroData methodology for debugging Docker networks.

1. Inspecting the Network

The first step is always to verify that the containers are on the network you think they are on. Use the docker network inspect command to view the subnet layout and the list of attached containers.

docker network inspect my-app-network

This outputs a JSON document. Look under the "Containers" key to verify the IP addresses and ensure both the source and destination containers are present.

2. Verifying DNS Resolution

If containers are on the same network but can't talk via hostname, verify that the embedded DNS server is functioning. Exec into the container and use tools like ping or nslookup.

docker exec -it web-container sh
# Inside the container:
ping db-container

3. Advanced Debugging with nsenter

Sometimes, images are built from scratch or minimal distributions like Alpine, and they lack basic networking tools like ping, curl, or ip. Instead of modifying your production images to include debugging tools, you can use the host's tools inside the container's network namespace using nsenter.

# Get the PID of the container
PID=$(docker inspect -f '{{.State.Pid}}' my-broken-container)

# Enter the container's network namespace and run host commands
sudo nsenter -t $PID -n ip addr
sudo nsenter -t $PID -n route -n
sudo nsenter -t $PID -n tcpdump -i eth0

This powerful technique allows you to run a packet capture (tcpdump) directly on a container's interface without altering the container itself.

Final Thoughts

Mastering Docker networking elevates you from someone who just runs containers to someone who can architect resilient, secure, and highly performant infrastructure. By defaulting to user-defined bridges, reserving host networking for high-performance edge nodes, deploying macvlan for physical integration, and leveraging Docker's embedded DNS, you can solve almost any topology challenge.

Remember, the foundation of a stable network is a valid configuration file. Don't forget to regularly lint and validate your infrastructure code using our local, client-side Docker Compose Validator to catch configuration bugs before they ever hit your servers.