From a657e25a81ce322bc7cbbd0b2bc7cf30701f1dd7 Mon Sep 17 00:00:00 2001 From: Adam Harrison Date: Tue, 12 Apr 2016 15:52:34 +0100 Subject: [PATCH] Update documentation --- site/ipam.md | 55 ++++++++++++++++++++++++++-------------------------- 1 file changed, 28 insertions(+), 27 deletions(-) diff --git a/site/ipam.md b/site/ipam.md index 4dfca0ae..03895800 100644 --- a/site/ipam.md +++ b/site/ipam.md @@ -14,7 +14,7 @@ addresses in multiple subnets. The following automatic IP address management topics are discussed: * [Initializing Peers on a Weave Network](#initialization) - * [`--init-peer-count` and How Quorum is Achieved](#quorum) + * [`--ipalloc-init:consensus` and How Quorum is Achieved](#quorum) * [Forcing Consensus](#forcing-consensus) * [Choosing an Allocation Range](#range) @@ -22,21 +22,20 @@ The following automatic IP address management topics are discussed: ### Initializing Peers on a Weave Network -There are two options for initializing IPAM - with a statically -configured seed or automatically via one-off consensus. The two -options have different tradeoffs, so pick the one that suits your -deployment best. +Three initialization strategies are available: seed, consensus and +observer. These options have different tradeoffs, so pick the one that +suits your deployment best. #### Via Seed Configuration via seed requires you to provide a list of peer names -(via the `--ipam-seed` parameter) amongst which the address space will -be shared initially - this means that you will also have to specify -peer names explicitly on launch: +(via the `--ipalloc-init seed=` parameter) amongst which the address +space will be shared initially - this means that you will also have to +specify peer names explicitly on launch: - host1$ weave launch --name ::1 --ipam-seed ::1,::2,::3 - host2$ weave launch --name ::2 --ipam-seed ::1,::2,::3 - host3$ weave launch --name ::3 --ipam-seed ::1,::2,::3 + host1$ weave launch --name ::1 --ipalloc-init seed=::1,::2,::3 + host2$ weave launch --name ::2 --ipalloc-init seed=::1,::2,::3 + host3$ weave launch --name ::3 --ipalloc-init seed=::1,::2,::3 In this configuration each peer knows in advance how the address space has been divided up, and will be able to perform allocations from the @@ -52,7 +51,7 @@ for you as well. However, in order for Weave Net to form a single consensus reliably you must now instead tell each peer how many peers there are in total either by listing them as target peers or using the -`--init-peer-count` parameter. +`--ipalloc-init consensus=` parameter. Just once, when the first automatic IP address allocation is requested in the whole network, Weave Net needs a majority of peers to be present in @@ -61,7 +60,7 @@ inconsistency, for example, the same IP address being allocated to two different containers. Therefore, you must either supply the list of all peers in the network at `weave launch` or add the -`--init-peer-count` flag to specify how many peers there will be. +`--ipalloc-init consensus=` flag to specify how many peers there will be. To illustrate, suppose you have three hosts, accessible to each other as `$HOST1`, `$HOST2` and `$HOST3`. You can start Weave Net on those three @@ -74,11 +73,11 @@ hosts using these three commands: Or, if it is not convenient to name all the other hosts at launch time, you can pass the number of peers like this: - host1$ weave launch --init-peer-count 3 - host2$ weave launch --init-peer-count 3 $HOST3 - host3$ weave launch --init-peer-count 3 $HOST2 + host1$ weave launch --ipalloc-init consensus=3 + host2$ weave launch --ipalloc-init consensus=3 $HOST3 + host3$ weave launch --ipalloc-init consensus=3 $HOST2 -The consensus mechanism used to determine a majority, transitions +The consensus mechanism used to determine a majority transitions through three states: 'deferred', 'waiting' and 'achieved': * 'deferred' - no allocation requests or claims have been made yet; @@ -89,21 +88,23 @@ through three states: 'deferred', 'waiting' and 'achieved': themselves successfully * 'achieved' - consensus achieved; allocations proceed normally -Finally, some (but never all) peers can be launched as consensus -observers rather than participants by specifying the `--observer` -option: +#### Via Observation - host4$ weave launch --observer $HOST3 +Finally, some (but never all) peers can be launched as observers +by specifying the `--ipalloc-init observer` option: -You do not need to specify an initial peer count to such peers. This -can be useful to add ephemeral peers to an existing fixed cluster (for -example in response to a scale-out event) without worrying about + host4$ weave launch --ipalloc-init observer $HOST3 + +You do not need to specify an initial peer count or seed to such +peers. This can be useful to add peers to an existing fixed cluster +(for example in response to a scale-out event) without worrying about adjusting initial peer counts accordingly. -#### `--init-peer-count` and How Quorum is Achieved +#### `--ipalloc-init consensus=` and How Quorum is Achieved -Normally it isn't a problem to over-estimate `--init-peer-count`, but if you supply -a number that is too small, then multiple independent groups may form. +Normally it isn't a problem to over-estimate the value supplied to +`--ipalloc-init consensus=`, but if you supply a number that is too +small, then multiple independent groups may form. Weave Net uses the estimate of the number of peers at initialization to compute a majority or quorum number - specifically floor(n/2) + 1.