Skip to content
Tutorials Center
My learning

Topics

Lesson 53 of 111 ยท Networking

User-Defined Bridge Networks

Learn why you should create your own Docker bridge networks: automatic DNS by container name, isolation, network aliases, connect and disconnect, subnets and internal networks.

Docker gives every machine a built-in bridge network called bridge. Containers you start without any network option land on it, and they can reach each other by IP address. That works, but it is the weakest networking setup Docker offers: no name resolution between containers, no isolation between unrelated apps, and addresses that change every time a container restarts.

The fix is a one-liner: create your own bridge network. A user-defined bridge gives you automatic DNS (containers find each other by name), better isolation, and the ability to plug containers in and out while they run. It is what Docker Compose creates for you behind the scenes, so understanding it now makes Compose much easier to read later. Every command and output in this lesson comes from a real Docker 29 engine.

Creating a network and putting containers on it

Creating a network takes one command:

CONSOLE
$ docker network create shop-net
d64b9be74a8b

The default driver is bridge, so you do not need to say so. Now start two containers on that network with --network:

CONSOLE
$ docker run -d --name web --network shop-net nginx:alpine
$ docker run -d --name db --network shop-net -e POSTGRES_PASSWORD=secret postgres:17-alpine

To see who is on the network, inspect it:

CONSOLE
$ docker network inspect shop-net --format '{{range .Containers}}{{.Name}} {{.IPv4Address}}{{"\n"}}{{end}}'
db 172.21.0.3/16
web 172.21.0.2/16
$ docker network inspect shop-net --format '{{(index .IPAM.Config 0).Subnet}} {{.Driver}}'
172.21.0.0/16 bridge

(The subnet is picked by Docker from a pool, so yours will differ.) Each container got an address from the network's subnet. Think of the network as a virtual Ethernet switch living inside your machine, with your containers plugged into it:

TEXT
        host
  +-------------------------------------------+
  |   bridge "shop-net"  172.21.0.0/16        |
  |        |                 |                |
  |   +---------+       +---------+           |
  |   |   web   |       |   db    |           |
  |   | .0.2    |       | .0.3    |           |
  |   +---------+       +---------+           |
  +-------------------------------------------+

Automatic DNS by name

Here is the feature that makes user-defined bridges worth using. Docker runs a small DNS server for each container on a user-defined network, and it answers questions about the other containers on the same network. From a throwaway container on shop-net:

CONSOLE
$ docker run --rm --network shop-net alpine:3 sh -c 'nslookup web | tail -2; ping -c1 web | head -2'
Name:	web
Address: 172.21.0.2

PING web (172.21.0.2): 56 data bytes
64 bytes from 172.21.0.2: seq=0 ttl=64 time=2.365 ms

The name web resolved to the container's current IP. That is why application config can say DB_HOST=db and keep working after the database container is recreated with a new address. You never hard-code container IPs.

How does the container know where to ask? Look at its /etc/resolv.conf:

CONSOLE
$ docker run --rm --network shop-net alpine:3 grep nameserver /etc/resolv.conf
nameserver 127.0.0.11

127.0.0.11 is Docker's embedded DNS server. It answers for container names and network aliases on the networks that container is attached to, and forwards everything else (like example.com) to the upstream resolvers Docker found on the host.

Now compare with the default bridge. Start a container there and try to reach it by name:

CONSOLE
$ docker run -d --name old alpine:3 sleep 300
$ docker run --rm alpine:3 ping -c1 -W2 old
ping: bad address 'old'
$ docker run --rm alpine:3 grep nameserver /etc/resolv.conf
nameserver 192.168.65.7

On the default bridge there is no embedded DNS. The container simply inherited the host's resolver (the address you see depends on your setup), which has never heard of old.

The old --link flag existed to patch this gap on the default bridge. It is deprecated. Create a user-defined network instead.

Why user-defined beats the default bridge

Feature Default bridge User-defined bridge
Resolve containers by name No Yes (embedded DNS)
Isolation from unrelated containers No, everything shares it Yes, per network
Attach or detach a running container No (stop and recreate) Yes (network connect / disconnect)
Configurable subnet, gateway, options Only by reconfiguring the daemon Per network, at creation
Can be removed No, it is built in Yes

The isolation point matters in practice. If your blog and your billing system both run on the default bridge, they can talk to each other whether you want it or not. Put each on its own user-defined network and they cannot see each other at all.

Isolation in action

Create a second network and start a container on it:

CONSOLE
$ docker network create back-net
$ docker run --rm --network back-net alpine:3 ping -c1 -W2 web
ping: bad address 'web'

The container on back-net cannot even resolve web, because web lives on shop-net and Docker only answers DNS questions about containers that share a network with the asker. Even by IP, traffic between two different bridge networks is blocked by the host firewall rules Docker installs.

Connecting and disconnecting live

A container can be on several networks at once. docker network connect adds a running container to another network without restarting it, and docker network disconnect takes it out. This is the standard way to build a front-end/back-end split: a proxy joins both networks, the database joins only the back one.

CONSOLE
$ docker network connect back-net web
$ docker inspect web --format '{{range $k,$v := .NetworkSettings.Networks}}{{$k}} {{end}}'
back-net shop-net
$ docker run --rm --network back-net alpine:3 ping -c1 web | head -1
PING web (172.22.0.2): 56 data bytes
$ docker network disconnect back-net web

Now web is reachable from both networks, while db (only on shop-net) is invisible to anything on back-net. Disconnecting a container that is not on that network gives a clear error: container ... is not connected to network back-net.

The same pattern is the foundation of a good multi-tier layout: put each tier on the networks it needs and nothing more.

Network aliases

A container is always reachable by its own name on a user-defined network. You can add extra names, called aliases, with --network-alias at docker run time, or --alias with network connect:

CONSOLE
$ docker network connect --alias cache back-net web
$ docker run --rm --network back-net alpine:3 ping -c1 cache | head -1
PING cache (172.22.0.2): 56 data bytes

Aliases are scoped to the network they were set on. Reached over back-net the container answers to cache; on shop-net that name does not exist. Aliases let you decouple the name your app uses (database, cache, search) from the name of the container, which is handy when you swap one implementation for another.

Aliases and simple load balancing

Several containers can share one alias. Docker's DNS then returns all their addresses:

CONSOLE
$ docker run -d --name a1 --network back-net --network-alias pool alpine:3 sleep 300
$ docker run -d --name a2 --network back-net --network-alias pool alpine:3 sleep 300
$ docker run --rm --network back-net alpine:3 nslookup pool | tail -5
Name:	pool
Address: 172.22.0.3
Name:	pool
Address: 172.22.0.2

This is DNS round-robin: the order of the answers rotates, so clients that take the first address spread their connections around. It is crude (no health checks, and clients may cache the answer), but it is good enough for development and is how Compose spreads traffic across scaled services.

Configuring a network

docker network create accepts options for the addressing:

CONSOLE
$ docker network create --subnet 10.77.0.0/24 --gateway 10.77.0.1 fixed-net
$ docker run --rm --network fixed-net --ip 10.77.0.50 alpine:3 ip -4 addr show eth0 | grep inet
    inet 10.77.0.50/24 brd 10.77.0.255 scope global eth0
  • --subnet and --gateway choose the address range. Do this when Docker's automatic pool collides with your office VPN or another network you must reach.
  • --ip pins a single container's address (it must be inside the subnet, and you need an explicit --subnet for it to be allowed).
  • --ip-range limits which part of the subnet Docker hands out automatically.

Pinning IPs is rarely needed. If you find yourself doing it, check whether a name or alias would solve the problem instead.

Internal networks

Add --internal and the network gets no route to the outside world:

CONSOLE
$ docker network create --internal sealed-net
$ docker run --rm --network sealed-net alpine:3 ping -c1 -W2 8.8.8.8
PING 8.8.8.8 (8.8.8.8): 56 data bytes
ping: sendto: Network unreachable

Containers on an internal network can talk to each other but not to the internet, and you cannot publish their ports. It is a neat way to keep a database tier truly private: the app joins both a normal network and the internal one; the database joins only the internal one.

An easy way to remember the rule: a container needs the internet only if it joins at least one network that is not --internal. A database that never calls out should sit alone on an internal network.

Listing and removing networks

CONSOLE
$ docker network ls --filter name=net --format 'table {{.Name}}\t{{.Driver}}\t{{.Scope}}'
NAME        DRIVER    SCOPE
back-net    bridge    local
shop-net    bridge    local

You cannot remove a network that still has containers attached:

CONSOLE
$ docker network rm shop-net
Error response from daemon: error while removing network: network shop-net has active endpoints (name:"web" id:"baa0d5bff94f", name:"db" id:"428e9044c327")

Stop and remove the containers first (or docker network disconnect them), then remove the network. The three built-in networks (bridge, host, none) cannot be removed. They are covered in Host, None, Macvlan and Overlay.

docker network prune removes every network that has no containers, which may include ones you created for later. Check docker network ls first, or use a --filter such as label=... so it only touches networks you meant to clean. More on safe cleanup in Cleaning Up.

When to use what

  • Always use a user-defined bridge for anything beyond a single throwaway container. It costs nothing and gives you names.
  • One network per application (or per tier) is a good default. Compose does exactly that.
  • Use multiple networks per container when a service must bridge two worlds, like a reverse proxy.
  • Reach for the default bridge only for quick experiments, and expect to use IP addresses there.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the main reason to create a user-defined bridge instead of using the default bridge?

    User-defined bridges add Docker's embedded DNS server (at 127.0.0.11), so containers can resolve each other by name, and they keep unrelated containers apart. Speed and port publishing are the same on both.
  2. 2. A container on network back-net tries to ping a container named web that lives only on shop-net. What happens?

    Docker's DNS only answers for containers that share a network with the asker. The lookup fails, and even by IP the firewall rules block traffic between separate bridge networks.
  3. 3. How do you make a running container reachable on a second network without restarting it?

    docker network connect attaches a running container to another network, and docker network disconnect removes it. A container can be on many networks at once.
  4. 4. What does the --internal flag on docker network create do?

    Containers on an internal network can reach each other but have no route out, so pinging 8.8.8.8 fails with 'Network unreachable'. DNS between containers still works.
  5. 5. Two containers on the same network both use --network-alias pool. What does a lookup of pool return?

    Shared aliases produce DNS round-robin: the lookup returns every matching address and the order rotates, which spreads clients around.

Summary

  • The default bridge network has no name resolution and no isolation. Create your own with docker network create.
  • On a user-defined bridge, Docker's embedded DNS (127.0.0.11) resolves container names and aliases for containers on the same network.
  • Networks isolate: containers on different bridges cannot resolve or reach each other.
  • docker network connect and disconnect change a running container's networks; a container can join several.
  • --network-alias adds extra names and, when shared, gives DNS round-robin.
  • --subnet, --gateway and --ip fix addressing; --internal removes outside access.
  • You cannot remove a network that still has containers attached.

Next: Host, None, Macvlan and Overlay