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

Reviewed-on: Deuxfleurs/garage#489

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.

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
 ```

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.

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
+}
+```

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,
+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.