From bf36f1f16aae763feae7bc7365741d8406f053cb Mon Sep 17 00:00:00 2001 From: Alex Auvolat Date: Tue, 6 Apr 2021 00:01:49 +0200 Subject: Update documentation --- doc/book/src/getting_started/binary.md | 6 +++--- doc/book/src/getting_started/bucket.md | 20 +++++++----------- doc/book/src/getting_started/cluster.md | 37 +++++++++++++++++---------------- 3 files changed, 30 insertions(+), 33 deletions(-) (limited to 'doc/book/src/getting_started') diff --git a/doc/book/src/getting_started/binary.md b/doc/book/src/getting_started/binary.md index 9a18babc..e48500ac 100644 --- a/doc/book/src/getting_started/binary.md +++ b/doc/book/src/getting_started/binary.md @@ -7,14 +7,14 @@ We did not test other architecture/operating system but, as long as your archite ## From Docker 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). -We encourage you to use a fixed tag (eg. `v0.1.1d`) and not the `latest` tag. -For this example, we will use the latest published version at the time of the writing which is `v0.1.1d` but it's up to you +We encourage you to use a fixed tag (eg. `v0.2.1`) and not the `latest` tag. +For this example, we will use the latest published version at the time of the writing which is `v0.2.1` 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). For example: ``` -sudo docker pull lxpz/garage_amd64:v0.1.1d +sudo docker pull lxpz/garage_amd64:v0.2.1 ``` ## From source diff --git a/doc/book/src/getting_started/bucket.md b/doc/book/src/getting_started/bucket.md index b22ce788..b4a2d81d 100644 --- a/doc/book/src/getting_started/bucket.md +++ b/doc/book/src/getting_started/bucket.md @@ -40,22 +40,18 @@ garagectl key new --name nextcloud-app-key You will have the following output (this one is fake, `key_id` and `secret_key` were generated with the openssl CLI tool): -```javascript -Key { - key_id: "GK3515373e4c851ebaad366558", - secret_key: "7d37d093435a41f2aab8f13c19ba067d9776c90215f56614adad6ece597dbb34", - name: "nextcloud-app-key", - name_timestamp: 1603280506694, - deleted: false, - authorized_buckets: [] -} +``` +Key name: nextcloud-app-key +Key ID: GK3515373e4c851ebaad366558 +Secret key: 7d37d093435a41f2aab8f13c19ba067d9776c90215f56614adad6ece597dbb34 +Authorized buckets: ``` -Check that everything works as intended (be careful, info works only with your key identifier and not with its friendly name!): +Check that everything works as intended: ``` garagectl key list -garagectl key info GK3515373e4c851ebaad366558 +garagectl key info nextcloud-app-key ``` ## Allow a key to access a bucket @@ -67,7 +63,7 @@ garagectl bucket allow \ --read \ --write nextcloud-bucket \ - --key GK3515373e4c851ebaad366558 + --key nextcloud-app-key ``` You can check at any times allowed keys on your bucket with: diff --git a/doc/book/src/getting_started/cluster.md b/doc/book/src/getting_started/cluster.md index af6e8f10..c9c18684 100644 --- a/doc/book/src/getting_started/cluster.md +++ b/doc/book/src/getting_started/cluster.md @@ -11,20 +11,20 @@ As this part is not relevant for a test cluster, you can use this one-liner to c ```bash garagectl status | grep UNCONFIGURED | grep -Po '^[0-9a-f]+' | while read id; do - garagectl node configure -d dc1 -n 10 $id + garagectl node configure -d dc1 -c 1 $id done ``` ## Real-world cluster -For our example, we will suppose we have the following infrastructure (Tokens, Identifier and Datacenter are specific values to garage described in the following): +For our example, we will suppose we have the following infrastructure (Capacity, Identifier and Datacenter are specific values to garage described in the following): -| Location | Name | Disk Space | `Tokens` | `Identifier` | `Datacenter` | -|----------|---------|------------|----------|--------------|--------------| -| Paris | Mercury | 1 To | `100` | `8781c5` | `par1` | -| Paris | Venus | 2 To | `200` | `2a638e` | `par1` | -| London | Earth | 2 To | `200` | `68143d` | `lon1` | -| Brussels | Mars | 1.5 To | `150` | `212f75` | `bru1` | +| Location | Name | Disk Space | `Capacity` | `Identifier` | `Datacenter` | +|----------|---------|------------|------------|--------------|--------------| +| Paris | Mercury | 1 To | `2` | `8781c5` | `par1` | +| Paris | Venus | 2 To | `4` | `2a638e` | `par1` | +| London | Earth | 2 To | `4` | `68143d` | `lon1` | +| Brussels | Mars | 1.5 To | `3` | `212f75` | `bru1` | ### Identifier @@ -45,14 +45,15 @@ garagectl status It will display the IP address associated with each node; from the IP address you will be able to recognize the node. -### Tokens +### Capacity -Garage reasons on an arbitrary metric about disk storage that is named "tokens". -The number of tokens must be proportional to the disk space dedicated to the node. -Additionaly, ideally the number of tokens must be in the order of magnitude of 100 -to provide a good trade-off between data load balancing and performances (*this sentence must be verified, it may be wrong*). +Garage reasons on an arbitrary 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. +Additionaly, the capacity values used in Garage should be as small as possible, with +1 ideally representing the size of your smallest server. -Here we chose 1 token = 10 Go but you are free to select the value that best fit your needs. +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. ### Datacenter @@ -65,8 +66,8 @@ Behind the scene, garage will try to store the same data on different sites to p Given the information above, we will configure our cluster as follow: ``` -garagectl node configure --datacenter par1 -n 100 -t mercury 8781c5 -garagectl node configure --datacenter par1 -n 200 -t venus 2a638e -garagectl node configure --datacenter lon1 -n 200 -t earth 68143d -garagectl node configure --datacenter bru1 -n 150 -t mars 212f75 +garagectl node configure --datacenter par1 -c 2 -t mercury 8781c5 +garagectl node configure --datacenter par1 -c 4 -t venus 2a638e +garagectl node configure --datacenter lon1 -c 4 -t earth 68143d +garagectl node configure --datacenter bru1 -c 3 -t mars 212f75 ``` -- cgit v1.2.3