Skip to content
Tutorials Center
My learning

Topics

Lesson 51 of 111 ยท Networking

Docker Networking

Understand Docker networking: the network drivers, how the default bridge connects containers, container IP addresses and gateways, outbound access, and DNS basics.

A container is isolated, but almost no container is alone. A web application talks to a database, a cache, other services, and the internet. Docker makes that possible by giving every container its own network stack: its own network interface, IP address, routing table and DNS settings. Behind the scenes Docker creates virtual networks on the host and plugs each container into one or more of them.

This lesson gives you the whole picture: what network drivers exist, what happens when you run a container without any network options, how to read a container's IP address and routes, how containers reach each other and the outside world, and how DNS works on the default network. The next lessons build on it: publishing ports so the outside world can reach a container, and user-defined bridge networks, which fix the weak points of the default one.

A container has its own network stack

Linux uses network namespaces to give a process its own private network world. A container starts in a fresh namespace, so it does not see the host's interfaces. Inside, a program sees a loopback interface (lo, which is 127.0.0.1) and a virtual Ethernet interface (eth0) that Docker connects to a network on the host.

TEXT
   +---------------- Docker host ----------------+
   |                                              |
   |  container A        container B              |
   |  eth0 172.17.0.7    eth0 172.17.0.6          |
   |      |                  |                    |
   |      +------ bridge "docker0" 172.17.0.1 ---+--- NAT ---> physical NIC ---> internet
   |                                              |
   +----------------------------------------------+

The key consequence: localhost inside a container means the container itself. If your application in container A connects to localhost:5432 hoping to reach a database in container B, it will not find it. You need B's address or name, which is what this chapter is about.

Network drivers at a glance

A network is created by a driver, just like a volume. These are the built-in ones:

Driver What it does Typical use
bridge A private virtual switch on one host; containers get addresses on it The default; most single-host setups
host No isolation: the container uses the host's network stack directly Special cases needing raw performance or many ports
none Only a loopback interface Fully offline jobs, custom wiring
overlay A network spanning several Docker hosts (Swarm) Multi-host clusters
macvlan Gives the container its own MAC address on your physical LAN Legacy software that expects to sit on the LAN
ipvlan Like macvlan, sharing the host's MAC address Similar niches

You will use bridge 95% of the time. The others have their own lesson: Host, None, Macvlan and Overlay. See what exists on your machine:

CONSOLE
$ docker network ls
NETWORK ID     NAME      DRIVER    SCOPE
92ecb4c05d28   bridge    bridge    local
5a4ac2a9b86e   host      host      local
1d4122531bc5   none      null      local

These three are created with Docker and cannot be removed. Names matter: a network called bridge is the default bridge, and host and none are the other two special cases. (On a machine with Compose projects you will see more lines, such as myproject_default.)

The default bridge network

Run a container without --network and Docker attaches it to the default bridge. On Linux the host side of that network is a virtual switch named docker0. Check its address range:

CONSOLE
$ docker network inspect bridge -f '{{json .IPAM.Config}} {{index .Options "com.docker.network.bridge.name"}}'
[{"Subnet":"172.17.0.0/16","Gateway":"172.17.0.1"}] docker0

The default network is 172.17.0.0/16. Docker hands out addresses from it, starting after the gateway 172.17.0.1, which belongs to the host's end of the bridge. Start two containers:

CONSOLE
$ docker run -d --name a alpine sleep 300
$ docker run -d --name b alpine sleep 300

Finding a container's IP address

In older versions you could read .NetworkSettings.IPAddress. That shortcut is gone in Docker 29, which lists addresses per network, because a container can be on several networks. Use the per-network path instead:

CONSOLE
$ docker inspect -f '{{range $name, $net := .NetworkSettings.Networks}}{{$name}} {{$net.IPAddress}} gw={{$net.Gateway}}{{end}}' a b
bridge 172.17.0.7 gw=172.17.0.1
bridge 172.17.0.6 gw=172.17.0.1

(The first line is container a, the second b.) You can also ask the network which containers are plugged into it:

CONSOLE
$ docker network inspect bridge -f '{{range .Containers}}{{.Name}} {{.IPv4Address}}{{"\n"}}{{end}}'
b 172.17.0.6/16
a 172.17.0.7/16

Addresses are handed out when containers start, in no guaranteed order, and may change after a restart. That is why you should never hard-code container IPs. Use names, which brings us to the next sections.

What the container sees from the inside

CONSOLE
$ docker exec a ip addr show eth0
2: eth0@if959: <BROADCAST,MULTICAST,UP,LOWER_UP,M-DOWN> mtu 1500 qdisc noqueue state UP
    inet 172.17.0.7/16 brd 172.17.255.255 scope global eth0
$ docker exec a ip route
default via 172.17.0.1 dev eth0
172.17.0.0/16 dev eth0 scope link  src 172.17.0.7

The numbers vary, but the shape is always the same. The container has an interface eth0 with an address from the bridge's subnet. The @if959 suffix means the other end of this virtual cable is interface number 959 on the host. Everything outside 172.17.0.0/16 is sent via the default route to 172.17.0.1, the host.

Reaching other containers

Containers on the same bridge are on the same virtual switch, so they can reach each other by IP address:

CONSOLE
$ docker exec a ping -c2 172.17.0.6
PING 172.17.0.6 (172.17.0.6): 56 data bytes
64 bytes from 172.17.0.6: seq=0 ttl=64 time=0.731 ms
64 bytes from 172.17.0.6: seq=1 ttl=64 time=0.104 ms

--- 172.17.0.6 ping statistics ---
2 packets transmitted, 2 packets received, 0% packet loss
round-trip min/avg/max = 0.104/0.417/0.731 ms

Not by name, though, on the default bridge:

CONSOLE
$ docker exec a ping -c1 b
ping: bad address 'b'

This is the biggest limitation of the default bridge. It has no automatic DNS for container names. The old --link option patched this, but it is deprecated. The cure is a user-defined bridge, one command away:

CONSOLE
$ docker network create appnet
$ docker run -d --name c --network appnet alpine sleep 300
$ docker run --rm --network appnet alpine ping -c1 c
PING c (172.21.0.2): 56 data bytes
64 bytes from 172.21.0.2: seq=0 ttl=64 time=0.915 ms

On appnet, the name c just works, because Docker runs a small DNS server for every user-defined network. Other differences are covered in User-Defined Bridge Networks. For anything beyond a quick experiment, put your containers on a user-defined network. Compose does this for you automatically.

Reaching the internet (outbound traffic)

The container's default route sends packets to the host. The host then performs NAT (masquerading), replacing the container's private address with its own, much like your home router. So outbound connections work without any option:

CONSOLE
$ docker exec a ping -c1 example.com
PING example.com (104.20.23.154): 56 data bytes
64 bytes from 104.20.23.154: seq=0 ttl=63 time=12.315 ms

Notice that the name example.com resolved. That is DNS, covered next. The reverse direction does not work by default: nobody on the internet or your LAN can open a connection to 172.17.0.7, since it is a private address. To allow that, you publish a port; see Publishing Ports.

You can see that masquerading is a setting on the network:

CONSOLE
$ docker network inspect bridge -f '{{index .Options "com.docker.network.bridge.enable_icc"}} {{index .Options "com.docker.network.bridge.enable_ip_masquerade"}}'
true true

enable_icc (inter-container communication) and enable_ip_masquerade are both true on the default bridge.

DNS basics

Names are resolved in two layers.

On the default bridge, the container receives a copy of the host's resolver settings in /etc/resolv.conf. Docker generates that file and writes a comment saying so:

CONSOLE
$ docker exec a cat /etc/resolv.conf
# Generated by Docker Engine.
# This file can be edited; Docker Engine will not make further changes once it
# has been modified.

nameserver 192.168.65.7

# Based on host file: '/etc/resolv.conf' (legacy)
# Overrides: []

(On Docker Desktop the nameserver is an address inside its VM. On a Linux host you would typically see your router or systemd-resolved address. Your values will differ.) Because the container asks that server directly, it can resolve public names such as example.com but knows nothing about other containers.

On a user-defined network, the nameserver is Docker's built-in DNS at 127.0.0.11:

CONSOLE
$ docker run --rm --network appnet alpine cat /etc/resolv.conf | grep -v '^#'
nameserver 127.0.0.11
options ndots:0

That resolver answers container names and network aliases itself and forwards everything else to the host's servers. Custom DNS servers, search domains and proxies are covered in DNS, Proxies and Firewalls.

Docker also manages the hostname and /etc/hosts. A container's hostname is its short container ID by default, and the file maps it to the container's own address:

CONSOLE
$ docker exec a hostname
6097b53762aa
$ docker exec a tail -1 /etc/hosts
172.17.0.7	6097b53762aa

You can override the hostname with --hostname (-h) for software that cares about it.

The two special networks: none and host

none gives a container only a loopback interface, handy for jobs that must not talk to anything:

CONSOLE
$ docker run --rm --network none alpine ip addr
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN qlen 1000
    inet 127.0.0.1/8 scope host lo

host removes the separation: the container sees all the host's interfaces and uses its ports directly. That is more than a speed trick. It removes the network isolation that is one of the main reasons to use containers, so it is a deliberate choice for special cases. (On Docker Desktop, "the host" means the Docker VM, not your Windows or macOS system.) Details follow in Host, None, Macvlan and Overlay.

Cleaning up

CONSOLE
$ docker rm -f a b c
$ docker network rm appnet

A network cannot be removed while containers are connected to it. The three built-in networks cannot be removed at all.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Inside container A, an application connects to localhost:5432 expecting a database that runs in container B. What happens?

    Every container has its own network namespace, so localhost is the container. To reach another container use its IP address or, better, its name on a user-defined network.
  2. 2. Which statement about the default bridge network is correct?

    The default bridge connects containers at layer 2 but has no built-in DNS for container names. Outbound internet traffic works through NAT.
  3. 3. You need a container to have no network access except loopback. Which option do you use?

    The none driver creates only the loopback interface.
  4. 4. Why is it a bad idea to hard-code a container's IP address such as 172.17.0.6 in your configuration?

    Docker assigns addresses from the subnet at start-up. After a restart or recreate the same container may get a different one.
  5. 5. How does a container on the default bridge reach a website on the internet?

    The default route points at the gateway, the host's end of the bridge. The host masquerades the private address, like a home router. Publishing ports is only for inbound traffic.

Summary

  • Each container has its own network namespace: localhost inside it means itself.
  • Drivers: bridge (default), host, none, overlay, macvlan, ipvlan. Three networks (bridge, host, none) always exist.
  • The default bridge is 172.17.0.0/16 with gateway 172.17.0.1 (device docker0 on Linux).
  • Read a container's address with docker inspect per network (.NetworkSettings.Networks); in Docker 29 the old top-level .IPAddress field is gone.
  • Containers on the default bridge reach each other by IP, not by name; user-defined networks add DNS at 127.0.0.11.
  • Outbound traffic is NAT-ed through the host; inbound traffic needs published ports.

Next: Publishing Ports