docker-bridge-overlay is a Docker plugin providing a network driver which uses same IP addresses (IPv4 and optionally IPv6) as the built-in container's bridge network thus making the bridge available as an overlay network.

When configured correctly, this also allows you to reach containers directly from outside of the docker host on your network. Most importantly it allows you to secure communication between docker host's using good old hardware routers!

Usage

Installation

The plugin can be installed with the docker plugin install command:

$ docker plugin install git.ivasoft.cz/sw/docker-bridge-overlay:latest
Plugin "git.ivasoft.cz/sw/docker-bridge-overlay:latest" is requesting the following privileges:
 - network: [host]
 - mount: [/var/run/docker.sock]
Do you grant the above permissions? [y/N] y
release-linux-amd64: Pulling from git.ivasoft.cz/sw/docker-bridge-overlay
Digest: sha256:<some hash>
<some id>: Complete
Installed plugin git.ivasoft.cz/sw/docker-bridge-overlay:latest
$

Note: If you get an error like invalid rootfs in image configuration, try upgrading your Docker installation.

OS

Currently only linux is supported.

Network creation

In order to create a Docker network using bridge-overlay, you'll need to prepare non-overlapping IP-ranges for all docker hosts default bridge network using BIP. Using command line it could be --bip 10.14.1.1/24 --ip-masq=false The second part disables masquerading of traffic leaving the container's bridge as you want the addresses untouched so you can route it yourselves using preferabbly hardware firewall.

Once the bridge network is ready, you can create the network on every docker host:

$ docker network create --config-only --ipam-driver null my-net-config

and once on the swarm manager

$ docker network create -d git.ivasoft.cz/sw/docker-bridge-overlay:latest --scope swarm --config-from mynetconfig my-net

Note: The null IPAM driver must be used, or else Docker will try to allocate IP addresses from its choice of subnet!

Container creation

Once you've set up a network, you can create some containers:

$ docker run --rm -ti --network my-dhcp-net alpine

Or, in a Docker Compose file:

version: '3'
services:
  app:
    hostname: my-net
    image: nginx
    mac_address: 86:41:68:f8:85:b9
    networks:
      - my-net
networks:
  my-net:
    external: true

The above Compose file assumes your network has already been created with docker network create. This is the recommended way to use docker-bridge-overlay, since it allows the network to be shared among multiple compose projects and other containers.

Debugging

To read the plugin's log, do cat /var/lib/docker/plugins/*/rootfs/var/log/bridge-overlay.log (as root). You can also use docker plugin set git.ivasoft.cz/sw/docker-bridge-overlay:latest LOG_LEVEL=trace to increase log verbosity.

Implementation

Fundamentally, the network is entirely fake and exists just for the purpose that Docker's internal DNS adds the bridge IP to its records as it is now perceived as an overlay network. Nothing at the container's network gets touched and no additional interface exists in the container. Without this network containers created as part of service cannot be resolved using the tasks.service_name DNS query.