Overlay Networks: Encryption Warnings, Container Attachment, Discovery, and Limitations

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: ```console $ docker run --network multi-host-network busybox sh ``` > [!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. | Flag value | Description | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-p 8080:80` | Map TCP port 80 in the container to port `8080` on the overlay network. | | `-p 8080:80/udp` | Map UDP port 80 in the container to port `8080` on the overlay network. | | `-p 8080:80/sctp` | Map SCTP port 80 in the container to port `8080` on the overlay network. | | `-p 8080:80/tcp -p 8080:80/udp` | Map TCP port 80 in the container to TCP port `8080` on the overlay network, and map UDP port 80 in the container to UDP port `8080` on the overlay network. | ## 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](https://github.com/moby/moby/issues/44973#issuecomment-1543747718). ## Next steps - Go through the [overlay networking tutorial](/manuals/engine/network/tutorials/overlay.md) - Learn about [networking from the container's point of view](../_index.md) - Learn about [standalone bridge networks](bridge.md) - Learn about [Macvlan networks](macvlan.md)

Encryption of overlay networks via IPsec/VXLAN incurs a performance penalty, and is not supported for Windows containers. Attaching containers to overlay networks enables communication without manual routing, requiring hosts to be in the same Swarm and the network to be created with the `--attachable` flag. Containers can be discovered via DNS lookup by container name. Publishing ports on the network allows access from other containers on the same network. A Linux kernel limitation can cause instability if more than 1000 containers are co-located on the same host. Additional learning resources are suggested, including tutorials and information on other network types.