diff --git a/doc/book/working-documents/migration-04.md b/doc/book/working-documents/migration-04.md index 52c56737..5aae2a42 100644 --- a/doc/book/working-documents/migration-04.md +++ b/doc/book/working-documents/migration-04.md @@ -1,6 +1,6 @@ +++ title = "Migrating from 0.3 to 0.4" -weight = 20 +weight = 80 +++ **Migrating from 0.3 to 0.4 is unsupported. This document is only intended to diff --git a/doc/book/working-documents/migration-06.md b/doc/book/working-documents/migration-06.md index 006b036b..5fa29120 100644 --- a/doc/book/working-documents/migration-06.md +++ b/doc/book/working-documents/migration-06.md @@ -1,6 +1,6 @@ +++ title = "Migrating from 0.5 to 0.6" -weight = 15 +weight = 75 +++ **This guide explains how to migrate to 0.6 if you have an existing 0.5 cluster. diff --git a/doc/book/working-documents/migration-07.md b/doc/book/working-documents/migration-07.md index 03cdfedc..392c75a9 100644 --- a/doc/book/working-documents/migration-07.md +++ b/doc/book/working-documents/migration-07.md @@ -1,6 +1,6 @@ +++ title = "Migrating from 0.6 to 0.7" -weight = 14 +weight = 74 +++ **This guide explains how to migrate to 0.7 if you have an existing 0.6 cluster. We don't recommend trying to migrate to 0.7 directly from 0.5 or older.** diff --git a/doc/book/working-documents/migration-08.md b/doc/book/working-documents/migration-08.md index b7c4c783..17fe078b 100644 --- a/doc/book/working-documents/migration-08.md +++ b/doc/book/working-documents/migration-08.md @@ -1,6 +1,6 @@ +++ title = "Migrating from 0.7 to 0.8" -weight = 13 +weight = 73 +++ **This guide explains how to migrate to 0.8 if you have an existing 0.7 cluster. diff --git a/doc/book/working-documents/migration-09.md b/doc/book/working-documents/migration-09.md index ba758093..cf5f309c 100644 --- a/doc/book/working-documents/migration-09.md +++ b/doc/book/working-documents/migration-09.md @@ -1,6 +1,6 @@ +++ title = "Migrating from 0.8 to 0.9" -weight = 12 +weight = 72 +++ **This guide explains how to migrate to 0.9 if you have an existing 0.8 cluster. diff --git a/doc/book/working-documents/migration-1.md b/doc/book/working-documents/migration-1.md index b6c0bb85..9a04d101 100644 --- a/doc/book/working-documents/migration-1.md +++ b/doc/book/working-documents/migration-1.md @@ -1,6 +1,6 @@ +++ title = "Migrating from 0.9 to 1.0" -weight = 11 +weight = 71 +++ **This guide explains how to migrate to 1.0 if you have an existing 0.9 cluster. diff --git a/doc/book/working-documents/migration-2.md b/doc/book/working-documents/migration-2.md new file mode 100644 index 00000000..f40d16df --- /dev/null +++ b/doc/book/working-documents/migration-2.md @@ -0,0 +1,70 @@ ++++ +title = "Migrating from 1.0 to 2.0" +weight = 70 ++++ + +**This guide explains how to migrate to v2.x if you have an existing v1.x.x cluster. +We don't recommend trying to migrate to v2.x directly from v0.9.x or older.** + +This migration procedure has been tested on several clusters without issues. +However, it is still a *critical procedure* that might cause issues. +**Make sure to back up all your data before attempting it!** + +You might also want to read our [general documentation on upgrading Garage](@/documentation/operations/upgrading.md). + +## Changes introduced in v2.0 + +The following are **breaking changes** in Garage v2.0 that require your attention when migrating: + +- The administration API has been completely reworked. + Some calls to the `/v1/` endpoints will still work but most will not. + New endpoints are prefixed by `/v2/`. **You will need to update all your code that makes use of the admin API.** + +- `replication_mode` is no longer a supported configuration parameter, + please use `replication_factor` and `consistency_mode` instead. + +## Migration procedure + +The migration to Garage v2.0 can be done with almost no downtime, +by restarting all nodes at once in the new version. + +The migration steps are as follows: + +1. Do a `garage repair --all-nodes --yes tables`, check the logs and check that + all data seems to be synced correctly between nodes. If you have time, do + additional `garage repair` procedures (`blocks`, `versions`, `block_refs`, + etc.) + +2. Ensure you have a snapshot of your Garage installation that you can restore + to in case the upgrade goes wrong, with one of the following options: + + - You may use the `garage meta snapshot --all` command + to make a backup snapshot of the metadata directories of your nodes + for backup purposes. Once this command has completed, copy the following + files and directories from the `metadata_dir` of all your nodes + to somewhere safe: `snapshots`, `cluster_layout`, `data_layout`, + `node_key`, `node_key.pub`. (If you have set the `metadata_snapshots_dir` + to a different value in your config file, back up that directory instead.) + + - If you are running a filesystem such as ZFS or BTRFS that support + snapshotting, you can create a filesystem-level snapshot of the `metadata_dir` + of all your nodes to be used as a restoration point if needed. + + - You may also make a back-up manually: turn off each node + individually; back up its metadata folder (for instance, use the following + command if your metadata directory is `/var/lib/garage/meta`: `cd + /var/lib/garage ; tar -acf meta-v0.9.tar.zst meta/`); turn it back on + again. This will allow you to take a backup of all nodes without + impacting global cluster availability. You can do all nodes of a single + zone at once as this does not impact the availability of Garage. + +3. Prepare your updated binaries and configuration files for Garage v2.0. + **Remember to update your configuration file to remove `replication_mode` and replace it by `replication_factor`.** + +4. Shut down all v1.0 nodes simultaneously, and restart them all simultaneously + in v2.0. Use your favorite deployment tool (Ansible, Kubernetes, Nomad) to + achieve this as fast as possible. Garage v2.0 should be in a working state + as soon as enough nodes have started. + +5. Monitor your cluster in the following hours to see if it works well under + your production load. diff --git a/doc/book/working-documents/testing-strategy.md b/doc/book/working-documents/testing-strategy.md index fff706d7..3c29e47b 100644 --- a/doc/book/working-documents/testing-strategy.md +++ b/doc/book/working-documents/testing-strategy.md @@ -1,6 +1,6 @@ +++ title = "Testing strategy" -weight = 30 +weight = 100 +++