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/cookbook/index.md | 2 +- doc/book/src/cookbook/recovering.md | 2 +- doc/book/src/getting_started/binary.md | 6 +++--- doc/book/src/getting_started/bucket.md | 20 +++++++----------- doc/book/src/getting_started/cluster.md | 37 +++++++++++++++++---------------- 5 files changed, 32 insertions(+), 35 deletions(-) diff --git a/doc/book/src/cookbook/index.md b/doc/book/src/cookbook/index.md index d7a51065..26ec68bb 100644 --- a/doc/book/src/cookbook/index.md +++ b/doc/book/src/cookbook/index.md @@ -2,4 +2,4 @@ A cookbook, when you cook, is a collection of recipes. Similarly, Garage's cookbook contains a collection of recipes that are known to works well! -This chapter could also be referred as "Tutorials" or "Best practises". +This chapter could also be referred as "Tutorials" or "Best practices". diff --git a/doc/book/src/cookbook/recovering.md b/doc/book/src/cookbook/recovering.md index 9dc42ec0..fcb0b7d8 100644 --- a/doc/book/src/cookbook/recovering.md +++ b/doc/book/src/cookbook/recovering.md @@ -8,7 +8,7 @@ Fear not! For Garage is fully equipped to handle drive failures, in most common With nodes dispersed in 3 datacenters or more, here are the guarantees Garage provides with the default replication strategy (3 copies of all data, which is the recommended value): -- The cluster remains fully functionnal as long as the machines that fail are in only one datacenter. This includes a whole datacenter going down due to power/Internet outage. +- The cluster remains fully functional as long as the machines that fail are in only one datacenter. This includes a whole datacenter going down due to power/Internet outage. - No data is lost as long as the machines that fail are in at most two datacenters. Of course this only works if your Garage nodes are correctly configured to be aware of the datacenter in which they are located. 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