Docker Core Networking

docker-core-networking

Quick Reference

Network Drivers

Default Bridge vs User-Defined Bridge

Port Mapping Syntax

CLI Command Reference

Critical Warnings

ALWAYS use user-defined bridge networks instead of the default bridge. The default bridge lacks DNS resolution, proper isolation, and per-network configuration.

NEVER use --link for container communication -- it is legacy and deprecated. Use user-defined networks with DNS-based service discovery instead.

NEVER publish ports with -p 0.0.0.0:PORT:PORT on production hosts unless external access is intended. Use -p 127.0.0.1:PORT:PORT to restrict to localhost.

ALWAYS use --internal flag when creating networks that should have no external (internet) access. This prevents accidental data exfiltration.

NEVER rely on container IP addresses for communication -- IPs change on container restart. ALWAYS use container names or network aliases for DNS-based discovery.

Network Driver Decision Tree

Need container networking?
├── No → use --network none
└── Yes
    ├── Need host-level performance (no NAT overhead)?
    │   └── Yes → use --network host
    ├── Need multi-host communication (Swarm)?
    │   └── Yes → use overlay driver
    │       ├── Need standalone container access? → --attachable
    │       └── Need encryption? → --opt encrypted
    ├── Need container to appear as physical device on LAN?
    │   ├── Yes, one MAC per container → use macvlan
    │   └── Yes, shared MAC (VLAN) → use ipvlan
    └── Single-host container communication
        └── ALWAYS use user-defined bridge
            └── docker network create mynet

DNS Resolution

How DNS Works in User-Defined Networks

Docker runs an embedded DNS server at 127.0.0.11 for all user-defined networks. Containers resolve each other by:

1. Container name -- The --name value becomes a DNS hostname
2. Network alias -- Additional DNS names via --network-alias
3. Service name -- In Compose, the service key is the DNS name

Container A (name: web)          Container B (name: api)
    |                                |
    |--- DNS query: "api" ---------> |
    |          127.0.0.11            |
    |<-- Response: 172.20.0.3 -------|
    |                                |
    |--- HTTP GET api:8080 --------->|  (resolved via DNS)

DNS Configuration

# Custom DNS server for external resolution
docker run --dns 8.8.8.8 nginx

# Custom search domain
docker run --dns-search example.com nginx

# Custom DNS options
docker run --dns-option ndots:2 nginx

Key DNS Rules

• Default bridge: Containers inherit host /etc/resolv.conf -- NO container name resolution
• User-defined networks: Docker DNS at 127.0.0.11 -- FULL container name resolution
• Multiple networks: A container resolves names ONLY for containers on the same network
• External DNS: Queries not matching container names forward to configured upstream DNS

Network Creation and IPAM

Basic Network Creation

# Simple user-defined bridge
docker network create mynet

# Bridge with custom subnet
docker network create --driver bridge \
  --subnet=172.28.0.0/16 \
  --gateway=172.28.0.1 \
  mynet

# Bridge with custom IP allocation range
docker network create --driver bridge \
  --subnet=172.28.0.0/16 \
  --ip-range=172.28.5.0/24 \
  --gateway=172.28.5.254 \
  mynet

# IPv6-enabled network
docker network create --ipv6 --subnet 2001:db8::/64 v6net

# Internal network (no external access)
docker network create --internal isolated

IPAM Configuration

Static IP Assignment

# Assign static IP to container (requires user-defined network with subnet)
docker network connect --ip 172.28.5.10 mynet myapp
docker run --network mynet --ip 172.28.5.10 nginx

Container-to-Container Communication

Same Network (Recommended)

# Create network
docker network create app-net

# Run containers on the same network
docker run -d --name db --network app-net postgres:16
docker run -d --name api --network app-net \
  -e DATABASE_URL=postgresql://db:5432/mydb myapp

# api can reach db by name "db" via DNS

Multiple Networks for Isolation

# Frontend network (web + api)
docker network create frontend

# Backend network (api + db)
docker network create backend

# Web server -- only frontend
docker run -d --name web --network frontend -p 80:80 nginx

# API server -- both networks (bridge between frontend and backend)
docker run -d --name api --network frontend myapi
docker network connect backend api

# Database -- only backend (unreachable from web)
docker run -d --name db --network backend postgres:16

Network Aliases

# Multiple containers behind one DNS name (client-side load balancing)
docker run -d --network mynet --network-alias search elasticsearch:8
docker run -d --network mynet --network-alias search elasticsearch:8

# Both containers resolve via "search" -- Docker round-robins responses

Port Exposure Rules

• Containers on the SAME user-defined network expose ALL ports to each other automatically
• -p flag is ONLY needed for access from outside the Docker network (host or external)
• The EXPOSE instruction in Dockerfile is documentation only -- it does NOT publish ports

Docker Compose Networking

Default Behavior

Compose automatically creates a network named {project}_default and connects all services:

# All services can reach each other by service name
services:
  web:
    image: nginx
    ports:
      - "80:80"      # Published to host
  api:
    image: myapi
    # Reaches db via hostname "db" automatically
  db:
    image: postgres:16
    # No ports published -- only accessible within Compose network

Custom Networks in Compose

services:
  web:
    image: nginx
    networks:
      - frontend
  api:
    image: myapi
    networks:
      - frontend
      - backend
  db:
    image: postgres:16
    networks:
      - backend

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true    # No external access

External Networks

# Use pre-existing network (MUST exist before docker compose up)
networks:
  existing-net:
    external: true

Network Inspection and Debugging

Inspect Commands

# List all networks
docker network ls
docker network ls --filter driver=bridge

# Inspect network details (containers, IPAM, options)
docker network inspect mynet

# Get containers on a network
docker network inspect --format='{{range .Containers}}{{.Name}} {{end}}' mynet

# Get container IP address
docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' myapp

Debug Connectivity

# Test DNS resolution from inside container
docker exec myapp nslookup other-container

# Test connectivity
docker exec myapp ping -c 2 other-container

# Check container's DNS config
docker exec myapp cat /etc/resolv.conf

# Check which networks a container belongs to
docker inspect --format='{{range $k, $v := .NetworkSettings.Networks}}{{$k}} {{end}}' myapp

Reference Links

• references/drivers.md -- All network driver details, options, and use cases
• references/examples.md -- Network creation, multi-container networking, isolation patterns
• references/anti-patterns.md -- Common networking mistakes and how to avoid them

Official Sources

• https://docs.docker.com/engine/network/
• https://docs.docker.com/engine/network/drivers/bridge/
• https://docs.docker.com/engine/network/drivers/overlay/
• https://docs.docker.com/engine/network/drivers/host/
• https://docs.docker.com/engine/network/drivers/macvlan/
• https://docs.docker.com/engine/network/drivers/ipvlan/
• https://docs.docker.com/compose/how-tos/networking/