Concepts
This section describes some of the essential concepts with which you will need to be familiar before continuing to the example deployment scenarios.
The following concepts are described:
Host
For the purposes of this documentation a host is an installation of the Linux operating system that is running an instance of the Docker Engine. The host may be executing directly on bare hardware or inside a virtual machine.
Peer
A peer is a running instance of Weave Net, typically one per host.
Peer Name
Weave Net peers are identified by a 48-bit value formatted like an
ethernet MAC address, for example, 01:23:45:67:89:ab. The ‘peer
name’ is used for various purposes:
- Routing of packets between containers on the overlay network
- Recording the origin peer of DNS entries
- Recording ownership of IP address ranges
While it is desirable for the peer name to remain stable across restarts, it is essential that it is unique. If two or more peers share the same name chaos will ensue, which includes but is not limited to double allocation of addresses and the inability to route packets on the overlay network.
When the router is launched on a host, it derives its peer name in order of preference:
- From the command line, where the user is responsible for uniqueness and stability
- From Weave’s data volume container (
weavedb), if you upgrade your Weave Net install from a pre-1.9 version and the underlying machine IDs still match. - From a unique machine ID. This is generated by combining IDs from systemd or D-Bus with the BIOS product UUID or hypervisor UUID. Most machines have one or two of these IDs, and the combination is practically stable across restarts unless a user re-generates it.
- If none of the machine IDs are found, a random value is generated. This is practically unique across different physical hardware and cloned VMs but not stable across restarts.
The appropriate strategy for assigning peer names depends on the type and method of your particular deployment and is discussed in more detail below.
Peer Discovery
Peer discovery is a mechanism that allows peers to learn about new Weave Net hosts from existing peers without being explicitly told. Peer discovery is enabled by default.
Network Partition
A network partition is a transient condition whereby some arbitrary subsets of peers are unable to communicate with each other for the duration - perhaps because a network switch has failed, or a fibre optic line severed. Weave Net is designed to allow peers and their containers to make maximum safe progress under conditions of partition, healing automatically once the partition is over.
IP Address Manager (IPAM)
IPAM is the subsystem responsible for dividing up a large contiguous block of IP addresses (known as the IP allocation range) amongst peers so that individual addresses may be uniquely assigned to containers anywhere on the overlay network.
When a new network is formed an initial division of the IP allocation range must be made. Two (mutually exclusive) mechanisms with different tradeoffs are provided to perform this task: seeding and consensus.
Seeding
Seeding requires each peer to be told the list of peer names amongst which the address space is to be divided initially. There are some constraints and consequences:
- Every peer added to the network must receive the same seed list, for all time, or they will not be able to join together to form a single cohesive whole.
- Because the ‘product UUID’ and ‘random value’ methods of peer name assignment are unpredictable, the end user must by necessity also specify peer names.
- Even though every peer must receive the same seed, that seed does not have to include every peer in the network, nor does it have to be updated when new peers are added (in fact due to the first constraint above it may not be).
Example configurations are given in the section on deployment scenarios:
Consensus
Alternatively, when a new network is formed for the first time, peers can be configured to co-ordinate amongst themselves to automatically divide up the IP allocation range. This process is known as consensus and it requires each peer to be told the total number of expected peers (the ‘initial peer count’) in order to prevent the formation of disjoint peer groups which would, ultimately, result in duplicate IP addresses.
Example configurations are given in the section on deployment scenarios:
Observers
Finally, an option is provided to start a peer as an observer. Such peers do not require a seed peer name list or an initial peer count; instead they rely on the existence of other peers in the network which have been so configured. When an observer needs address space, it asks for it from one of the peers which partook of the initial division, triggering consensus if necessary.
Example configurations are given in the section on deployment scenarios:
Persistence
Certain information is remembered between launches of Weave Net (for example across reboots):
- The division of the IP allocation range amongst peers
- Allocation of addresses to containers
The persistence of this information is managed transparently in a volume container but can be destroyed explicitly if necessary.