Overlay Network

Docker hub

A multi-host Docker network driver that spans multiple Docker hosts, enabling containers on different machines to communicate as if on the same network. Used in Docker Swarm and as the conceptual foundation for understanding Kubernetes CNI networking.

Overlay Network — Connecting Containers Across Multiple Hosts

What Is an Overlay Network in Simple Terms?

A bridge network connects containers on the same host. An overlay network connects containers across multiple hosts — containers running on different physical or virtual machines communicate as if they are on the same local network, with Docker handling all the routing transparently.

Overlay networks use VXLAN (Virtual Extensible LAN) to encapsulate container traffic inside UDP packets that travel across the real network between hosts.

◈ DIAGRAM

+------------------+      +------------------+
| Host 1           |      | Host 2           |
|                  |      |                  |
| +----------+     |      | +----------+     |
| | api      |     |      | | worker   |     |
| | 10.0.0.2 |     |      | | 10.0.0.3 |     |
| +-----+----+     |      | +-----+----+     |
|       |          |      |       |          |
|  overlay network |=====>|  overlay network  |
|  VXLAN tunnel    |      |  VXLAN tunnel     |
+------------------+      +------------------+
 
api pings 10.0.0.3 -> VXLAN encapsulates -> travels across real network
-> Host 2 decapsulates -> delivers to worker
Containers see a flat network — VXLAN is invisible to them

Creating and Using Overlay Networks

Bash

# Overlay networks require Docker Swarm mode
docker swarm init
 
# Create an overlay network
docker network create \
  --driver overlay \
  --attachable \
  payment-overlay
# --attachable: allows standalone containers (not just Swarm services) to join
 
# Deploy a Swarm service on the overlay network
docker service create \
  --name payment-api \
  --network payment-overlay \
  registry.razorpay.in/payment-api:v3.1.0
 
# Services on the same overlay network find each other by service name
# Docker's built-in load balancing distributes traffic across replicas

Encrypted Overlay Networks

Bash

# Create encrypted overlay (traffic encrypted with AES-GCM)
docker network create \
  --driver overlay \
  --opt encrypted \
  --attachable \
  secure-payment-overlay
# All traffic between containers encrypted
# Small performance overhead (~10%)

Overlay vs Bridge — When to Use Each

Need	Bridge	Overlay
Single host containers	Yes	No need
Multiple hosts	Cannot	Yes
Docker Swarm services	No	Yes
Kubernetes (CNI)	No	Similar concept

Connection to Kubernetes

Kubernetes CNI plugins (Calico, Cilium, Flannel) implement the same concept as Docker overlay networks — containers on different nodes communicate as if on the same flat network. Understanding Docker overlay networks makes Kubernetes pod networking immediately intuitive.

Remember
Overlay networks require Docker Swarm mode. If you are not using Swarm, you cannot create overlay networks — use bridge networks for single-host and look at Kubernetes for multi-host orchestration.

Frequently Asked Questions

How does a Docker overlay network let containers on different hosts communicate as if local?

An overlay network encapsulates container traffic inside VXLAN packets, tunneling it across the underlying physical or cloud network between Docker hosts participating in a Swarm cluster. Each container gets an IP on the overlay's private subnet, and Docker's embedded DNS resolves service names to those IPs, so a container on Host A can reach a container on Host B by service name exactly as it would reach a container on the same host, without either host needing routes configured for the overlay subnet.

Why is understanding Docker overlay networks useful even for teams running Kubernetes instead of Swarm?

Kubernetes doesn't ship its own networking implementation — CNI plugins like Flannel, Calico, and Cilium solve the same cross-host container networking problem, and several of them (Flannel's VXLAN backend, for instance) use the same encapsulation concept as Docker overlay networks. Understanding overlay networking in the simpler Swarm context — encapsulation overhead, the need for open UDP ports between hosts, MTU considerations — transfers directly to debugging CNI-level networking issues in a Kubernetes cluster.