aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAlex Auvolat <alex@adnab.me>2022-01-10 14:39:35 +0100
committerAlex Auvolat <alex@adnab.me>2022-01-10 14:42:58 +0100
commit9cb2e9e57ce1aab23d8c3b2aaa7581c8e8b78253 (patch)
tree20099632ccaf1be7b0719290fa323ce88ec9b358
parent3586c7257cf9abe095f934227794627f8cdf7182 (diff)
downloadgarage-update-documentation.tar.gz
garage-update-documentation.zip
Add documentation to migrate to 0.6update-documentationcreate-delete-buckets
-rw-r--r--doc/book/src/SUMMARY.md1
-rw-r--r--doc/book/src/working_documents/migration_06.md46
2 files changed, 47 insertions, 0 deletions
diff --git a/doc/book/src/SUMMARY.md b/doc/book/src/SUMMARY.md
index e1b77cfd..d9b76e96 100644
--- a/doc/book/src/SUMMARY.md
+++ b/doc/book/src/SUMMARY.md
@@ -44,5 +44,6 @@
- [Working Documents](./working_documents/index.md)
- [S3 compatibility target](./working_documents/compatibility_target.md)
- [Load balancing data](./working_documents/load_balancing.md)
+ - [Migrating from 0.5 to 0.6](./working_documents/migration_06.md)
- [Migrating from 0.3 to 0.4](./working_documents/migration_04.md)
- [Design draft](./working_documents/design_draft.md)
diff --git a/doc/book/src/working_documents/migration_06.md b/doc/book/src/working_documents/migration_06.md
new file mode 100644
index 00000000..4312e37d
--- /dev/null
+++ b/doc/book/src/working_documents/migration_06.md
@@ -0,0 +1,46 @@
+# Migrating from 0.5 to 0.6
+
+**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. 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!
+
+10. Your upgraded cluster should be in a working state. Re-enable API and Web
+ access and check that everything went well.