diff options
| -rw-r--r-- | doc/book/cookbook/_index.md | 4 | ||||
| -rw-r--r-- | doc/book/cookbook/gateways.md | 2 | ||||
| -rw-r--r-- | doc/book/cookbook/monitoring.md | 25 | ||||
| -rw-r--r-- | doc/book/cookbook/reverse-proxy.md | 52 | ||||
| -rw-r--r-- | doc/book/reference-manual/configuration.md | 4 |
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. |