From e852c91d18dc5eb82b335472de53e35420a8290a Mon Sep 17 00:00:00 2001 From: kaiyou Date: Fri, 18 Nov 2022 20:03:57 +0100 Subject: Fix documentation based on new deployment values --- doc/book/cookbook/kubernetes.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'doc/book/cookbook') diff --git a/doc/book/cookbook/kubernetes.md b/doc/book/cookbook/kubernetes.md index 9eafe3e1..dfeb3281 100644 --- a/doc/book/cookbook/kubernetes.md +++ b/doc/book/cookbook/kubernetes.md @@ -48,7 +48,8 @@ garage: replicationMode: "2" # Start 4 instances (StatefulSets) of garage -replicaCount: 4 +deployment: + replicaCount: 4 # Override default storage class and size persistence: -- cgit v1.2.3 From f2492107d7858882adf386f8925829659755f1e5 Mon Sep 17 00:00:00 2001 From: Jonathan Davies Date: Wed, 25 Jan 2023 12:00:01 +0000 Subject: cookbook/real-world.md: Added note about mesh network options. --- doc/book/cookbook/real-world.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) (limited to 'doc/book/cookbook') diff --git a/doc/book/cookbook/real-world.md b/doc/book/cookbook/real-world.md index 5423bbab..9be1ba44 100644 --- a/doc/book/cookbook/real-world.md +++ b/doc/book/cookbook/real-world.md @@ -19,8 +19,12 @@ To run a real-world deployment, make sure the following conditions are met: - You have at least three machines with sufficient storage space available. -- Each machine has a public IP address which is reachable by other machines. - Running behind a NAT is likely to be possible but hasn't been tested for the latest version (TODO). +- Each machine has a public IP address which is reachable by other machines. It + is highly recommended that you use IPv6 for this end-to-end connectivity. If + IPv6 is not available, then using a mesh VPN such as + [Nebula](https://github.com/slackhq/nebula) or + [Yggdrasil](https://yggdrasil-network.github.io/) are approaches to consider + in addition to building out your own VPN tunneling. - This guide will assume you are using Docker containers to deploy Garage on each node. Garage can also be run independently, for instance as a [Systemd service](@/documentation/cookbook/systemd.md). -- cgit v1.2.3 From 0c618f8a89addebd1eb8483cc87d48ea8a2d1d48 Mon Sep 17 00:00:00 2001 From: Jonathan Davies Date: Wed, 4 Jan 2023 18:49:27 +0000 Subject: reverse-proxy.md: Corrected web server ports in Caddy example. --- doc/book/cookbook/reverse-proxy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/book/cookbook') 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 { -- cgit v1.2.3 From 55c369137dfc6dcda4ba2a51347c9d49461dd69f Mon Sep 17 00:00:00 2001 From: Jonathan Davies Date: Wed, 4 Jan 2023 19:02:39 +0000 Subject: gateways.md: -z is a required flag for layout assign. --- doc/book/cookbook/gateways.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/book/cookbook') 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 ``` -- cgit v1.2.3 From ae9c7a29001ce08a73798f68f49c421a2e432959 Mon Sep 17 00:00:00 2001 From: Jonathan Davies Date: Fri, 27 Jan 2023 18:01:06 +0000 Subject: cookbook/_index.md: Added link to monitoring documentation. --- doc/book/cookbook/_index.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'doc/book/cookbook') 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. -- cgit v1.2.3 From c753a9dfb6e46830a625697d7c244183c4b5f1a7 Mon Sep 17 00:00:00 2001 From: Jonathan Davies Date: Fri, 27 Jan 2023 20:55:50 +0000 Subject: 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(+) (limited to 'doc/book/cookbook') 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. -- cgit v1.2.3 From 5f412abd4e0868ea11711f696c3eabe452db7560 Mon Sep 17 00:00:00 2001 From: Jonathan Davies Date: Sat, 28 Jan 2023 21:57:26 +0000 Subject: cookbook/reverse-proxy.md: Added on-demand TLS section. --- doc/book/cookbook/reverse-proxy.md | 50 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) (limited to 'doc/book/cookbook') 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 +} +``` -- cgit v1.2.3 From 44f8b1d71abf661fb4e2a34b22c00569efc09481 Mon Sep 17 00:00:00 2001 From: Alex Auvolat Date: Mon, 30 Jan 2023 18:00:01 +0100 Subject: Reorder reference manual section, move metrics list to there --- doc/book/cookbook/monitoring.md | 276 +--------------------------------------- 1 file changed, 1 insertion(+), 275 deletions(-) (limited to 'doc/book/cookbook') diff --git a/doc/book/cookbook/monitoring.md b/doc/book/cookbook/monitoring.md index f2240e8c..8313daa9 100644 --- a/doc/book/cookbook/monitoring.md +++ b/doc/book/cookbook/monitoring.md @@ -52,280 +52,6 @@ or make your own. 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 - -#### `api_admin_request_counter` (counter) - -Counts the number of requests to a given endpoint of the administration API. Example: - -``` -api_admin_request_counter{api_endpoint="Metrics"} 127041 -``` - -#### `api_admin_request_duration` (histogram) - -Evaluates the duration of API calls to the various administration API endpoint. Example: - -``` -api_admin_request_duration_bucket{api_endpoint="Metrics",le="0.5"} 127041 -api_admin_request_duration_sum{api_endpoint="Metrics"} 605.250344830999 -api_admin_request_duration_count{api_endpoint="Metrics"} 127041 -``` - -#### `api_s3_request_counter` (counter) - -Counts the number of requests to a given endpoint of the S3 API. Example: - -``` -api_s3_request_counter{api_endpoint="CreateMultipartUpload"} 1 -``` - -#### `api_s3_error_counter` (counter) - -Counts the number of requests to a given endpoint of the S3 API that returned an error. Example: - -``` -api_s3_error_counter{api_endpoint="GetObject",status_code="404"} 39 -``` - -#### `api_s3_request_duration` (histogram) - -Evaluates the duration of API calls to the various S3 API endpoints. Example: - -``` -api_s3_request_duration_bucket{api_endpoint="CreateMultipartUpload",le="0.5"} 1 -api_s3_request_duration_sum{api_endpoint="CreateMultipartUpload"} 0.046340762 -api_s3_request_duration_count{api_endpoint="CreateMultipartUpload"} 1 -``` - -#### `api_k2v_request_counter` (counter), `api_k2v_error_counter` (counter), `api_k2v_error_duration` (histogram) - -Same as for S3, for the K2V API. - - -### Metrics of the Web endpoint - - -#### `web_request_counter` (counter) - -Number of requests to the web endpoint - -``` -web_request_counter{method="GET"} 80 -``` - -#### `web_request_duration` (histogram) - -Duration of requests to the web endpoint - -``` -web_request_duration_bucket{method="GET",le="0.5"} 80 -web_request_duration_sum{method="GET"} 1.0528433229999998 -web_request_duration_count{method="GET"} 80 -``` - -#### `web_error_counter` (counter) - -Number of requests to the web endpoint resulting in errors - -``` -web_error_counter{method="GET",status_code="404 Not Found"} 64 -``` - - -### Metrics of the data block manager - -#### `block_bytes_read`, `block_bytes_written` (counter) - -Number of bytes read/written to/from disk in the data storage directory. - -``` -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. - -``` -block_read_duration_bucket{le="0.5"} 169229 -block_read_duration_sum 2761.6902550310056 -block_read_duration_count 169240 -block_write_duration_bucket{le="0.5"} 3559 -block_write_duration_sum 195.59170078500006 -block_write_duration_count 3571 -``` - -#### `block_delete_counter` (counter) - -Counts the number of data blocks that have been deleted from storage. - -``` -block_delete_counter 122 -``` - -#### `block_resync_counter` (counter), `block_resync_duration` (histogram) - -Counts the number of resync operations the node has executed, and evaluates their duration. - -``` -block_resync_counter 308897 -block_resync_duration_bucket{le="0.5"} 308892 -block_resync_duration_sum 139.64204196100016 -block_resync_duration_count 308897 -``` - -#### `block_resync_queue_length` (gauge) - -The number of block hashes currently queued for a resync. -This is normal to be nonzero for long periods of time. - -``` -block_resync_queue_length 0 -``` - -#### `block_resync_errored_blocks` (gauge) - -The number of block hashes that we were unable to resync last time we tried. -**THIS SHOULD BE ZERO, OR FALL BACK TO ZERO RAPIDLY, IN A HEALTHY CLUSTER.** -Persistent nonzero values indicate that some data is likely to be lost. - -``` -block_resync_errored_blocks 0 -``` - - -### Metrics related to RPCs (remote procedure calls) between nodes - -#### `rpc_netapp_request_counter` (counter) - -Number of RPC requests emitted - -``` -rpc_request_counter{from="",rpc_endpoint="garage_block/manager.rs/Rpc",to=""} 176 -``` - -#### `rpc_netapp_error_counter` (counter) - -Number of communication errors (errors in the Netapp library, generally due to disconnected nodes) - -``` -rpc_netapp_error_counter{from="",rpc_endpoint="garage_block/manager.rs/Rpc",to=""} 354 -``` - -#### `rpc_timeout_counter` (counter) - -Number of RPC timeouts, should be close to zero in a healthy cluster. - -``` -rpc_timeout_counter{from="",rpc_endpoint="garage_rpc/membership.rs/SystemRpc",to=""} 1 -``` - -#### `rpc_duration` (histogram) - -The duration of internal RPC calls between Garage nodes. - -``` -rpc_duration_bucket{from="",rpc_endpoint="garage_block/manager.rs/Rpc",to="",le="0.5"} 166 -rpc_duration_sum{from="",rpc_endpoint="garage_block/manager.rs/Rpc",to=""} 35.172253716 -rpc_duration_count{from="",rpc_endpoint="garage_block/manager.rs/Rpc",to=""} 174 -``` - - -### Metrics of the metadata table manager - -#### `table_gc_todo_queue_length` (gauge) - -Table garbage collector TODO queue length - -``` -table_gc_todo_queue_length{table_name="block_ref"} 0 -``` - -#### `table_get_request_counter` (counter), `table_get_request_duration` (histogram) - -Number of get/get_range requests internally made on each table, and their duration. - -``` -table_get_request_counter{table_name="bucket_alias"} 315 -table_get_request_duration_bucket{table_name="bucket_alias",le="0.5"} 315 -table_get_request_duration_sum{table_name="bucket_alias"} 0.048509778000000024 -table_get_request_duration_count{table_name="bucket_alias"} 315 -``` - - -#### `table_put_request_counter` (counter), `table_put_request_duration` (histogram) - -Number of insert/insert_many requests internally made on this table, and their duration - -``` -table_put_request_counter{table_name="block_ref"} 677 -table_put_request_duration_bucket{table_name="block_ref",le="0.5"} 677 -table_put_request_duration_sum{table_name="block_ref"} 61.617528636 -table_put_request_duration_count{table_name="block_ref"} 677 -``` - -#### `table_internal_delete_counter` (counter) - -Number of value deletions in the tree (due to GC or repartitioning) - -``` -table_internal_delete_counter{table_name="block_ref"} 2296 -``` - -#### `table_internal_update_counter` (counter) - -Number of value updates where the value actually changes (includes creation of new key and update of existing key) - -``` -table_internal_update_counter{table_name="block_ref"} 5996 -``` - -#### `table_merkle_updater_todo_queue_length` (gauge) - -Merkle tree updater TODO queue length (should fall to zero rapidly) - -``` -table_merkle_updater_todo_queue_length{table_name="block_ref"} 0 -``` - -#### `table_sync_items_received`, `table_sync_items_sent` (counters) - -Number of data items sent to/recieved from other nodes during resync procedures - -``` -table_sync_items_received{from="",table_name="bucket_v2"} 3 -table_sync_items_sent{table_name="block_ref",to=""} 2 -``` - - +See our [dedicated page](@/documentation/reference-manual/monitoring.md) in the Reference manual section. -- cgit v1.2.3 From 7f715ba94fd636c5fb9d19686e5bf9f51242df06 Mon Sep 17 00:00:00 2001 From: Alex Auvolat Date: Mon, 30 Jan 2023 18:41:04 +0100 Subject: zero-downtime migration procedure --- doc/book/cookbook/upgrading.md | 77 +++++++++++++++++++++++++++++------------- 1 file changed, 54 insertions(+), 23 deletions(-) (limited to 'doc/book/cookbook') diff --git a/doc/book/cookbook/upgrading.md b/doc/book/cookbook/upgrading.md index 9f2ba73b..dd9974d1 100644 --- a/doc/book/cookbook/upgrading.md +++ b/doc/book/cookbook/upgrading.md @@ -6,45 +6,76 @@ weight = 60 Garage is a stateful clustered application, where all nodes are communicating together and share data structures. It makes upgrade more difficult than stateless applications so you must be more careful when upgrading. On a new version release, there is 2 possibilities: - - protocols and data structures remained the same ➡️ this is a **straightforward upgrade** - - protocols or data structures changed ➡️ this is an **advanced upgrade** + - protocols and data structures remained the same ➡️ this is a **minor upgrade** + - protocols or data structures changed ➡️ this is a **major upgrade** -You can quickly now what type of update you will have to operate by looking at the version identifier. -Following the [SemVer ](https://semver.org/) terminology, if only the *patch* number changed, it will only need a straightforward upgrade. -Example: an upgrade from v0.6.0 from v0.6.1 is a straightforward upgrade. -If the *minor* or *major* number changed however, you will have to do an advanced upgrade. Example: from v0.6.1 to v0.7.0. +You can quickly now what type of update you will have to operate by looking at the version identifier: +when we require our users to do a major upgrade, we will always bump the first nonzero component of the version identifier +(e.g. from v0.7.2 to v0.8.0). +Conversely, for versions that only require a minor upgrade, the first nonzero component will always stay the same (e.g. from v0.8.0 to v0.8.1). -Migrations are designed to be run only between contiguous versions (from a *major*.*minor* perspective, *patches* can be skipped). -Example: migrations from v0.6.1 to v0.7.0 and from v0.6.0 to v0.7.0 are supported but migrations from v0.5.0 to v0.7.0 are not supported. +Major upgrades are designed to be run only between contiguous versions. +Example: migrations from v0.7.1 to v0.8.0 and from v0.7.0 to v0.8.2 are supported but migrations from v0.6.0 to v0.8.0 are not supported. -## Straightforward upgrades +## Minor upgrades -Straightforward upgrades do not imply cluster downtime. +Minor upgrades do not imply cluster downtime. Before upgrading, you should still read [the changelog](https://git.deuxfleurs.fr/Deuxfleurs/garage/releases) and ideally test your deployment on a staging cluster before. When you are ready, start by checking the health of your cluster. -You can force some checks with `garage repair`, we recommend at least running `garage repair --all-nodes --yes` that is very quick to run (less than a minute). -You will see that the command correctly terminated in the logs of your daemon. +You can force some checks with `garage repair`, we recommend at least running `garage repair --all-nodes --yes tables` which is very quick to run (less than a minute). +You will see that the command correctly terminated in the logs of your daemon, or using `garage worker list` (the repair workers should be in the `Done` state). -Finally, you can simply upgrades nodes one by one. -For each node: stop it, install the new binary, edit the configuration if needed, restart it. +Finally, you can simply upgrade nodes one by one. +For each node: stop it, install the new binary, edit the configuration if needed, restart it. -## Advanced upgrades +## Major upgrades -Advanced upgrades will imply cluster downtime. +Major upgrades can be done with minimal downtime with a bit of preparation, but the simplest way is usually to put the cluster offline for the duration of the migration. Before upgrading, you must read [the changelog](https://git.deuxfleurs.fr/Deuxfleurs/garage/releases) and you must test your deployment on a staging cluster before. -From a high level perspective, an advanced upgrade looks like this: - 1. Make sure the health of your cluster is good (see `garage repair`) - 2. Disable API access (comment the configuration in your reverse proxy) - 3. Check that your cluster is idle +We write guides for each major upgrade, they are stored under the "Working Documents" section of this documentation. + +### Major upgrades with full downtime + +From a high level perspective, a major upgrade looks like this: + + 1. Disable API access (for instance in your reverse proxy, or by commenting the corresponding section in your Garage configuration file and restarting Garage) + 2. Check that your cluster is idle + 3. Make sure the health of your cluster is good (see `garage repair`) 4. Stop the whole cluster - 5. Backup the metadata folder of all your nodes, so that you will be able to restore it quickly if the upgrade fails (blocks being immutable, they should not be impacted) + 5. Back up the metadata folder of all your nodes, so that you will be able to restore it if the upgrade fails (data blocks being immutable, they should not be impacted) 6. Install the new binary, update the configuration 7. Start the whole cluster 8. If needed, run the corresponding migration from `garage migrate` 9. Make sure the health of your cluster is good - 10. Enable API access (uncomment the configuration in your reverse proxy) + 10. Enable API access (reverse step 1) 11. Monitor your cluster while load comes back, check that all your applications are happy with this new version -We write guides for each advanced upgrade, they are stored under the "Working Documents" section of this documentation. +### Major upgarades with minimal downtime + +There is only one operation that has to be coordinated cluster-wide: the passage of one version of the internal RPC protocol to the next. +This means that an upgrade with very limited downtime can simply be performed from one major version to the next by restarting all nodes +simultaneously in the new version. +The downtime will simply be the time required for all nodes to stop and start again, which should be less than a minute. +If all nodes fail to stop and restart simultaneously, some nodes might be temporarily shut out from the cluster as nodes using different RPC protocol +versions are prevented to talk to one another. + +The entire procedure would look something like this: + +1. Make sure the health of your cluster is good (see `garage repair`) + +2. Take each node offline individually to back up its metadata folder, bring them back online once the backup is done. + You can do all of the nodes in a single zone at once as that won't impact global cluster availability. + Do not try to make a backup of the metadata folder of a running node. + +3. Prepare your binaries and configuration files for the new Garage version + +4. Restart all nodes simultaneously in the new version + +5. If any specific migration procedure is required, it is usually in one of the two cases: + + - It can be run on online nodes after the new version has started, during regular cluster operation. + - it has to be run offline + + For this last step, please refer to the specific documentation pertaining to the version upgrade you are doing. -- cgit v1.2.3 From 179fda9fb6e3e1d837a38b44e08b958f246a8b28 Mon Sep 17 00:00:00 2001 From: Jonathan Davies Date: Mon, 6 Feb 2023 12:53:55 +0000 Subject: upgrading.md: Added small note about garage_build_info. --- doc/book/cookbook/upgrading.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'doc/book/cookbook') diff --git a/doc/book/cookbook/upgrading.md b/doc/book/cookbook/upgrading.md index dd9974d1..9d60a988 100644 --- a/doc/book/cookbook/upgrading.md +++ b/doc/book/cookbook/upgrading.md @@ -17,6 +17,10 @@ Conversely, for versions that only require a minor upgrade, the first nonzero co Major upgrades are designed to be run only between contiguous versions. Example: migrations from v0.7.1 to v0.8.0 and from v0.7.0 to v0.8.2 are supported but migrations from v0.6.0 to v0.8.0 are not supported. +The `garage_build_info` +[Prometheus metric](@/documentation/reference-manual/monitoring.md) provides +an overview for which Garage versions are currently in use within a cluster. + ## Minor upgrades Minor upgrades do not imply cluster downtime. -- cgit v1.2.3 From ee88ccf2b27c1e94922ce542da221560bbe2e6e0 Mon Sep 17 00:00:00 2001 From: Jonathan Davies Date: Tue, 14 Feb 2023 18:39:05 +0000 Subject: cookbook/reverse-proxy.md: Document how to use healthchecks for caddy. --- doc/book/cookbook/reverse-proxy.md | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) (limited to 'doc/book/cookbook') diff --git a/doc/book/cookbook/reverse-proxy.md b/doc/book/cookbook/reverse-proxy.md index c7dcf6a8..65a42271 100644 --- a/doc/book/cookbook/reverse-proxy.md +++ b/doc/book/cookbook/reverse-proxy.md @@ -291,15 +291,30 @@ Your Caddy configuration can be as simple as: ```caddy s3.garage.tld, *.s3.garage.tld { - reverse_proxy localhost:3900 192.168.1.2:3900 example.tld:3900 + reverse_proxy localhost:3900 192.168.1.2:3900 example.tld:3900 { + health_uri /health + health_port 3903 + #health_interval 15s + #health_timeout 5s + } } *.web.garage.tld { - reverse_proxy localhost:3902 192.168.1.2:3902 example.tld:3902 + reverse_proxy localhost:3902 192.168.1.2:3902 example.tld:3902 { + health_uri /health + health_port 3903 + #health_interval 15s + #health_timeout 5s + } } admin.garage.tld { - reverse_proxy localhost:3903 + reverse_proxy localhost:3903 { + health_uri /health + health_port 3903 + #health_interval 15s + #health_timeout 5s + } } ``` -- cgit v1.2.3 From 6b8d634cc23cef1205eb13ce339df921b2907060 Mon Sep 17 00:00:00 2001 From: Jonathan Davies Date: Tue, 14 Feb 2023 18:45:09 +0000 Subject: cookbook/reverse-proxy.md: Fixed up Traefik section: * Renamed my_garage_service -> garage-s3-service. * Defined a web service for port 3902. * Added a garage-s3 router. * Pointed website definition at web service. * Use the /health endpoint for loadBalancer health check. * Renamed gzip_compress to just compression as traefik v3 will also do brotli compression. --- doc/book/cookbook/reverse-proxy.md | 111 ++++++++++++++++++++++++++++--------- 1 file changed, 84 insertions(+), 27 deletions(-) (limited to 'doc/book/cookbook') diff --git a/doc/book/cookbook/reverse-proxy.md b/doc/book/cookbook/reverse-proxy.md index 65a42271..9c833ad0 100644 --- a/doc/book/cookbook/reverse-proxy.md +++ b/doc/book/cookbook/reverse-proxy.md @@ -168,40 +168,65 @@ Here is [a basic configuration file](https://doc.traefik.io/traefik/https/acme/# ### Add Garage service -To add Garage on Traefik you should declare a new service using its IP address (or hostname) and port: +To add Garage on Traefik you should declare two new services using its IP +address (or hostname) and port, these are used for the S3, and web components +of Garage: ```toml [http.services] - [http.services.my_garage_service.loadBalancer] - [[http.services.my_garage_service.loadBalancer.servers]] + [http.services.garage-s3-service.loadBalancer] + [[http.services.garage-s3-service.loadBalancer.servers]] url = "http://xxx.xxx.xxx.xxx" port = 3900 + + [http.services.garage-web-service.loadBalancer] + [[http.services.garage-web-service.loadBalancer.servers]] + url = "http://xxx.xxx.xxx.xxx" + port = 3902 ``` It's possible to declare multiple Garage servers as back-ends: ```toml [http.services] - [[http.services.my_garage_service.loadBalancer.servers]] + [[http.services.garage-s3-service.loadBalancer.servers]] url = "http://xxx.xxx.xxx.xxx" port = 3900 - [[http.services.my_garage_service.loadBalancer.servers]] + [[http.services.garage-s3-service.loadBalancer.servers]] url = "http://yyy.yyy.yyy.yyy" port = 3900 - [[http.services.my_garage_service.loadBalancer.servers]] + [[http.services.garage-s3-service.loadBalancer.servers]] url = "http://zzz.zzz.zzz.zzz" port = 3900 + + [[http.services.garage-web-service.loadBalancer.servers]] + url = "http://xxx.xxx.xxx.xxx" + port = 3902 + [[http.services.garage-web-service.loadBalancer.servers]] + url = "http://yyy.yyy.yyy.yyy" + port = 3902 + [[http.services.garage-web-service.loadBalancer.servers]] + url = "http://zzz.zzz.zzz.zzz" + port = 3902 ``` Traefik can remove unhealthy servers automatically with [a health check configuration](https://doc.traefik.io/traefik/routing/services/#health-check): ``` [http.services] - [http.services.my_garage_service.loadBalancer] - [http.services.my_garage_service.loadBalancer.healthCheck] - path = "/" - interval = "60s" - timeout = "5s" + [http.services.garage-s3-service.loadBalancer] + [http.services.garage-s3-service.loadBalancer.healthCheck] + path = "/health" + port = "3903" + #interval = "15s" + #timeout = "2s" + + [http.services.garage-web-service.loadBalancer] + [http.services.garage-web-service.loadBalancer.healthCheck] + path = "/health" + port = "3903" + #interval = "15s" + #timeout = "2s" ``` ### Adding a website @@ -210,10 +235,15 @@ To add a new website, add the following declaration to your Traefik configuratio ```toml [http.routers] + [http.routers.garage-s3] + rule = "Host(`s3.example.org`)" + service = "garage-s3-service" + entryPoints = ["websecure"] + [http.routers.my_website] rule = "Host(`yoururl.example.org`)" - service = "my_garage_service" - entryPoints = ["web"] + service = "garage-web-service" + entryPoints = ["websecure"] ``` Enable HTTPS access to your website with the following configuration section ([documentation](https://doc.traefik.io/traefik/https/overview/)): @@ -226,7 +256,7 @@ Enable HTTPS access to your website with the following configuration section ([d ... ``` -### Adding gzip compression +### Adding compression Add the following configuration section [to compress response](https://doc.traefik.io/traefik/middlewares/http/compress/) using [gzip](https://developer.mozilla.org/en-US/docs/Glossary/GZip_compression) before sending them to the client: @@ -234,10 +264,10 @@ Add the following configuration section [to compress response](https://doc.traef [http.routers] [http.routers.my_website] ... - middlewares = ["gzip_compress"] + middlewares = ["compression"] ... [http.middlewares] - [http.middlewares.gzip_compress.compress] + [http.middlewares.compression.compress] ``` ### Add caching response @@ -262,27 +292,54 @@ Traefik's caching middleware is only available on [entreprise version](https://d entryPoint = "web" [http.routers] + [http.routers.garage-s3] + rule = "Host(`s3.example.org`)" + service = "garage-s3-service" + entryPoints = ["websecure"] + [http.routers.my_website] rule = "Host(`yoururl.example.org`)" - service = "my_garage_service" - middlewares = ["gzip_compress"] + service = "garage-web-service" + middlewares = ["compression"] entryPoints = ["websecure"] [http.services] - [http.services.my_garage_service.loadBalancer] - [http.services.my_garage_service.loadBalancer.healthCheck] - path = "/" - interval = "60s" - timeout = "5s" - [[http.services.my_garage_service.loadBalancer.servers]] + [http.services.garage-s3-service.loadBalancer] + [http.services.garage-s3-service.loadBalancer.healthCheck] + path = "/health" + port = "3903" + #interval = "15s" + #timeout = "2s" + + [http.services.garage-web-service.loadBalancer] + [http.services.garage-web-service.loadBalancer.healthCheck] + path = "/health" + port = "3903" + #interval = "15s" + #timeout = "2s" + + [[http.services.garage-s3-service.loadBalancer.servers]] + url = "http://xxx.xxx.xxx.xxx" + port = 3900 + [[http.services.garage-s3-service.loadBalancer.servers]] + url = "http://yyy.yyy.yyy.yyy" + port = 3900 + [[http.services.garage-s3-service.loadBalancer.servers]] + url = "http://zzz.zzz.zzz.zzz" + port = 3900 + + [[http.services.garage-web-service.loadBalancer.servers]] url = "http://xxx.xxx.xxx.xxx" - [[http.services.my_garage_service.loadBalancer.servers]] + port = 3902 + [[http.services.garage-web-service.loadBalancer.servers]] url = "http://yyy.yyy.yyy.yyy" - [[http.services.my_garage_service.loadBalancer.servers]] + port = 3902 + [[http.services.garage-web-service.loadBalancer.servers]] url = "http://zzz.zzz.zzz.zzz" + port = 3902 [http.middlewares] - [http.middlewares.gzip_compress.compress] + [http.middlewares.compression.compress] ``` ## Caddy -- cgit v1.2.3 From 3b22da251d68eedb60f9beff7f2e555449ced637 Mon Sep 17 00:00:00 2001 From: Baptiste Jonglez Date: Tue, 28 Feb 2023 09:10:49 +0100 Subject: Add documentation on community Ansible roles --- doc/book/cookbook/_index.md | 6 +++++- doc/book/cookbook/ansible.md | 51 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+), 1 deletion(-) create mode 100644 doc/book/cookbook/ansible.md (limited to 'doc/book/cookbook') diff --git a/doc/book/cookbook/_index.md b/doc/book/cookbook/_index.md index 34e2ed92..a85678fb 100644 --- a/doc/book/cookbook/_index.md +++ b/doc/book/cookbook/_index.md @@ -6,7 +6,7 @@ sort_by = "weight" +++ A cookbook, when you cook, is a collection of recipes. -Similarly, Garage's cookbook contains a collection of recipes that are known to works well! +Similarly, Garage's cookbook contains a collection of recipes that are known to work well! This chapter could also be referred as "Tutorials" or "Best practices". - **[Multi-node deployment](@/documentation/cookbook/real-world.md):** This page will walk you through all of the necessary @@ -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. +- **[Deploying on Kubernetes](@/documentation/cookbook/kubernetes.md):** This page explains how to deploy Garage on Kubernetes using our Helm chart. + +- **[Deploying with Ansible](@/documentation/cookbook/ansible.md):** This page lists available Ansible roles developed by the community to deploy Garage. + - **[Monitoring Garage](@/documentation/cookbook/monitoring.md)** This page explains the Prometheus metrics available for monitoring the Garage cluster/nodes. diff --git a/doc/book/cookbook/ansible.md b/doc/book/cookbook/ansible.md new file mode 100644 index 00000000..6d624c9c --- /dev/null +++ b/doc/book/cookbook/ansible.md @@ -0,0 +1,51 @@ ++++ +title = "Deploying with Ansible" +weight = 35 ++++ + +While Ansible is not officially supported to deploy Garage, several community members +have published Ansible roles. We list them and compare them below. + +## Comparison of Ansible roles + +| Feature | [ansible-role-garage](#zorun-ansible-role-garage) | [garage-docker-ansible-deploy](#moan0s-garage-docker-ansible-deploy) | +|------------------------------------|---------------------------------------------|---------------------------------------------------------------| +| **Runtime** | Systemd | Docker | +| **Target OS** | Any Linux | Any Linux | +| **Architecture** | amd64, arm64, i686 | amd64, arm64 | +| **Additional software** | None | Traefik | +| **Automatic node connection** | ❌ | ✅ | +| **Layout management** | ❌ | ✅ | +| **Manage buckets & keys** | ❌ | ✅ (basic) | +| **Allow custom Garage config** | ✅ | ❌ | +| **Facilitate Garage upgrades** | ✅ | ❌ | +| **Multiple instances on one host** | ✅ | ✅ | + + +## zorun/ansible-role-garage + +[Source code](https://github.com/zorun/ansible-role-garage), [Ansible galaxy](https://galaxy.ansible.com/zorun/garage) + +This role is voluntarily simple: it relies on the official Garage static +binaries and only requires Systemd. As such, it should work on any +Linux-based OS. + +To make things more flexible, the user has to provide a Garage +configuration template. This allows to customize Garage configuration in +any way. + +Some more features might be added, such as a way to automatically connect +nodes to each other or to define a layout. + +## moan0s/garage-docker-ansible-deploy + +[Source code](https://github.com/moan0s/garage-docker-ansible-deploy), [Blog post](https://hyteck.de/post/garage/) + +This role is based on the Docker image for Garage, and comes with +"batteries included": it will additionally install Docker and Traefik. In +addition, it is "opinionated" in the sense that it expects a particular +deployment structure (one instance per disk, one gateway per host, +structured DNS names, etc). + +As a result, this role makes it easier to start with Garage on Ansible, +but is less flexible. -- cgit v1.2.3 From f056ad569dc599ba5f145819bc91a8f15e105347 Mon Sep 17 00:00:00 2001 From: Jonathan Davies Date: Sat, 4 Feb 2023 09:19:19 +0000 Subject: binary-packages.md: Added. --- doc/book/cookbook/_index.md | 4 ++++ doc/book/cookbook/binary-packages.md | 28 ++++++++++++++++++++++++++++ 2 files changed, 32 insertions(+) create mode 100644 doc/book/cookbook/binary-packages.md (limited to 'doc/book/cookbook') diff --git a/doc/book/cookbook/_index.md b/doc/book/cookbook/_index.md index a85678fb..07bf6ebf 100644 --- a/doc/book/cookbook/_index.md +++ b/doc/book/cookbook/_index.md @@ -16,6 +16,10 @@ This chapter could also be referred as "Tutorials" or "Best practices". source in case a binary is not provided for your architecture, or if you want to hack with us! +- **[Binary packages](@/documentation/cookbook/binary-packages.md):** This page + lists the different platforms that provide ready-built software packages for + Garage. + - **[Integration with Systemd](@/documentation/cookbook/systemd.md):** This page explains how to run Garage as a Systemd service (instead of as a Docker container). diff --git a/doc/book/cookbook/binary-packages.md b/doc/book/cookbook/binary-packages.md new file mode 100644 index 00000000..606de2b6 --- /dev/null +++ b/doc/book/cookbook/binary-packages.md @@ -0,0 +1,28 @@ ++++ +title = "Binary packages" +weight = 11 ++++ + +Garage is also available in binary packages on: + +## Alpine Linux + +```bash +apk install garage +``` + +## Arch Linux + +Garage is available in the [AUR](https://aur.archlinux.org/packages/garage). + +## FreeBSD + +```bash +pkg install garage +``` + +## NixOS + +```bash +nix-shell -p garage +``` -- cgit v1.2.3 From 04a0063df93ae354af0eb7e867d315b9932e7ac6 Mon Sep 17 00:00:00 2001 From: yuka Date: Fri, 21 Apr 2023 16:46:58 +0000 Subject: cookbook/real-world: fix typo --- doc/book/cookbook/real-world.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/book/cookbook') diff --git a/doc/book/cookbook/real-world.md b/doc/book/cookbook/real-world.md index 9be1ba44..08266b23 100644 --- a/doc/book/cookbook/real-world.md +++ b/doc/book/cookbook/real-world.md @@ -349,5 +349,5 @@ and is covered in the [quick start guide](@/documentation/quick-start/_index.md) Remember also that the CLI is self-documented thanks to the `--help` flag and the `help` subcommand (e.g. `garage help`, `garage key --help`). -Configuring S3-compatible applicatiosn to interact with Garage +Configuring S3-compatible applications to interact with Garage is covered in the [Integrations](@/documentation/connect/_index.md) section. -- cgit v1.2.3