Weave Net implements an overlay container network that links together all containers, regardless of where the Docker hosts are running. Weave is designed to work with minimal configuration and zero application changes. So when you add a new Docker host and install Weave, the only thing you need to configure is the address of one other existing Weave router on any other Docker host.

How do you automate this initial configuration? Where does the information come from to configure the initial peer? To solve this, we have developed the Weave Discovery tool which allows Weave routers to find each other automatically.

Weave discovery retrieves and watches the list of peers in a Weave network from a discovery backend. Discovery uses this information to tell a Weave Router about new peers it must connect to, as well as peers that are not available anymore (e.g. after a host failure) and must be forgotten. Discovery also advertises the new Weave router so other peers can join it.

Discovery with Weave

A discovery backend is any kind of database where the list of peers is stored. It can be as simple as a regular file with one IP per line, or as sophisticated as a etcd database or a Zookeeper cluster. Weave Discovery uses the same backends that Docker’s Swarm discovery employs for their clustering solution, so we can even use Swarm tokens.

In the following example we will start by using a Swarm token for connecting some Weave routers. The token can be created with a simple HTTP call like this:

$ curl -X POST https://discovery-stage.hub.docker.com/v1/clusters

This will give you a discovery token. In this case we got 182d0d8c2e80b0d2a2f6ed6eb9b5effa. So we have created a backend! For each of your machines, launch Weave Net as you would usually do, with

vm1$ weave launch

and then install Discovery with

vm1$ curl -O http://git.io/vmW3z && chmod a+x discovery
vm1$ discovery join --advertise-router token://182d0d8c2e80b0d2a2f6ed6eb9b5effa

This will keep announcing the router in the discovery backend, while also trying to get any new peers for this token. This command is something like “a router in the 182d0d8c2e80b0d2a2f6ed6eb9b5effa token is reachable at, and please let me know about any new peers in this token…”

Repeat the same steps in a second machine:

vm2$ weave launch
vm2$ curl -O http://git.io/vmW3z && chmod a+x discovery
vm2$ discovery join --advertise-router token://182d0d8c2e80b0d2a2f6ed6eb9b5effa

You are done! Your Weave routers should be connected, and they should stay connected

In this example we have used a token for connecting peers and, while this can be convenient for impromptu connectivities, it is probably not the best solution for stable infrastructures. You probably want all your Weave routers to automatically join the same network when launched, so you could be better served by a persistent backend (eg, etcd://my_etcd_server/my_network) where you could keep the list of routers available in the network.

You must also be careful about the IPs that nodes announce in the discovery backend. We have taken the shortest path in our example and we have used the --advertise-router flag. This announces the IP of the device used for the default route, but this will not always be reachable from other peers. Firewalls and NATs can get in your way. In that case you will have to specify the IP manually with the --advertise flag.

In the next post we will talk about how to use Discovery for keeping a Swarm cluster connected.