From ee4d6a01e16ac53fa3e48340a47455281d5f6bc0 Mon Sep 17 00:00:00 2001 From: sptaule Date: Tue, 25 Jan 2022 15:27:39 +0100 Subject: Organized doc md with metadata & draft for doc template --- .../working-documents/migration_06.md | 51 ++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 content/documentation/working-documents/migration_06.md (limited to 'content/documentation/working-documents/migration_06.md') diff --git a/content/documentation/working-documents/migration_06.md b/content/documentation/working-documents/migration_06.md new file mode 100644 index 0000000..692e309 --- /dev/null +++ b/content/documentation/working-documents/migration_06.md @@ -0,0 +1,51 @@ ++++ +title = "Migrating from 0.5 to 0.6" +weight = 15 ++++ + +# 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. -- cgit v1.2.3