What is Overlay network driver?

Source: Dev.to

The overlay network driver creates a distributed network among multiple Docker daemon hosts. This network sits on top of (overlays) the host‑specific networks, allowing containers connected to it to communicate securely when encryption is enabled. Docker transparently handles routing of each packet to and from the correct Docker daemon host and the correct destination container.

You can create user‑defined overlay networks using docker network create, just like user‑defined bridge networks. Services or containers can be connected to more than one network at a time, but they can only communicate across networks they are both attached to.

Overlay networks are often used to connect Swarm services, but they can also connect standalone containers running on different hosts. When using standalone containers, Swarm mode is still required to establish the connection between the hosts.

Ports required for an overlay network

Before you start, ensure that participating nodes can communicate over the network. The following ports must be open on each host participating in an overlay network:

• 2377/tcp – Swarm control plane (configurable with docker swarm join --listen-addr)
• 4789/udp – Overlay traffic (configurable with docker swarm init --data-path-addr)
• 7946/tcp and 7946/udp – Node communication (not configurable)

Create an overlay network

Initialize Docker Swarm

docker swarm init

This command initializes Docker Swarm on the host and creates a Swarm manager node.

Create the overlay network

docker network create --driver overlay my-overlay-network

You can also specify a subnet and gateway:

docker network create --driver overlay \
  --subnet=10.0.1.0/24 \
  --gateway=10.0.1.1 \
  my-overlay-network

To make the network attachable by standalone containers as well as Swarm services:

docker network create --driver overlay --attachable my-overlay-network

The --attachable option enables both standalone containers and Swarm services to connect to the overlay network. Without it, only Swarm services can connect.

Verify the overlay network

docker network ls

Encrypt traffic on an overlay network

Use the --opt encrypted flag to enable IPsec encryption for the overlay network:

docker network create \
  --opt encrypted \
  --driver overlay \
  --attachable \
  my-attachable-multi-host-network

Encryption adds a non‑negligible performance penalty, so test this option before using it in production.

Attach a container to an overlay network

Adding containers to an overlay network lets them communicate without manual routing on individual Docker hosts. The hosts must be part of the same Swarm.

docker run --network multi-host-network busybox sh

Note: Due to Linux kernel limitations, overlay networks may become unstable when ~1000 containers are co‑located on the same host.

---

Related article: What is Bridge network driver?