From 0c618f8a89addebd1eb8483cc87d48ea8a2d1d48 Mon Sep 17 00:00:00 2001 From: Jonathan Davies Date: Wed, 4 Jan 2023 18:49:27 +0000 Subject: [PATCH 1/6] reverse-proxy.md: Corrected web server ports in Caddy example. --- doc/book/cookbook/reverse-proxy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/book/cookbook/reverse-proxy.md b/doc/book/cookbook/reverse-proxy.md index c8fde28d..01fe4edc 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 { From 55c369137dfc6dcda4ba2a51347c9d49461dd69f Mon Sep 17 00:00:00 2001 From: Jonathan Davies Date: Wed, 4 Jan 2023 19:02:39 +0000 Subject: [PATCH 2/6] gateways.md: -z is a required flag for layout assign. --- doc/book/cookbook/gateways.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 +garage layout assign --gateway --tag gw1 -z dc1 garage layout show # review the changes you are making garage layout apply # once satisfied, apply the changes ``` From 7ab27f84b80f00764988052506432a9f34932896 Mon Sep 17 00:00:00 2001 From: Jonathan Davies Date: Mon, 9 Jan 2023 11:57:01 +0000 Subject: [PATCH 3/6] configuration.md: Corrected OpenTelemetry. --- doc/book/reference-manual/configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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. From ae9c7a29001ce08a73798f68f49c421a2e432959 Mon Sep 17 00:00:00 2001 From: Jonathan Davies Date: Fri, 27 Jan 2023 18:01:06 +0000 Subject: [PATCH 4/6] cookbook/_index.md: Added link to monitoring documentation. --- doc/book/cookbook/_index.md | 4 ++++ 1 file changed, 4 insertions(+) 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. From c753a9dfb6e46830a625697d7c244183c4b5f1a7 Mon Sep 17 00:00:00 2001 From: Jonathan Davies Date: Fri, 27 Jan 2023 20:55:50 +0000 Subject: [PATCH 5/6] cookbook/monitoring.md: Added new metrics (garage_build_info, garage_replication_factor, block_compression_level). --- doc/book/cookbook/monitoring.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) 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. From 5f412abd4e0868ea11711f696c3eabe452db7560 Mon Sep 17 00:00:00 2001 From: Jonathan Davies Date: Sat, 28 Jan 2023 21:57:26 +0000 Subject: [PATCH 6/6] cookbook/reverse-proxy.md: Added on-demand TLS section. --- doc/book/cookbook/reverse-proxy.md | 50 ++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/doc/book/cookbook/reverse-proxy.md b/doc/book/cookbook/reverse-proxy.md index 01fe4edc..c7dcf6a8 100644 --- a/doc/book/cookbook/reverse-proxy.md +++ b/doc/book/cookbook/reverse-proxy.md @@ -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 +} +```