From 69bcc813de462a8b13388d11b491146c937b8d9a Mon Sep 17 00:00:00 2001 From: Alex Auvolat Date: Mon, 26 Sep 2022 17:41:38 +0200 Subject: [PATCH 1/2] Add garage v0.8 migration guide --- doc/book/working-documents/migration-07.md | 2 +- doc/book/working-documents/migration-08.md | 34 ++++++++++++++++++++++ 2 files changed, 35 insertions(+), 1 deletion(-) create mode 100644 doc/book/working-documents/migration-08.md diff --git a/doc/book/working-documents/migration-07.md b/doc/book/working-documents/migration-07.md index 2d0444db7..03cdfedcb 100644 --- a/doc/book/working-documents/migration-07.md +++ b/doc/book/working-documents/migration-07.md @@ -16,7 +16,7 @@ The migration steps are as follows: 1. Do `garage repair --all-nodes --yes tables` and `garage repair --all-nodes --yes blocks`, check the logs and check that all data seems to be synced correctly between nodes. If you have time, do additional checks (`scrub`, `block_refs`, etc.) -2. Disable api and web access. Garage does not support disabling +2. Disable API and web access. Garage does not support disabling these endpoints but you can change the port number or stop your reverse proxy for instance. 3. Check once again that your cluster is healty. Run again `garage repair --all-nodes --yes tables` which is quick. diff --git a/doc/book/working-documents/migration-08.md b/doc/book/working-documents/migration-08.md new file mode 100644 index 000000000..5f97c45ba --- /dev/null +++ b/doc/book/working-documents/migration-08.md @@ -0,0 +1,34 @@ ++++ +title = "Migrating from 0.7 to 0.8" +weight = 13 ++++ + +**This guide explains how to migrate to 0.8 if you have an existing 0.7 cluster. +We don't recommend trying to migrate to 0.8 directly from 0.6 or older.** + +**We make no guarantee that this migration will work perfectly: +back up all your data before attempting it!** + +Garage v0.8 introduces new data tables that allow the counting of objects in buckets in order to implement bucket quotas. +A manual migration step is required to first count objects in Garage buckets and populate these tables with accurate data. + +The migration steps are as follows: + +1. Disable API and web access. Garage v0.7 does not support disabling + these endpoints but you can change the port number or stop your reverse proxy for instance. +2. Do `garage repair --all-nodes --yes tables` and `garage repair --all-nodes --yes blocks`, + check the logs and check that all data seems to be synced correctly between + nodes. If you have time, do additional checks (`scrub`, `block_refs`, etc.) +3. Check that queues are empty: run `garage stats` to query them or inspect metrics in the Grafana dashboard. +4. Turn off Garage v0.7 +5. **Backup the metadata folder of all your nodes!** For instance, use the following command + if your metadata directory is `/var/lib/garage/meta`: `cd /var/lib/garage ; tar -acf meta-v0.7.tar.zst meta/` +6. Install Garage v0.8 +7. **Before starting Garage v0.8**, run the offline migration step: `garage offline-repair --yes object_counters`. + This can take a while to run, depending on the number of objects stored in your cluster. +8. Turn on Garage v0.8 +9. Do `garage repair --all-nodes --yes tables` and `garage repair --all-nodes --yes blocks`. + Wait for a full table sync to run. +10. Your upgraded cluster should be in a working state. Re-enable API and Web + access and check that everything went well. +11. Monitor your cluster in the next hours to see if it works well under your production load, report any issue. From 194e8be1bbed076ca811176123cc07abb4a8d04d Mon Sep 17 00:00:00 2001 From: Alex Auvolat Date: Mon, 26 Sep 2022 18:01:17 +0200 Subject: [PATCH 2/2] Update docker image links --- doc/book/cookbook/real-world.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/book/cookbook/real-world.md b/doc/book/cookbook/real-world.md index e101a7065..4fcb5cf78 100644 --- a/doc/book/cookbook/real-world.md +++ b/doc/book/cookbook/real-world.md @@ -51,15 +51,15 @@ to store 2 TB of data in total. ## Get a Docker image -Our docker image is currently named `dxflrs/amd64_garage` and is stored on the [Docker Hub](https://hub.docker.com/r/dxflrs/amd64_garage/tags?page=1&ordering=last_updated). -We encourage you to use a fixed tag (eg. `v0.4.0`) and not the `latest` tag. -For this example, we will use the latest published version at the time of the writing which is `v0.4.0` but it's up to you -to check [the most recent versions on the Docker Hub](https://hub.docker.com/r/dxflrs/amd64_garage/tags?page=1&ordering=last_updated). +Our docker image is currently named `dxflrs/garage` and is stored on the [Docker Hub](https://hub.docker.com/r/dxflrs/garage/tags?page=1&ordering=last_updated). +We encourage you to use a fixed tag (eg. `v0.8.0`) and not the `latest` tag. +For this example, we will use the latest published version at the time of the writing which is `v0.8.0` but it's up to you +to check [the most recent versions on the Docker Hub](https://hub.docker.com/r/dxflrs/garage/tags?page=1&ordering=last_updated). For example: ``` -sudo docker pull dxflrs/amd64_garage:v0.4.0 +sudo docker pull dxflrs/garage:v0.8.0 ``` ## Deploying and configuring Garage @@ -125,7 +125,7 @@ docker run \ -v /etc/garage.toml:/etc/garage.toml \ -v /var/lib/garage/meta:/var/lib/garage/meta \ -v /var/lib/garage/data:/var/lib/garage/data \ - lxpz/garage_amd64:v0.4.0 + dxflrs/garage:v0.8.0 ``` It should be restarted automatically at each reboot.