Improve how node roles are assigned in Garagev0.5-beta1

- change the terminology: the network configuration becomes the role
  table, the configuration of a nodes becomes a node's role
- the modification of the role table takes place in two steps: first,
  changes are staged in a CRDT data structure. Then, once the user is
  happy with the changes, they can commit them all at once (or revert
  them).
- update documentation
- fix tests
- implement smarter partition assignation algorithm

This patch breaks the format of the network configuration: when
migrating, the cluster will be in a state where no roles are assigned.
All roles must be re-assigned and commited at once. This migration
should not pose an issue.

3 files changed, 56 insertions, 30 deletions

diff --git a/doc/book/src/cookbook/gateways.md b/doc/book/src/cookbook/gateways.md
index f1ad43e4..7b286b65 100644
--- a/doc/book/src/cookbook/gateways.md
+++ b/doc/book/src/cookbook/gateways.md
@@ -21,7 +21,9 @@ Currently it will not work with minio client. Follow issue [#64](https://git.deu
 The instructions are similar to a regular node, the only option that is different is while configuring the node, you must set the `--gateway` parameter:
 
 ```bash
-garage node configure --gateway --tag gw1 xxxx
+garage layout assign --gateway --tag gw1 <node_id>
+garage layout show    # review the changes you are making
+garage layout apply   # once satisfied, apply the changes
 ```
 
 Then use `http://localhost:3900` when a S3 endpoint is required:
@@ -29,3 +31,9 @@ Then use `http://localhost:3900` when a S3 endpoint is required:
 ```bash
 aws --endpoint-url http://127.0.0.1:3900 s3 ls
 ```
+
+If a newly added gateway node seems to not be working, do a full table resync to ensure that bucket and key list are correctly propagated:
+
+```bash
+garage repair -a --yes tables
+```
diff --git a/doc/book/src/cookbook/real_world.md b/doc/book/src/cookbook/real_world.md
index 7864274c..4b3fec2b 100644
--- a/doc/book/src/cookbook/real_world.md
+++ b/doc/book/src/cookbook/real_world.md
@@ -41,15 +41,15 @@ For our example, we will suppose the following infrastructure with IPv6 connecti
 
 ## Get a Docker image
 
-Our docker image is currently named `lxpz/garage_amd64` and is stored on the [Docker Hub](https://hub.docker.com/r/lxpz/garage_amd64/tags?page=1&ordering=last_updated).
+Our docker image is currently named `dxflrs/amd64_garage` and is stored on the [Docker Hub](https://hub.docker.com/r/dxflrs/amd64_garage/tags?page=1&ordering=last_updated).
 We encourage you to use a fixed tag (eg. `v0.4.0`) and not the `latest` tag.
 For this example, we will use the latest published version at the time of the writing which is `v0.4.0` but it's up to you
-to check [the most recent versions on the Docker Hub](https://hub.docker.com/r/lxpz/garage_amd64/tags?page=1&ordering=last_updated).
+to check [the most recent versions on the Docker Hub](https://hub.docker.com/r/dxflrs/amd64_garage/tags?page=1&ordering=last_updated).
 
 For example:
 
 ```
-sudo docker pull lxpz/garage_amd64:v0.4.0
+sudo docker pull dxflrs/amd64_garage:v0.4.0
 ```
 
 ## Deploying and configuring Garage
@@ -144,7 +144,7 @@ At this point, nodes are not yet talking to one another.
 Your output should therefore look like follows:
 
 ```
-Mercury$ garage node-id
+Mercury$ garage status
 ==== HEALTHY NODES ====
 ID                  Hostname  Address           Tag                   Zone  Capacity
 563e1ac825ee3323…   Mercury   [fc00:1::1]:3901  NO ROLE ASSIGNED
@@ -157,14 +157,14 @@ When your Garage nodes first start, they will generate a local node identifier
 (based on a public/private key pair).
 
 To obtain the node identifier of a node, once it is generated,
-run `garage node-id`.
+run `garage node id`.
 This will print keys as follows:
 
 ```bash
-Mercury$ garage node-id
+Mercury$ garage node id
 563e1ac825ee3323aa441e72c26d1030d6d4414aeb3dd25287c531e7fc2bc95d@[fc00:1::1]:3901
 
-Venus$ garage node-id
+Venus$ garage node id
 86f0f26ae4afbd59aaf9cfb059eefac844951efd5b8caeec0d53f4ed6c85f332@[fc00:1::2]:3901
 
 etc.
@@ -191,20 +191,22 @@ ID                  Hostname  Address           Tag                   Zone  Capa
 212f7572f0c89da9…   Mars      [fc00:F::1]:3901  NO ROLE ASSIGNED
 ```
 
-## Giving roles to nodes
+## Creating a cluster layout
 
 We will now inform Garage of the disk space available on each node of the cluster
 as well as the zone (e.g. datacenter) in which each machine is located.
+This information is called the **cluster layout** and consists
+of a role that is assigned to each active cluster node.
 
 For our example, we will suppose we have the following infrastructure
 (Capacity, Identifier and Zone are specific values to Garage described in the following):
 
 | Location | Name    | Disk Space | `Capacity` | `Identifier` | `Zone` |
 |----------|---------|------------|------------|--------------|--------------|
-| Paris    | Mercury | 1 To       | `2`        | `563e`     | `par1`       |
-| Paris    | Venus   | 2 To       | `4`        | `86f0`     | `par1`       |
-| London   | Earth   | 2 To       | `4`        | `6814`     | `lon1`       |
-| Brussels | Mars    | 1.5 To     | `3`        | `212f`     | `bru1`       |
+| Paris    | Mercury | 1 To       | `10`       | `563e`     | `par1`       |
+| Paris    | Venus   | 2 To       | `20`       | `86f0`     | `par1`       |
+| London   | Earth   | 2 To       | `20`       | `6814`     | `lon1`       |
+| Brussels | Mars    | 1.5 To     | `15`       | `212f`     | `bru1`       |
 
 #### Node identifiers
 
@@ -239,13 +241,9 @@ in order to provide high availability despite failure of a zone.
 
 Garage reasons on an abstract metric about disk storage that is named the *capacity* of a node.
 The capacity configured in Garage must be proportional to the disk space dedicated to the node.
-Due to the way the Garage allocation algorithm works, capacity values must
-be **integers**, and must be **as small as possible**, for instance with
-1 representing the size of your smallest server.
 
-Here we chose that 1 unit of capacity = 0.5 To, so that we can express servers of size
-1 To and 2 To, as wel as the intermediate size 1.5 To, with the integer values 2, 4 and
-3 respectively (see table above).
+Capacity values must be **integers** but can be given any signification.
+Here we chose that 1 unit of capacity = 100 GB.
 
 Note that the amount of data stored by Garage on each server may not be strictly proportional to
 its capacity value, as Garage will priorize having 3 copies of data in different zones,
@@ -257,13 +255,29 @@ have 66% chance of being stored by Venus and 33% chance of being stored by Mercu
 
 Given the information above, we will configure our cluster as follow:
 
+```bash
+garage layout assign -z par1 -c 10 -t mercury 563e
+garage layout assign -z par1 -c 20 -t venus 86f0
+garage layout assign -z lon1 -c 20 -t earth 6814
+garage layout assign -z bru1 -c 15 -t mars 212f
 ```
-garage node configure -z par1 -c 2 -t mercury 563e
-garage node configure -z par1 -c 4 -t venus 86f0
-garage node configure -z lon1 -c 4 -t earth 6814
-garage node configure -z bru1 -c 3 -t mars 212f
+
+At this point, the changes in the cluster layout have not yet been applied.
+To show the new layout that will be applied, call:
+
+```bash
+garage layout show
 ```
 
+Once you are satisfied with your new layout, apply it with:
+
+```bash
+garage layout apply
+```
+
+**WARNING:** if you want to use the layout modification commands in a script,
+make sure to read [this page](/reference_manual/layout.html) first.
+
 
 ## Using your Garage cluster
 
diff --git a/doc/book/src/cookbook/recovering.md b/doc/book/src/cookbook/recovering.md
index a6f15fcb..279d574c 100644
--- a/doc/book/src/cookbook/recovering.md
+++ b/doc/book/src/cookbook/recovering.md
@@ -28,8 +28,10 @@ and you should instead use one of the methods detailed in the next sections.
 
 Removing a node is done with the following command:
 
-```
-garage node remove --yes <node_id>
+```bash
+garage layout remove <node_id>
+garage layout show    # review the changes you are making
+garage layout apply   # once satisfied, apply the changes
 ```
 
 (you can get the `node_id` of the failed node by running `garage status`)
@@ -50,7 +52,7 @@ We just need to tell Garage to get back all the data blocks and store them on th
 First, set up a new HDD to store Garage's data directory on the failed node, and restart Garage using
 the existing configuration.  Then, run:
 
-```
+```bash
 garage repair -a --yes blocks
 ```
 
@@ -58,7 +60,7 @@ This will re-synchronize blocks of data that are missing to the new HDD, reading
 
 You can check on the advancement of this process by doing the following command: 
 
-```
+```bash
 garage stats -a
 ```
 
@@ -94,9 +96,11 @@ The ID of the lost node should be shown in `garage status` in the section for di
 
 Then, replace the broken node by the new one, using:
 
-```
-garage node configure --replace <old_node_id> \
-		-c <capacity> -z <zone> -t <node_tag> <new_node_id>
+```bash
+garage layout assign <new_node_id> --replace <old_node_id> \
+		-c <capacity> -z <zone> -t <node_tag>
+garage layout show    # review the changes you are making
+garage layout apply   # once satisfied, apply the changes
 ```
 
 Garage will then start synchronizing all required data on the new node.