From 9cb2e9e57ce1aab23d8c3b2aaa7581c8e8b78253 Mon Sep 17 00:00:00 2001 From: Alex Auvolat Date: Mon, 10 Jan 2022 14:39:35 +0100 Subject: [PATCH] Add documentation to migrate to 0.6 --- doc/book/src/SUMMARY.md | 1 + .../src/working_documents/migration_06.md | 46 +++++++++++++++++++ 2 files changed, 47 insertions(+) create mode 100644 doc/book/src/working_documents/migration_06.md 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.