micropelago/garage
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request 'documentation updates for v0.9.0' (#647) from doc-updates into main

Browse Source 
Reviewed-on: https://git.deuxfleurs.fr/Deuxfleurs/garage/pulls/647
This commit is contained in:
Alex 2023-10-11 12:57:37 +00:00
commit d8263fdf92
3 changed files with 58 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
doc/book/cookbook/real-world.md
View File

@ -19,9 +19,10 @@ To run a real-world deployment, make sure the following conditions are met:
- You have at least three machines with sufficient storage space available. - You have at least three machines with sufficient storage space available.
- Each machine has a public IP address which is reachable by other machines. It - Each machine has an IP address which makes it directly reachable by all other machines.
is highly recommended that you use IPv6 for this end-to-end connectivity. If In many cases, nodes will be behind a NAT and will not each have a public
IPv6 is not available, then using a mesh VPN such as IPv4 addresses. In this case, is recommended that you use IPv6 for this
end-to-end connectivity if it is available. Otherwise, using a mesh VPN such as
[Nebula](https://github.com/slackhq/nebula) or [Nebula](https://github.com/slackhq/nebula) or
[Yggdrasil](https://yggdrasil-network.github.io/) are approaches to consider [Yggdrasil](https://yggdrasil-network.github.io/) are approaches to consider
in addition to building out your own VPN tunneling. in addition to building out your own VPN tunneling.
@ -42,7 +43,7 @@ For our example, we will suppose the following infrastructure with IPv6 connecti
| Brussels | Mars | fc00:F::1 | 1.5 TB | | Brussels | Mars | fc00:F::1 | 1.5 TB |
Note that Garage will **always** store the three copies of your data on nodes at different Note that Garage will **always** store the three copies of your data on nodes at different
locations. This means that in the case of this small example, the available capacity locations. This means that in the case of this small example, the usable capacity
of the cluster is in fact only 1.5 TB, because nodes in Brussels can't store more than that. of the cluster is in fact only 1.5 TB, because nodes in Brussels can't store more than that.
This also means that nodes in Paris and London will be under-utilized. This also means that nodes in Paris and London will be under-utilized.
To make better use of the available hardware, you should ensure that the capacity To make better use of the available hardware, you should ensure that the capacity
@ -84,14 +85,14 @@ to store 2 TB of data in total.
## Get a Docker image ## Get a Docker image
Our docker image is currently named `dxflrs/garage` and is stored on the [Docker Hub](https://hub.docker.com/r/dxflrs/garage/tags?page=1&ordering=last_updated). Our docker image is currently named `dxflrs/garage` and is stored on the [Docker Hub](https://hub.docker.com/r/dxflrs/garage/tags?page=1&ordering=last_updated).
We encourage you to use a fixed tag (eg. `v0.8.0`) and not the `latest` tag. We encourage you to use a fixed tag (eg. `v0.9.0`) and not the `latest` tag.
For this example, we will use the latest published version at the time of the writing which is `v0.8.0` but it's up to you For this example, we will use the latest published version at the time of the writing which is `v0.9.0` but it's up to you
to check [the most recent versions on the Docker Hub](https://hub.docker.com/r/dxflrs/garage/tags?page=1&ordering=last_updated). to check [the most recent versions on the Docker Hub](https://hub.docker.com/r/dxflrs/garage/tags?page=1&ordering=last_updated).
For example: For example:
``` ```
sudo docker pull dxflrs/garage:v0.8.0 sudo docker pull dxflrs/garage:v0.9.0
``` ```
## Deploying and configuring Garage ## Deploying and configuring Garage
@ -156,12 +157,13 @@ docker run \
-v /etc/garage.toml:/etc/garage.toml \ -v /etc/garage.toml:/etc/garage.toml \
-v /var/lib/garage/meta:/var/lib/garage/meta \ -v /var/lib/garage/meta:/var/lib/garage/meta \
-v /var/lib/garage/data:/var/lib/garage/data \ -v /var/lib/garage/data:/var/lib/garage/data \
dxflrs/garage:v0.8.0 dxflrs/garage:v0.9.0
``` ```
It should be restarted automatically at each reboot. With this command line, Garage should be started automatically at each boot.
Please note that we use host networking as otherwise Docker containers Please note that we use host networking as otherwise the network indirection
can not communicate with IPv6. added by Docker would prevent Garage nodes from communicating with one another
(especially if using IPv6).
If you want to use `docker-compose`, you may use the following `docker-compose.yml` file as a reference: If you want to use `docker-compose`, you may use the following `docker-compose.yml` file as a reference:
@ -169,7 +171,7 @@ If you want to use `docker-compose`, you may use the following `docker-compose.y
version: "3" version: "3"
services: services:
garage: garage:
image: dxflrs/garage:v0.8.0 image: dxflrs/garage:v0.9.0
network_mode: "host" network_mode: "host"
restart: unless-stopped restart: unless-stopped
volumes: volumes:
@ -178,10 +180,12 @@ services:
- /var/lib/garage/data:/var/lib/garage/data - /var/lib/garage/data:/var/lib/garage/data
``` ```
Upgrading between Garage versions should be supported transparently, If you wish to upgrade your cluster, make sure to read the corresponding
but please check the relase notes before doing so! [documentation page](@/documentation/operations/upgrading.md) first, as well as
To upgrade, simply stop and remove this container and the documentation relevant to your version of Garage in the case of major
start again the command with a new version of Garage. upgrades. With the containerized setup proposed here, the upgrade process
will require stopping and removing the existing container, and re-creating it
with the upgraded version.
## Controling the daemon ## Controling the daemon
@ -265,12 +269,12 @@ of a role that is assigned to each active cluster node.
For our example, we will suppose we have the following infrastructure For our example, we will suppose we have the following infrastructure
(Capacity, Identifier and Zone are specific values to Garage described in the following): (Capacity, Identifier and Zone are specific values to Garage described in the following):
| Location | Name | Disk Space | `Capacity` | `Identifier` | `Zone` | | Location | Name | Disk Space | Identifier | Zone (`-z`) | Capacity (`-c`) |
|----------|---------|------------|------------|--------------|--------------| |----------|---------|------------|------------|-------------|-----------------|
| Paris | Mercury | 1 TB | `10` | `563e` | `par1` | | Paris | Mercury | 1 TB | `563e` | `par1` | `1T` |
| Paris | Venus | 2 TB | `20` | `86f0` | `par1` | | Paris | Venus | 2 TB | `86f0` | `par1` | `2T` |
| London | Earth | 2 TB | `20` | `6814` | `lon1` | | London | Earth | 2 TB | `6814` | `lon1` | `2T` |
| Brussels | Mars | 1.5 TB | `15` | `212f` | `bru1` | | Brussels | Mars | 1.5 TB | `212f` | `bru1` | `1.5T` |
#### Node identifiers #### Node identifiers
@ -292,6 +296,8 @@ garage status
It will display the IP address associated with each node; It will display the IP address associated with each node;
from the IP address you will be able to recognize the node. from the IP address you will be able to recognize the node.
We will now use the `garage layout assign` command to configure the correct parameters for each node.
#### Zones #### Zones
Zones are simply a user-chosen identifier that identify a group of server that are grouped together logically. Zones are simply a user-chosen identifier that identify a group of server that are grouped together logically.
@ -301,29 +307,29 @@ In most cases, a zone will correspond to a geographical location (i.e. a datacen
Behind the scene, Garage will use zone definition to try to store the same data on different zones, Behind the scene, Garage will use zone definition to try to store the same data on different zones,
in order to provide high availability despite failure of a zone. in order to provide high availability despite failure of a zone.
Zones are passed to Garage using the `-z` flag of `garage layout assign` (see below).
#### Capacity #### Capacity
Garage reasons on an abstract metric about disk storage that is named the *capacity* of a node. Garage needs to know the storage capacity (disk space) it can/should use on
The capacity configured in Garage must be proportional to the disk space dedicated to the node. each node, to be able to correctly balance data.
Capacity values must be **integers** but can be given any signification. Capacity values are expressed in bytes and are passed to Garage using the `-c` flag of `garage layout assign` (see below).
Here we chose that 1 unit of capacity = 100 GB.
Note that the amount of data stored by Garage on each server may not be strictly proportional to #### Tags
its capacity value, as Garage will priorize having 3 copies of data in different zones,
even if this means that capacities will not be strictly respected. For example in our above examples, You can add additional tags to nodes using the `-t` flag of `garage layout assign` (see below).
nodes Earth and Mars will always store a copy of everything each, and the third copy will Tags have no specific meaning for Garage and can be used at your convenience.
have 66% chance of being stored by Venus and 33% chance of being stored by Mercury.
#### Injecting the topology #### Injecting the topology
Given the information above, we will configure our cluster as follow: Given the information above, we will configure our cluster as follow:
```bash ```bash
garage layout assign 563e -z par1 -c 10 -t mercury garage layout assign 563e -z par1 -c 1T -t mercury
garage layout assign 86f0 -z par1 -c 20 -t venus garage layout assign 86f0 -z par1 -c 2T -t venus
garage layout assign 6814 -z lon1 -c 20 -t earth garage layout assign 6814 -z lon1 -c 2T -t earth
garage layout assign 212f -z bru1 -c 15 -t mars garage layout assign 212f -z bru1 -c 1.5T -t mars
``` ```
At this point, the changes in the cluster layout have not yet been applied. At this point, the changes in the cluster layout have not yet been applied.
@ -333,6 +339,7 @@ To show the new layout that will be applied, call:
garage layout show garage layout show
``` ```
Make sure to read carefully the output of `garage layout show`.
Once you are satisfied with your new layout, apply it with: Once you are satisfied with your new layout, apply it with:
```bash ```bash

19
doc/book/quick-start/_index.md
View File

@ -84,9 +84,8 @@ admin_token = "$(openssl rand -base64 32)"
EOF EOF
``` ```
Now that your configuration file has been created, you can put Now that your configuration file has been created, you may save it to the directory of your choice.
it in the right place. By default, garage looks at **`/etc/garage.toml`.** By default, Garage looks for **`/etc/garage.toml`.**
You can also store it somewhere else, but you will have to specify `-c path/to/garage.toml` You can also store it somewhere else, but you will have to specify `-c path/to/garage.toml`
at each invocation of the `garage` binary (for example: `garage -c ./garage.toml server`, `garage -c ./garage.toml status`). at each invocation of the `garage` binary (for example: `garage -c ./garage.toml server`, `garage -c ./garage.toml status`).
@ -103,12 +102,14 @@ your data to be persisted properly.
### Launching the Garage server ### Launching the Garage server
Use the following command to launch the Garage server with our configuration file: Use the following command to launch the Garage server:
``` ```
garage server garage -c path/to/garage.toml server
``` ```
If you have placed the `garage.toml` file in `/etc` (its default location), you can simply run `garage server`.
You can tune Garage's verbosity as follows (from less verbose to more verbose): You can tune Garage's verbosity as follows (from less verbose to more verbose):
``` ```
@ -126,7 +127,7 @@ Log level `debug` can help you check why your S3 API calls are not working.
The `garage` utility is also used as a CLI tool to configure your Garage deployment. The `garage` utility is also used as a CLI tool to configure your Garage deployment.
It uses values from the TOML configuration file to find the Garage daemon running on the It uses values from the TOML configuration file to find the Garage daemon running on the
local node, therefore if your configuration file is not at `/etc/garage.toml` you will local node, therefore if your configuration file is not at `/etc/garage.toml` you will
again have to specify `-c path/to/garage.toml`. again have to specify `-c path/to/garage.toml` at each invocation.
If the `garage` CLI is able to correctly detect the parameters of your local Garage node, If the `garage` CLI is able to correctly detect the parameters of your local Garage node,
the following command should be enough to show the status of your cluster: the following command should be enough to show the status of your cluster:
@ -140,7 +141,7 @@ This should show something like this:
``` ```
==== HEALTHY NODES ==== ==== HEALTHY NODES ====
ID Hostname Address Tag Zone Capacity ID Hostname Address Tag Zone Capacity
563e1ac825ee3323… linuxbox 127.0.0.1:3901 NO ROLE ASSIGNED 563e1ac825ee3323 linuxbox 127.0.0.1:3901 NO ROLE ASSIGNED
``` ```
## Creating a cluster layout ## Creating a cluster layout
@ -153,12 +154,12 @@ For our test deployment, we are using only one node. The way in which we configu
it does not matter, you can simply write: it does not matter, you can simply write:
```bash ```bash
garage layout assign -z dc1 -c 1 <node_id> garage layout assign -z dc1 -c 1G <node_id>
``` ```
where `<node_id>` corresponds to the identifier of the node shown by `garage status` (first column). where `<node_id>` corresponds to the identifier of the node shown by `garage status` (first column).
You can enter simply a prefix of that identifier. You can enter simply a prefix of that identifier.
For instance here you could write just `garage layout assign -z dc1 -c 1 563e`. For instance here you could write just `garage layout assign -z dc1 -c 1G 563e`.
The layout then has to be applied to the cluster, using: The layout then has to be applied to the cluster, using:

9
doc/book/working-documents/migration-09.md
View File

@ -1,13 +1,16 @@
+++ +++
title = "Migrating from 0.8 to 0.9" title = "Migrating from 0.8 to 0.9"
weight = 14 weight = 12
+++ +++
**This guide explains how to migrate to 0.9 if you have an existing 0.8 cluster. **This guide explains how to migrate to 0.9 if you have an existing 0.8 cluster.
We don't recommend trying to migrate to 0.9 directly from 0.7 or older.** We don't recommend trying to migrate to 0.9 directly from 0.7 or older.**
**We make no guarantee that this migration will work perfectly: This migration procedure has been tested on several clusters without issues.
back up all your data before attempting it!** However, it is still a *critical procedure* that might cause issues.
**Make sure to back up all your data before attempting it!**
You might also want to read our [general documentation on upgrading Garage](@/documentation/operations/upgrading.md).
The following are **breaking changes** in Garage v0.9 that require your attention when migrating: The following are **breaking changes** in Garage v0.9 that require your attention when migrating: