aboutsummaryrefslogtreecommitdiff
path: root/doc/book/src/reference_manual/layout.md
diff options
context:
space:
mode:
authorAlex <alex@adnab.me>2022-02-07 11:51:12 +0100
committerAlex <alex@adnab.me>2022-02-07 11:51:12 +0100
commit1c0ba930b8d6aa5d97e6942852240861e6ab9bed (patch)
treecddc9af5fc2378c76fe5ef6306f807e27648b7a7 /doc/book/src/reference_manual/layout.md
parent45d6d377d2011d8fb4ceb13bb4584df97c458525 (diff)
downloadgarage-1c0ba930b8d6aa5d97e6942852240861e6ab9bed.tar.gz
garage-1c0ba930b8d6aa5d97e6942852240861e6ab9bed.zip
Reorganize documentation for new website (#213)
This PR should be merged after the new website is deployed. - [x] Rename files - [x] Add front matter section to all `.md` files in the book (necessary for Zola) - [x] Change all internal links to use Zola's linking system that checks broken links - [x] Some updates to documentation contents and organization Co-authored-by: Alex Auvolat <alex@adnab.me> Reviewed-on: https://git.deuxfleurs.fr/Deuxfleurs/garage/pulls/213 Co-authored-by: Alex <alex@adnab.me> Co-committed-by: Alex <alex@adnab.me>
Diffstat (limited to 'doc/book/src/reference_manual/layout.md')
-rw-r--r--doc/book/src/reference_manual/layout.md74
1 files changed, 0 insertions, 74 deletions
diff --git a/doc/book/src/reference_manual/layout.md b/doc/book/src/reference_manual/layout.md
deleted file mode 100644
index 80c71d60..00000000
--- a/doc/book/src/reference_manual/layout.md
+++ /dev/null
@@ -1,74 +0,0 @@
-# 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.