The Docker linking architecture

At a senior engineering level, Docker networking creeps away from the high-level shipping container metaphors and moves into Linux kernel primitives, network namespaces, and iptables routing.

Here is how container linking and port mechanics (kind of) work under the hood.

Container Inter-Connectivity

Try saying that 3 times in a row... anyway, it is The "Linking" Architecture.

Network Namespaces (netns)

• Every Docker container gets its own isolated network stack namespace. This means an isolated routing table, distinct interfaces, firewall rules, and its own loopback (127.0.0.1) device.

Virtual Ethernet Pairs (veth)

• Docker connects a container to a network using a veth pair—a virtual wire acting as a bidirectional tunnel. One end of this pair is placed inside the container's namespace (usually mapped as eth0), and the other end is bound to the host's virtual bridge interface (e.g., docker0).

The Bridge Layer (L2 Isolation)

• By default, local multi-container communication goes through a software bridge (brctl). The bridge acts as a virtual layer-2 switch, broadcasting ARP requests and switching ethernet frames natively between the veth ends attached to it.
  
  

Embedded DNS Resolver (Service Discovery)

• When using custom user-defined networks (like those implicitly created by Docker Compose), Docker runs an embedded DNS server at 127.0.0.11 inside each container. When a container requests DB_HOST=database, this resolver intercepts the query and returns the internal IP allocated to the destination container's namespace.

Network Drivers & Overlay (L3/Multi-Host)

• For single-host workloads, the bridge driver is used. For multi-host distributed systems (like Swarm mode), Docker uses the overlay driver, which implements VXLAN (Virtual Extensible LAN) encapsulation to tunnel layer-2 traffic over layer-3 host networks using UDP port 4789.
  
  

Port Mechanics

What Ports "Do or Might Not Do"

The EXPOSE Instruction is Pure Metadata

• Adding EXPOSE 3000 to a Dockerfile does not open, bind, or publish any ports. It is merely documentation for human developers and a hint for automated orchestration tools. If a process listens on a port inside the namespace, it is reachable by other containers on the same network regardless of whether EXPOSE is stated.
  
  

The -p / --publish Flag Alters Host Routing

• When you execute docker run -p 8080:3000, you are telling the Docker daemon to map port 8080 on the host system to port 3000 inside the container's isolated network namespace.

The docker-proxy User-Space Daemon

• For every published port, Docker spins up a user-space proxy process (docker-proxy). It binds directly to the designated host interface and port. If a host-bound request arrives and iptables bypassing occurs, docker-proxy forwards the traffic directly into the container's internal IP.

Kernel-Level Routing via iptables (DNAT)

• To avoid the performance bottleneck of the user-space proxy, Docker injects rules into the host’s Linux kernel network stack via iptables (specifically the DOCKER chain in the nat table). When a packet hits the host interface on a published port, Destination Network Address Translation (DNAT) rewrites the packet header on-the-fly, swapping the host IP/port for the container’s internal bridge IP/port.
  
  

Host Network Bypass (--network host)

• If a container is run with host networking, Docker entirely bypasses namespace isolation for networking. The container shares the host’s network interfaces directly. In this mode, port mapping is completely non-functional; if the containerized app binds to port 3000, it binds to the host's physical port 3000 natively.