aboutsummaryrefslogtreecommitdiff
path: root/doc/book/working-documents/migration-07.md
diff options
context:
space:
mode:
authorQuentin Dufour <quentin@deuxfleurs.fr>2022-04-05 10:05:44 +0200
committerQuentin Dufour <quentin@deuxfleurs.fr>2022-04-05 10:08:31 +0200
commita122a8cb464e78e1b5f2454aef91f12d647b1b6c (patch)
tree331f09b969d2b7727a48e275ab58f3c02c6168cf /doc/book/working-documents/migration-07.md
parent9fd8ec1dee367c773d51cdc035879ea43abb1cbf (diff)
downloadgarage-a122a8cb464e78e1b5f2454aef91f12d647b1b6c.tar.gz
garage-a122a8cb464e78e1b5f2454aef91f12d647b1b6c.zip
Add an "upgrading" section, add a guide for 0.7
Diffstat (limited to 'doc/book/working-documents/migration-07.md')
-rw-r--r--doc/book/working-documents/migration-07.md31
1 files changed, 31 insertions, 0 deletions
diff --git a/doc/book/working-documents/migration-07.md b/doc/book/working-documents/migration-07.md
new file mode 100644
index 00000000..d4ef4d9e
--- /dev/null
+++ b/doc/book/working-documents/migration-07.md
@@ -0,0 +1,31 @@
++++
+title = "Migrating from 0.6 to 0.7"
+weight = 14
++++
+**This guide explains how to migrate to 0.7 if you have an existing 0.6 cluster.
+We don't recommend trying to migrate directly from older to 0.6.**
+
+**We make no guarantee that this migration will work perfectly:
+back up all your data before attempting it!**
+
+Garage v0.7 introduces a cluster protocol change to support request tracing through OpenTelemetry.
+No data structure is changed, so no data migration is required.
+
+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
+ 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.
+ Also check your queues are empty, run `garage stats` to query them.
+4. Turn off Garage v0.6
+5. Backup the metadata folder of all your nodes: `cd /var/lib/garage ; tar -acf meta-v0.6.tar.zst meta/`
+6. Install Garage v0.7, edit the configuration if you plan to use OpenTelemetry or the Kubernetes integration
+7. Turn on Garage v0.7
+8. Do `garage repair --all-nodes --yes tables` and `garage repair --all-nodes --yes blocks`
+9. Your upgraded cluster should be in a working state. Re-enable API and Web
+ access and check that everything went well.
+10. Monitor your cluster in the next hours to see if it works well under your production load, report any issue.