💦 FULL SET: Engine/network/drivers/overlay - Uncensored 2025

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, in the same way that you can create user-defined bridge networks. Services or containers can be connected to more than one network at a time. Services or containers can only communicate across networks they're each connected to.

Overlay networks are often used to create a connection between Swarm services, but you can also use it to connect standalone containers running on different hosts. When using standalone containers, it's still required that you use Swarm mode to establish a connection between the hosts.

This page describes overlay networks in general, and when used with standalone containers. For information about overlay for Swarm services, see Manage Swarm service networks.

Requirements

Docker hosts must be part of a swarm to use overlay networks, even when connecting standalone containers. The following ports must be open between participating hosts:

• 2377/tcp: Swarm control plane (configurable)
• 4789/udp: Overlay traffic (configurable)
• 7946/tcp and 7946/udp: Node communication (not configurable)

Create an overlay network

The following table lists the ports that need to be open to each host participating in an overlay network:

To create an overlay network that containers on other Docker hosts can connect to, run the following command:

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

You can specify the IP address range, subnet, gateway, and other options. See docker network create --help for details.

Encrypt traffic on an overlay network

Use the --opt encrypted flag to encrypt the application data transmitted over the overlay network:

This enables IPsec encryption at the level of the Virtual Extensible LAN (VXLAN). This encryption imposes a non-negligible performance penalty, so you should test this option before using it in production.

Warning

Don't attach Windows containers to encrypted overlay networks.

Overlay network encryption isn't supported on Windows. Swarm doesn't report an error when a Windows host attempts to connect to an encrypted overlay network, but networking for the Windows containers is affected as follows:

• Windows containers can't communicate with Linux containers on the network
• Data traffic between Windows containers on the network isn't encrypted

Attach a container to an overlay network

Adding containers to an overlay network gives them the ability to communicate with other containers without having to set up routing on the individual Docker daemon hosts. A prerequisite for doing this is that the hosts have joined the same Swarm.

To join an overlay network named multi-host-network with a busybox container:

Note

This only works if the overlay network is attachable (created with the --attachable flag).

Container discovery

Publishing ports of a container on an overlay network opens the ports to other containers on the same network. Containers are discoverable by doing a DNS lookup using the container name.

Connection limit for overlay networks

Due to limitations set by the Linux kernel, overlay networks become unstable and inter-container communications may break when 1000 containers are co-located on the same host.

For more information about this limitation, see moby/moby#44973.

Usage examples

This section provides hands-on examples for working with overlay networks. These examples cover swarm services and standalone containers on multiple Docker hosts.

Prerequisites

All examples require at least a single-node swarm. Initialize one by running docker swarm init on the host. You can run these examples on multi-node swarms as well.

Use the default overlay network

This example shows how the default overlay network works with swarm services. You'll create an nginx service and examine the network from the service containers' perspective.

Prerequisites for multi-node setup

This walkthrough requires three Docker hosts that can communicate with each other on the same network with no firewall blocking traffic between them:

• manager: Functions as both manager and worker
• worker-1: Functions as worker only
• worker-2: Functions as worker only

If you don't have three hosts available, you can set up three virtual machines on a cloud provider with Docker installed.

Create the swarm

1. On manager, initialize the swarm. If the host has one network interface, the --advertise-addr flag is optional:

   Save the join token displayed for use with workers.

2. On worker-1, join the swarm:

3. On worker-2, join the swarm:

4. On manager, list all nodes:

   Filter by role if needed:

5. List Docker networks on all hosts. Each now has an overlay network called ingress and a bridge network called docker_gwbridge:

The docker_gwbridge connects the ingress network to the Docker host's network interface. If you create services without specifying a network, they connect to ingress. It's recommended to use separate overlay networks for each application or group of related applications.

Create the services

1. On manager, create a new overlay network:

   The overlay network is automatically created on worker nodes when they run service tasks that need it.

2. On manager, create a 5-replica Nginx service connected to nginx-net:

   Note

   Services can only be created on a manager.

   The default ingress publish mode means you can browse to port 80 on any node and connect to one of the 5 service tasks, even if no tasks run on that node.

3. Monitor service creation progress:

4. Inspect the nginx-net network on all hosts. The Containers section lists all service tasks connected to the overlay network from that host.

5. From manager, inspect the service:

   Notice the information about ports and endpoints.

6. Create a second network and update the service to use it:

7. Verify the update completed:

   Inspect both networks to verify containers moved from nginx-net to nginx-net-2.

   Note

   Overlay networks are automatically created on swarm worker nodes as needed, but aren't automatically removed.

8. Clean up:

Use a user-defined overlay network

This example shows the recommended approach for production services using custom overlay networks.

Prerequisites

This assumes the swarm is already set up and you're on a manager node.

Steps

1. Create a user-defined overlay network:

2. Start a service using the overlay network, publishing port 80 to port 8080:

3. Verify the service task is connected to the network:

   Check the Containers section for the my-nginx service task.

4. Clean up:

Use an overlay network for standalone containers

This example demonstrates DNS container discovery between standalone containers on different Docker hosts using an overlay network.

Prerequisites

You need two Docker hosts that can communicate with each other with the following ports open between them:

• TCP port 2377
• TCP and UDP port 7946
• UDP port 4789

This example refers to the hosts as host1 and host2.

Steps

1. Set up the swarm:

   On host1, initialize a swarm:

   On host2, join the swarm using the token from the previous output:

   If the join fails, run docker swarm leave --force on host2, verify network and firewall settings, and try again.

2. On host1, create an attachable overlay network:

   Note the returned network ID.

3. On host1, start an interactive container that connects to test-net:

4. On host2, list available networks. Notice that test-net doesn't exist yet:

5. On host2, start a detached, interactive container that connects to test-net:

   Note

   Automatic DNS container discovery only works with unique container names.

6. On host2, verify that test-net was created with the same network ID as on host1:

7. On host1, ping alpine2 from within alpine1:

   The two containers communicate over the overlay network connecting the two hosts. You can also run another container on host2 and ping alpine1:

8. On host1, close the alpine1 session (which stops the container):

9. Clean up. You must stop and remove containers on each host independently:

   On host2:

   When you stop alpine2, test-net disappears from host2.

   On host1:

Next steps

• Learn about networking from the container's point of view
• Learn about standalone bridge networks
• Learn about Macvlan networks