Lesson 6 of 8 in Containers with Docker

Container networking

Core11 min

Each container has its own network namespace, so it has its own localhost and its own IP address. Containers on the same user-defined bridge network reach each other by name, and a published port opens a path from the host in.

Draft. This lesson is written and waiting for a person to run every command and review it. It is safe to learn from, but check the official documentation for anything you depend on.

Read these first: Running and inspecting containers, Networking for DevOps

The problem this solves

Real apps are several programs that talk to each other: a web app and a database, an API and a cache. Because each container gets its own isolated network, they cannot assume the addresses and names they have on a single machine.

The most common surprise is localhost. Inside a container it means that container itself, so an app that calls localhost:5432 for its database is looking in its own empty container.

Docker's answer is a virtual network the containers join, with built-in name lookup. You address another container by its name, and you publish only the ports that the outside world truly needs.

How it works

Reaching another container by name
Reaching another container by nameOn a user-defined network, the app asks Docker's built-in DNS for the name web and then connects to the address it receives.1 lookup: who is web?2 connect toits IP:80app containerwants to call webDocker DNSname to IP lookupweb containerlistens on port 80
  • Runs code
  • Network

On a user-defined network, the app asks Docker's built-in DNS for the name web and then connects to the address it receives.

  1. app container to Docker DNS: 1 lookup: who is web?
  2. app container to web container: 2 connect to its IP:80
Published ports versus private ports
Published ports versus private portsOnly the web container's port is published to the host, so the browser reaches web, and web reaches the database over the private network.1 request:80802 forwardedto :803 reachesdb:5432Browseron your computerHost port 8080published with -pwebcontainer, port 80dbno published port
  • People and clients
  • Network
  • Runs code
  • Data

Only the web container's port is published to the host, so the browser reaches web, and web reaches the database over the private network.

  1. Browser to Host port 8080: 1 request :8080
  2. Host port 8080 to web: 2 forwarded to :80
  3. web to db: 3 reaches db:5432

Every container gets its own network namespace, which includes its own localhost. Another container is a separate machine as far as the network is concerned, so you reach it by its IP address or, better, its name.

The default bridge network does not do name lookup between containers. A network you create yourself with docker network create does: containers on it can resolve each other by container name, and Compose creates such a network for you automatically.

Published ports are a different thing. -p is for traffic coming from outside the Docker network, such as your browser. Two containers on the same user-defined network can talk to each other on any port without publishing anything.

Finally, a program must listen on all interfaces inside the container, 0.0.0.0, not only on 127.0.0.1. Otherwise forwarded traffic cannot reach it even though the port is published.

Try it yourself

These commands create one network and a few short-lived containers. Cleanup is at the end.

  1. 1
    Create a network and a server on it
    docker network create appnet
    docker run -d --name web --network appnet nginx:alpine

    No -p here, so the host cannot reach this server, but other containers on appnet can.

  2. 2
    Call it by name from another container
    docker run --rm --network appnet alpine wget -qO- http://web

    Docker's DNS resolves web to the server's IP address, and you get the nginx welcome page back.

  3. 3
    Try localhost and watch it fail
    docker run --rm --network appnet alpine wget -T 3 -qO- http://localhost

    This fails with a connection refused style error, because localhost in that container is the container itself, where nothing listens on port 80.

  4. 4
    Inspect the network
    docker network inspect appnet

    Look at the Containers section to see each member and its private IP address.

  5. 5
    Clean up
    docker rm -f web
    docker network rm appnet

What breaks, and where to look

  • connect ECONNREFUSED 127.0.0.1:5432 (or a similar Connection refused to localhost) from the app container.

    WHY IT HAPPENS
    The app uses localhost or 127.0.0.1 for a service in another container. That address points back at the app's own container.
    CHECK FIRST
    Change the host in the app's config to the other container's name, for example the Compose service name db, and run docker exec <app> getent hosts db to confirm the name resolves.
  • curl: (52) Empty reply from server, or (56) Recv failure: Connection reset by peer, on a port you published.

    WHY IT HAPPENS
    The program inside the container listens only on 127.0.0.1. Forwarded traffic arrives on the container's other interface and is refused.
    CHECK FIRST
    Run docker exec <name> ss -ltn or netstat -ltn and look for 127.0.0.1:<port>. Reconfigure the app to bind 0.0.0.0.
  • wget: bad address 'web', or could not translate host name, between two containers you started with plain docker run.

    WHY IT HAPPENS
    Both containers are on the default bridge network, which does not provide name resolution between containers.
    CHECK FIRST
    Run docker network inspect bridge to see where they are. Put both on a network you created with --network, or use Compose.

When not to use this

  • Using container IP addresses directly is fragile because they change when containers restart. Use names.
  • Across several machines, a single bridge network is not enough. That needs an orchestrator such as Kubernetes, which has its own networking model.

Check yourself

What does localhost mean inside a container?

The container itself. It never refers to the host or to other containers.

Do two containers on the same user-defined network need published ports to talk?

No. Published ports are for traffic from outside the Docker network. Containers on the same network can use any port directly.

Why can a published port still give an empty reply?

The app may listen only on 127.0.0.1 inside the container, so forwarded traffic cannot reach it. It should listen on 0.0.0.0.

Lesson 44 of 92 in the DevOps path

Search

Search cheat sheets and projects