forked from Deuxfleurs/garage
WIP getting started
This commit is contained in:
parent
b82a61fba2
commit
1a5af9d1fc
4 changed files with 175 additions and 32 deletions
doc/book/src/getting_started
|
@ -1,71 +1,78 @@
|
|||
# Create buckets and keys
|
||||
|
||||
First, chances are that your garage deployment is secured by TLS.
|
||||
All your commands must be prefixed with their certificates.
|
||||
I will define an alias once and for all to ease future commands.
|
||||
Please adapt the path of the binary and certificates to your installation!
|
||||
*We use a command named `garagectl` which is in fact an alias you must define as explained in the [Control the daemon](./daemon.md) section.*
|
||||
|
||||
```
|
||||
alias grg="/garage/garage --ca-cert /secrets/garage-ca.crt --client-cert /secrets/garage.crt --client-key /secrets/garage.key"
|
||||
```
|
||||
|
||||
Now we can check that everything is going well by checking our cluster status:
|
||||
|
||||
```
|
||||
grg status
|
||||
```
|
||||
In this section, we will suppose that we want to create a bucket named `nextcloud-bucket`
|
||||
that will be accessed through a key named `nextcloud-app-key`.
|
||||
|
||||
Don't forget that `help` command and `--help` subcommands can help you anywhere, the CLI tool is self-documented! Two examples:
|
||||
|
||||
```
|
||||
grg help
|
||||
grg bucket allow --help
|
||||
garagectl help
|
||||
garagectl bucket allow --help
|
||||
```
|
||||
|
||||
## Create a bucket
|
||||
|
||||
Fine, now let's create a bucket (we imagine that you want to deploy nextcloud):
|
||||
|
||||
```
|
||||
grg bucket create nextcloud-bucket
|
||||
garagectl bucket create nextcloud-bucket
|
||||
```
|
||||
|
||||
Check that everything went well:
|
||||
|
||||
```
|
||||
grg bucket list
|
||||
grg bucket info nextcloud-bucket
|
||||
garagectl bucket list
|
||||
garagectl bucket info nextcloud-bucket
|
||||
```
|
||||
|
||||
## Create an API key
|
||||
|
||||
Now we will generate an API key to access this bucket.
|
||||
Note that API keys are independent of buckets: one key can access multiple buckets, multiple keys can access one bucket.
|
||||
|
||||
Now, let's start by creating a key only for our PHP application:
|
||||
|
||||
```
|
||||
grg key new --name nextcloud-app-key
|
||||
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):
|
||||
|
||||
```
|
||||
Key { key_id: "GK3515373e4c851ebaad366558", secret_key: "7d37d093435a41f2aab8f13c19ba067d9776c90215f56614adad6ece597dbb34", name: "nextcloud-app-key", name_timestamp: 1603280506694, deleted: false, authorized_buckets: [] }
|
||||
```javascript
|
||||
Key {
|
||||
key_id: "GK3515373e4c851ebaad366558",
|
||||
secret_key: "7d37d093435a41f2aab8f13c19ba067d9776c90215f56614adad6ece597dbb34",
|
||||
name: "nextcloud-app-key",
|
||||
name_timestamp: 1603280506694,
|
||||
deleted: false,
|
||||
authorized_buckets: []
|
||||
}
|
||||
```
|
||||
|
||||
Check that everything works as intended (be careful, info works only with your key identifier and not with its friendly name!):
|
||||
|
||||
```
|
||||
grg key list
|
||||
grg key info GK3515373e4c851ebaad366558
|
||||
garagectl key list
|
||||
garagectl key info GK3515373e4c851ebaad366558
|
||||
```
|
||||
|
||||
## Allow a key to access a bucket
|
||||
|
||||
Now that we have a bucket and a key, we need to give permissions to the key on the bucket!
|
||||
|
||||
```
|
||||
grg bucket allow --read --write nextcloud-bucket --key GK3515373e4c851ebaad366558
|
||||
garagectl bucket allow \
|
||||
--read \
|
||||
--write
|
||||
nextcloud-bucket \
|
||||
--key GK3515373e4c851ebaad366558
|
||||
```
|
||||
|
||||
You can check at any times allowed keys on your bucket with:
|
||||
|
||||
```
|
||||
grg bucket info nextcloud-bucket
|
||||
garagectl bucket info nextcloud-bucket
|
||||
```
|
||||
|
||||
|
|
|
@ -1,14 +1,72 @@
|
|||
# Configure a cluster
|
||||
|
||||
*We use a command named `garagectl` which is in fact an alias you must define as explained in the [Control the daemon](./daemon.md) section.*
|
||||
|
||||
In this section, we will inform garage of the disk space available on each node of the cluster
|
||||
as well as the site (think datacenter) of each machine.
|
||||
|
||||
## Test cluster
|
||||
|
||||
As this part is not relevant for a test cluster, you can use this one-liner to create a basic topology:
|
||||
|
||||
```bash
|
||||
garagectl status | grep UNCONFIGURED | grep -Po '^[0-9a-f]+' | while read id; do
|
||||
garagectl node configure -d dc1 -n 10 $id
|
||||
done
|
||||
```
|
||||
|
||||
## Real-world cluster
|
||||
|
||||
For our example, we will suppose we have the following infrastructure:
|
||||
For our example, we will suppose we have the following infrastructure (Tokens, Identifier and Datacenter are specific values to garage described in the following):
|
||||
|
||||
| Location | Name | IP Address | Disk Space |
|
||||
|----------|---------|------------|------------|
|
||||
| Paris | Mercury | fc00:1::1 | 1 To |
|
||||
| Paris | Venus | fc00:1::2 | 2 To |
|
||||
| London | Earth | fc00:1::2 | 2 To |
|
||||
| Brussels | Mars | fc00:B::1 | 1.5 To |
|
||||
| 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` |
|
||||
|
||||
### Identifier
|
||||
|
||||
After its first launch, garage generates a random and unique identifier for each nodes, such as:
|
||||
|
||||
```
|
||||
8781c50c410a41b363167e9d49cc468b6b9e4449b6577b64f15a249a149bdcbc
|
||||
```
|
||||
|
||||
Often a shorter form can be used, containing only the beginning of the identifier, like `8781c5`,
|
||||
which identifies the server "Mercury" located in "Paris" according to our previous table.
|
||||
|
||||
The most simple way to match an identifier to a node is to run:
|
||||
|
||||
```
|
||||
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
|
||||
|
||||
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*).
|
||||
|
||||
Here we chose 1 token = 10 Go but you are free to select the value that best fit your needs.
|
||||
|
||||
### Datacenter
|
||||
|
||||
Datacenter are simply a user-chosen identifier that identify a group of server that are located in the same place.
|
||||
It is up to the system administrator deploying garage to identify what does "the same place" means.
|
||||
Behind the scene, garage will try to store the same data on different sites to provide high availability despite a data center failure.
|
||||
|
||||
### Inject the topology
|
||||
|
||||
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
|
||||
```
|
||||
|
|
77
doc/book/src/getting_started/control.md
Normal file
77
doc/book/src/getting_started/control.md
Normal file
|
@ -0,0 +1,77 @@
|
|||
# Control the daemon
|
||||
|
||||
The `garage` binary has two purposes:
|
||||
- it acts as a daemon when launched with `garage server ...`
|
||||
- it acts as a control tool for the daemon when launched with any other command
|
||||
|
||||
In this section, we will see how to use the `garage` binary as a control tool for the daemon we just started.
|
||||
You first need to get a shell having access to this binary, which depends of your configuration:
|
||||
- with `docker-compose`, run `sudo docker-compose exec g1 bash` then `/garage/garage`
|
||||
- with `docker`, run `sudo docker exec -ti garaged bash` then `/garage/garage`
|
||||
- with `systemd`, simply run `/usr/local/bin/garage` if you followed previous instructions
|
||||
|
||||
*You can also install the binary on your machine to remotely control the cluster.*
|
||||
|
||||
## Talk to the daemon and create an alias
|
||||
|
||||
`garage` requires 4 options to talk with the daemon:
|
||||
|
||||
```
|
||||
--ca-cert <ca-cert>
|
||||
--client-cert <client-cert>
|
||||
--client-key <client-key>
|
||||
-h, --rpc-host <rpc-host>
|
||||
```
|
||||
|
||||
The 3 first ones are certificates and keys needed by TLS, the last one is simply the address of garage's RPC endpoint.
|
||||
Because we configure garage directly from the server, we do not need to set `--rpc-host`.
|
||||
To avoid typing the 3 first options each time we want to run a command, we will create an alias.
|
||||
|
||||
### `docker-compose` alias
|
||||
|
||||
```bash
|
||||
alias garagectl='/garage/garage \
|
||||
--ca-cert /pki/garage-ca.crt \
|
||||
--client-cert /pki/garage.crt \
|
||||
--client-key /pki/garage.key'
|
||||
```
|
||||
|
||||
### `docker` alias
|
||||
|
||||
```bash
|
||||
alias garagectl='/garage/garage \
|
||||
--ca-cert /etc/garage/pki/garage-ca.crt \
|
||||
--client-cert /etc/garage/pki/garage.crt \
|
||||
--client-key /etc/garage/pki/garage.key'
|
||||
```
|
||||
|
||||
|
||||
### raw binary alias
|
||||
|
||||
```bash
|
||||
alias garagectl='/usr/local/bin/garage \
|
||||
--ca-cert /etc/garage/pki/garage-ca.crt \
|
||||
--client-cert /etc/garage/pki/garage.crt \
|
||||
--client-key /etc/garage/pki/garage.key'
|
||||
```
|
||||
|
||||
Of course, if your deployment does not match exactly one of this alias, feel free to adapt it to your needs!
|
||||
|
||||
## Test the alias
|
||||
|
||||
You can test your alias by running a simple command such as:
|
||||
|
||||
```
|
||||
garagectl status
|
||||
```
|
||||
|
||||
You should get something like that as result:
|
||||
|
||||
```
|
||||
Healthy nodes:
|
||||
2a638ed6c775b69a… 37f0ba978d27 [::ffff:172.20.0.101]:3901 UNCONFIGURED/REMOVED
|
||||
68143d720f20c89d… 9795a2f7abb5 [::ffff:172.20.0.103]:3901 UNCONFIGURED/REMOVED
|
||||
8781c50c410a41b3… 758338dde686 [::ffff:172.20.0.102]:3901 UNCONFIGURED/REMOVED
|
||||
```
|
||||
|
||||
...which means that you are ready to configure your cluster!
|
|
@ -171,6 +171,7 @@ On each machine, you can run the daemon with:
|
|||
```bash
|
||||
docker run \
|
||||
-d \
|
||||
--name garaged \
|
||||
--restart always \
|
||||
--network host \
|
||||
-v /etc/garage/pki:/etc/garage/pki \
|
||||
|
|
Loading…
Reference in a new issue