Merge pull request 'Small doc corrections' (#489) from jpds/garage:doc-corrections into main

Reviewed-on: Deuxfleurs/garage#489
This commit is contained in:
Alex 2023-01-30 16:35:30 +00:00
commit 4cff37397f
5 changed files with 83 additions and 4 deletions

View file

@ -26,6 +26,10 @@ This chapter could also be referred as "Tutorials" or "Best practices".
- **[Configuring a reverse-proxy](@/documentation/cookbook/reverse-proxy.md):** This page explains how to configure a reverse-proxy to add TLS support to your S3 api endpoint. - **[Configuring a reverse-proxy](@/documentation/cookbook/reverse-proxy.md):** This page explains how to configure a reverse-proxy to add TLS support to your S3 api endpoint.
- **[Monitoring Garage](@/documentation/cookbook/monitoring.md)** This page
explains the Prometheus metrics available for monitoring the Garage
cluster/nodes.
- **[Recovering from failures](@/documentation/cookbook/recovering.md):** Garage's first selling point is resilience - **[Recovering from failures](@/documentation/cookbook/recovering.md):** Garage's first selling point is resilience
to hardware failures. This section explains how to recover from such a failure in the to hardware failures. This section explains how to recover from such a failure in the
best possible way. best possible way.

View file

@ -21,7 +21,7 @@ You can configure Garage as a gateway on all nodes that will consume your S3 API
The instructions are similar to a regular node, the only option that is different is while configuring the node, you must set the `--gateway` parameter: The instructions are similar to a regular node, the only option that is different is while configuring the node, you must set the `--gateway` parameter:
```bash ```bash
garage layout assign --gateway --tag gw1 <node_id> garage layout assign --gateway --tag gw1 -z dc1 <node_id>
garage layout show # review the changes you are making garage layout show # review the changes you are making
garage layout apply # once satisfied, apply the changes garage layout apply # once satisfied, apply the changes
``` ```

View file

@ -55,6 +55,23 @@ We detail below the list of exposed metrics and their meaning.
## List of exported metrics ## List of exported metrics
### Garage system metrics
#### `garage_build_info` (counter)
Exposes the Garage version number running on a node.
```
garage_build_info{version="1.0"} 1
```
#### `garage_replication_factor` (counter)
Exposes the Garage replication factor configured on the node
```
garage_replication_factor 3
```
### Metrics of the API endpoints ### Metrics of the API endpoints
@ -148,6 +165,14 @@ block_bytes_read 120586322022
block_bytes_written 3386618077 block_bytes_written 3386618077
``` ```
#### `block_compression_level` (counter)
Exposes the block compression level configured for the Garage node.
```
block_compression_level 3
```
#### `block_read_duration`, `block_write_duration` (histograms) #### `block_read_duration`, `block_write_duration` (histograms)
Evaluates the duration of the reading/writing of individual data blocks in the data storage directory. Evaluates the duration of the reading/writing of individual data blocks in the data storage directory.

View file

@ -295,7 +295,7 @@ s3.garage.tld, *.s3.garage.tld {
} }
*.web.garage.tld { *.web.garage.tld {
reverse_proxy localhost:3902 192.168.1.2:3900 example.tld:3900 reverse_proxy localhost:3902 192.168.1.2:3902 example.tld:3902
} }
admin.garage.tld { admin.garage.tld {
@ -306,3 +306,53 @@ admin.garage.tld {
But at the same time, the `reverse_proxy` is very flexible. But at the same time, the `reverse_proxy` is very flexible.
For a production deployment, you should [read its documentation](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy) as it supports features like DNS discovery of upstreams, load balancing with checks, streaming parameters, etc. For a production deployment, you should [read its documentation](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy) as it supports features like DNS discovery of upstreams, load balancing with checks, streaming parameters, etc.
### On-demand TLS
Caddy supports a technique called
[on-demand TLS](https://caddyserver.com/docs/automatic-https#on-demand-tls), by
which one can configure the webserver to provision TLS certificates when a
client first connects to it.
In order to prevent an attack vector whereby domains are simply pointed at your
webserver and certificates are requested for them - Caddy can be configured to
ask Garage if a domain is authorized for web hosting, before it then requests
a TLS certificate.
This 'check' endpoint, which is on the admin port (3903 by default), can be
configured in Caddy's global section as follows:
```caddy
{
...
on_demand_tls {
ask http://localhost:3903/check
interval 2m
burst 5
}
...
}
```
The host section can then be configured with (note that this uses the web
endpoint instead):
```caddy
# For a specific set of subdomains
*.web.garage.tld {
tls {
on_demand
}
reverse_proxy localhost:3902 192.168.1.2:3902 example.tld:3902
}
# Accept all domains on HTTPS
# Never configure this without global section above
https:// {
tls {
on_demand
}
reverse_proxy localhost:3902 192.168.1.2:3902 example.tld:3902
}
```

View file

@ -429,6 +429,6 @@ You can use any random string for this value. We recommend generating a random t
### `trace_sink` ### `trace_sink`
Optionnally, the address of an Opentelemetry collector. If specified, Optionally, the address of an OpenTelemetry collector. If specified,
Garage will send traces in the Opentelemetry format to this endpoint. These Garage will send traces in the OpenTelemetry format to this endpoint. These
trace allow to inspect Garage's operation when it handles S3 API requests. trace allow to inspect Garage's operation when it handles S3 API requests.