aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAlex <alex@adnab.me>2023-01-30 16:35:30 +0000
committerAlex <alex@adnab.me>2023-01-30 16:35:30 +0000
commit4cff37397f626ef063dad29e5b5e97ab1206015d (patch)
tree584005f176e3e535dd4e63ae766cffc9fb12b0f0
parenta1005c26b638782df613a7a776e4dcb22ad34d08 (diff)
parent5f412abd4e0868ea11711f696c3eabe452db7560 (diff)
downloadgarage-4cff37397f626ef063dad29e5b5e97ab1206015d.tar.gz
garage-4cff37397f626ef063dad29e5b5e97ab1206015d.zip
Merge pull request 'Small doc corrections' (#489) from jpds/garage:doc-corrections into main
Reviewed-on: https://git.deuxfleurs.fr/Deuxfleurs/garage/pulls/489
-rw-r--r--doc/book/cookbook/_index.md4
-rw-r--r--doc/book/cookbook/gateways.md2
-rw-r--r--doc/book/cookbook/monitoring.md25
-rw-r--r--doc/book/cookbook/reverse-proxy.md52
-rw-r--r--doc/book/reference-manual/configuration.md4
5 files changed, 83 insertions, 4 deletions
diff --git a/doc/book/cookbook/_index.md b/doc/book/cookbook/_index.md
index 6e279363..34e2ed92 100644
--- a/doc/book/cookbook/_index.md
+++ b/doc/book/cookbook/_index.md
@@ -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.
+- **[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
to hardware failures. This section explains how to recover from such a failure in the
best possible way.
diff --git a/doc/book/cookbook/gateways.md b/doc/book/cookbook/gateways.md
index 62ed0fe2..ce4c7fa8 100644
--- a/doc/book/cookbook/gateways.md
+++ b/doc/book/cookbook/gateways.md
@@ -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:
```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 apply # once satisfied, apply the changes
```
diff --git a/doc/book/cookbook/monitoring.md b/doc/book/cookbook/monitoring.md
index 8206f645..f2240e8c 100644
--- a/doc/book/cookbook/monitoring.md
+++ b/doc/book/cookbook/monitoring.md
@@ -55,6 +55,23 @@ We detail below the list of exposed metrics and their meaning.
## 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
@@ -148,6 +165,14 @@ block_bytes_read 120586322022
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)
Evaluates the duration of the reading/writing of individual data blocks in the data storage directory.
diff --git a/doc/book/cookbook/reverse-proxy.md b/doc/book/cookbook/reverse-proxy.md
index c8fde28d..c7dcf6a8 100644
--- a/doc/book/cookbook/reverse-proxy.md
+++ b/doc/book/cookbook/reverse-proxy.md
@@ -295,7 +295,7 @@ s3.garage.tld, *.s3.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 {
@@ -306,3 +306,53 @@ admin.garage.tld {
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.
+### 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
+}
+```
diff --git a/doc/book/reference-manual/configuration.md b/doc/book/reference-manual/configuration.md
index 353963ef..7a829836 100644
--- a/doc/book/reference-manual/configuration.md
+++ b/doc/book/reference-manual/configuration.md
@@ -429,6 +429,6 @@ You can use any random string for this value. We recommend generating a random t
### `trace_sink`
-Optionnally, the address of an Opentelemetry collector. If specified,
-Garage will send traces in the Opentelemetry format to this endpoint. These
+Optionally, the address of an OpenTelemetry collector. If specified,
+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.