Docker Networking

Container networking from the kernel up

Docker Networking from First Principles

Docker networking is not magic — it is built entirely on Linux kernel primitives: network namespaces, virtual ethernet (veth) pairs, bridges, and iptables. Understanding these building blocks demystifies every Docker networking behavior.

Default Bridge Architecture

When Docker starts, it creates a Linux bridge interface called docker0 (typically 172.17.0.1/16). Each new container gets:

• Its own network namespace (isolated network stack)
• A veth pair: one end appears as eth0 inside the container, the other end attaches to docker0
• An IP address from the bridge's subnet (e.g., 172.17.0.2, 172.17.0.3, ...)
• A default route pointing to the bridge IP (172.17.0.1)

Topology: docker0 Bridge, veth Pairs, and Containers

Outbound Traffic: Container to Internet

Containers sit behind NAT. When a container sends traffic to the internet, the packet traverses several stages in the host kernel:

1. Container eth0

   Packet leaves container namespace via veth

2. docker0 bridge

   Bridge receives frame, routes to host stack

3. iptables MASQUERADE

   SNAT: rewrite src IP to host IP

4. Host eth0

   Physical interface sends to gateway

5. Internet

   Reply comes back, conntrack maps it

The MASQUERADE Rule

Docker inserts this iptables rule in the nat table's POSTROUTING chain:

    $ iptables -t nat -L POSTROUTING -n -v --line-numbers

    Chain POSTROUTING (policy ACCEPT)

num   target     prot opt source               destination

1     MASQUERADE  all  --  172.17.0.0/16        0.0.0.0/0  ! -o docker0
  

The rule in iptables syntax:

# Source NAT for container traffic leaving the host
-t nat -A POSTROUTING -s 172.17.0.0/16 ! -o docker0 -j MASQUERADE

Inbound Traffic: Port Mapping (-p 8080:80)

Port mapping exposes a container service on a host port. Under the hood, Docker installs two iptables rules:

1. DNAT Rule (nat table, DOCKER chain)

# Redirect host port 8080 to container 172.17.0.2 port 80
-t nat -A DOCKER -p tcp --dport 8080 -j DNAT --to-destination 172.17.0.2:80

This rewrites the destination address. Traffic arriving at host:8080 gets rewritten to 172.17.0.2:80 before routing.

2. ACCEPT Rule (filter table, DOCKER chain)

# Allow forwarded traffic to reach the container
-A DOCKER -d 172.17.0.2/32 ! -i docker0 -o docker0 -p tcp --dport 80 -j ACCEPT

This allows the DNAT'd traffic through the FORWARD chain to reach the container.

1. External client

   Connects to host:8080

2. PREROUTING/DNAT

   Rewrite dst to 172.17.0.2:80

3. FORWARD/ACCEPT

   Filter allows the packet

4. docker0 bridge

   Routes to veth pair

5. Container :80

   Receives the connection

Network Drivers

Docker supports multiple networking modes via pluggable drivers. Each driver addresses a different use case and makes different trade-offs between isolation, performance, and complexity.

Driver Details

$ docker run --network bridge nginx

$ docker run --network host nginx

$ docker run --network none alpine ip addr
# Only shows lo (127.0.0.1)

$ docker network create -d macvlan \
  --subnet=192.168.1.0/24 \
  --gateway=192.168.1.1 \
  -o parent=eth0 my_macvlan

$ docker network create -d overlay --attachable my_overlay

Docker's Embedded DNS Server

Docker runs an embedded DNS server at 127.0.0.11 inside each container on user-defined networks. This enables service discovery by container name.

# This FAILS on default bridge:
$ docker exec app ping db
ping: db: Name or service not known

# This WORKS on user-defined bridge:
$ docker exec app ping db
PING db (172.18.0.3): 56 data bytes
64 bytes from 172.18.0.3: seq=0 ...

User-Defined Bridges vs Default Bridge

    $ docker network create my-app-net

    a1b2c3d4e5f6...


    $ docker run -d --name db --network my-app-net postgres

    $ docker run -d --name app --network my-app-net -e DB_HOST=db my-app


    # app can now resolve "db" to the postgres container's IP
  

Docker Compose Networking

Docker Compose automatically creates a dedicated bridge network for each project. This is one of its biggest ergonomic wins — zero networking configuration needed for most apps.

# docker-compose.yml
services:
  web:
    image: nginx
    ports:
      - "8080:80"
  api:
    image: my-api
    environment:
      - DB_HOST=db     # resolves via DNS
  db:
    image: postgres:16

# All three services can reach each other as "web", "api", "db"
# Compose creates network: myproject_default

Custom Network Configuration

services:
  web:
    image: nginx
    networks:
      - frontend
  api:
    image: my-api
    networks:
      - frontend
      - backend    # api bridges both networks
  db:
    image: postgres:16
    networks:
      - backend

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    ipam:
      config:
        - subnet: 172.28.0.0/16

# web can talk to api (frontend network)
# api can talk to db (backend network)
# web CANNOT talk to db (different networks, no route)

Debugging Docker Networking

Essential commands for inspecting and troubleshooting container networking:

    # List all Docker networks

    $ docker network ls

    NETWORK ID     NAME              DRIVER    SCOPE
a1b2c3d4e5f6   bridge            bridge    local
f6e5d4c3b2a1   host              host      local
1a2b3c4d5e6f   none              null      local
9f8e7d6c5b4a   myproject_default bridge    local



    # Inspect a network — shows subnet, gateway, connected containers

    $ docker network inspect bridge

    [{
    "Name": "bridge",
    "IPAM": { "Config": [{ "Subnet": "172.17.0.0/16", "Gateway": "172.17.0.1" }] },
    "Containers": {
        "abc123...": { "Name": "web", "IPv4Address": "172.17.0.2/16" }
    }
}]



    # Inspect networking from inside a container

    $ docker exec -it web ip addr

    1: lo: <LOOPBACK,UP> mtu 65536
    inet 127.0.0.1/8 scope host lo
2: eth0@if7: <BROADCAST,MULTICAST,UP> mtu 1500
    inet 172.17.0.2/16 brd 172.17.255.255 scope global eth0



    # Check routing table inside a container

    $ docker exec -it web ip route

    default via 172.17.0.1 dev eth0
172.17.0.0/16 dev eth0 scope link src 172.17.0.2



    # Check DNS resolution

    $ docker exec -it web cat /etc/resolv.conf

    nameserver 127.0.0.11
options ndots:0



    # View Docker's iptables rules on the host

    $ iptables -t nat -L -n -v

    $ iptables -L DOCKER -n -v



    # See veth pairs — match host-side veth to container

    $ ip link show type veth

    $ brctl show docker0  # (or: bridge link show)