aboutsummaryrefslogtreecommitdiff
path: root/doc/book/src/reference_manual
diff options
context:
space:
mode:
authorAlex Auvolat <alex@adnab.me>2021-11-09 12:24:04 +0100
committerAlex Auvolat <alex@adnab.me>2021-11-16 16:05:53 +0100
commitc94406f4282d48e2e2ac82ffb57eafaad23f7edc (patch)
tree01fe1b272e18fdae993e2207d8d3aea4a301ec56 /doc/book/src/reference_manual
parent53888995bdd7c672d2e3ab8bb6a3529195c127a9 (diff)
downloadgarage-c94406f4282d48e2e2ac82ffb57eafaad23f7edc.tar.gz
garage-c94406f4282d48e2e2ac82ffb57eafaad23f7edc.zip
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.
Diffstat (limited to 'doc/book/src/reference_manual')
-rw-r--r--doc/book/src/reference_manual/configuration.md4
-rw-r--r--doc/book/src/reference_manual/layout.md74
2 files changed, 76 insertions, 2 deletions
diff --git a/doc/book/src/reference_manual/configuration.md b/doc/book/src/reference_manual/configuration.md
index 61f7bcee..0b1e7bc7 100644
--- a/doc/book/src/reference_manual/configuration.md
+++ b/doc/book/src/reference_manual/configuration.md
@@ -133,9 +133,9 @@ These peer identifiers have the following syntax:
In the case where `rpc_public_addr` is correctly specified in the
configuration file, the full identifier of a node including IP and port can
-be obtained by running `garage node-id` and then included directly in the
+be obtained by running `garage node id` and then included directly in the
`bootstrap_peers` list of other nodes. Otherwise, only the node's public
-key will be returned by `garage node-id` and you will have to add the IP
+key will be returned by `garage node id` and you will have to add the IP
yourself.
#### `consul_host` and `consul_service_name`
diff --git a/doc/book/src/reference_manual/layout.md b/doc/book/src/reference_manual/layout.md
new file mode 100644
index 00000000..80c71d60
--- /dev/null
+++ b/doc/book/src/reference_manual/layout.md
@@ -0,0 +1,74 @@
+# Creating and updating a cluster layout
+
+The cluster layout in Garage is a table that assigns to each node a role in
+the cluster. The role of a node in Garage can either be a storage node with
+a certain capacity, or a gateway node that does not store data and is only
+used as an API entry point for faster cluster access.
+An introduction to building cluster layouts can be found in the [production deployment](/cookbook/real_world.md) page.
+
+## How cluster layouts work in Garage
+
+In Garage, a cluster layout is composed of the following components:
+
+- a table of roles assigned to nodes
+- a version number
+
+Garage nodes will always use the cluster layout with the highest version number.
+
+Garage nodes also maintain and synchronize between them a set of proposed role
+changes that haven't yet been applied. These changes will be applied (or
+canceled) in the next version of the layout
+
+The following commands insert modifications to the set of proposed role changes
+for the next layout version (but they do not create the new layout immediately):
+
+```bash
+garage layout assign [...]
+garage layout remove [...]
+```
+
+The following command can be used to inspect the layout that is currently set in the cluster
+and the changes proposed for the next layout version, if any:
+
+```bash
+garage layout show
+```
+
+The following commands create a new layout with the specified version number,
+that either takes into account the proposed changes or cancels them:
+
+```bash
+garage layout apply --version <new_version_number>
+garage layout revert --version <new_version_number>
+```
+
+The version number of the new layout to create must be 1 + the version number
+of the previous layout that existed in the cluster. The `apply` and `revert`
+commands will fail otherwise.
+
+## Warnings about Garage cluster layout management
+
+**Warning: never make several calls to `garage layout apply` or `garage layout
+revert` with the same value of the `--version` flag. Doing so can lead to the
+creation of several different layouts with the same version number, in which
+case your Garage cluster will become inconsistent until fixed.** If a call to
+`garage layout apply` or `garage layout revert` has failed and `garage layout
+show` indicates that a new layout with the given version number has not been
+set in the cluster, then it is fine to call the command again with the same
+version number.
+
+If you are using the `garage` CLI by typing individual commands in your
+shell, you shouldn't have much issues as long as you run commands one after
+the other and take care of checking the output of `garage layout show`
+before applying any changes.
+
+If you are using the `garage` CLI to script layout changes, follow the following recommendations:
+
+- Make all of your `garage` CLI calls to the same RPC host. Do not use the
+ `garage` CLI to connect to individual nodes to send them each a piece of the
+ layout changes you are making, as the changes propagate asynchronously
+ between nodes and might not all be taken into account at the time when the
+ new layout is applied.
+
+- **Only call `garage layout apply` once**, and call it **strictly after** all
+ of the `layout assign` and `layout remove` commands have returned.