diff options
Diffstat (limited to 'doc/book/src/reference_manual')
| -rw-r--r-- | doc/book/src/reference_manual/configuration.md | 4 | ||||
| -rw-r--r-- | doc/book/src/reference_manual/layout.md | 74 |
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. |