aboutsummaryrefslogtreecommitdiff
path: root/doc/book/working-documents/migration-06.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/book/working-documents/migration-06.md')
-rw-r--r--doc/book/working-documents/migration-06.md53
1 files changed, 53 insertions, 0 deletions
diff --git a/doc/book/working-documents/migration-06.md b/doc/book/working-documents/migration-06.md
new file mode 100644
index 00000000..28e2c32e
--- /dev/null
+++ b/doc/book/working-documents/migration-06.md
@@ -0,0 +1,53 @@
++++
+title = "Migrating from 0.5 to 0.6"
+weight = 15
++++
+
+**This guide explains how to migrate to 0.6 if you have an existing 0.5 cluster.
+We don't recommend trying to migrate directly from 0.4 or older to 0.6.**
+
+**We make no guarantee that this migration will work perfectly:
+back up all your data before attempting it!**
+
+Garage v0.6 (not yet released) introduces a new data model for buckets,
+that allows buckets to have many names (aliases).
+Buckets can also have "private" aliases (called local aliases),
+which are only visible when using a certain access key.
+
+This new data model means that the metadata tables have changed quite a bit in structure,
+and a manual migration step is required.
+
+The migration steps are as follows:
+
+1. Disable api and web access for some time (Garage does not support disabling
+ these endpoints but you can change the port number or stop your reverse
+ proxy for instance).
+
+2. Do `garage repair -a --yes tables` and `garage repair -a --yes blocks`,
+ check the logs and check that all data seems to be synced correctly between
+ nodes.
+
+4. Turn off Garage 0.5
+
+5. **Backup your metadata folders!!**
+
+6. Turn on Garage 0.6
+
+7. At this point, `garage bucket list` should indicate that no buckets are present
+ in the cluster. `garage key list` should show all of the previously existing
+ access key, however these keys should not have any permissions to access buckets.
+
+8. Run `garage migrate buckets050`: this will populate the new bucket table with
+ the buckets that existed previously. This will also give access to API keys
+ as it was before.
+
+9. Do `garage repair -a --yes tables` and `garage repair -a --yes blocks`,
+ check the logs and check that all data seems to be synced correctly between
+ nodes.
+
+10. Check that all your buckets indeed appear in `garage bucket list`, and that
+ keys have the proper access flags set. If that is not the case, revert
+ everything and file a bug!
+
+11. Your upgraded cluster should be in a working state. Re-enable API and Web
+ access and check that everything went well.