Add documentation to migrate to 0.6
All checks were successful
continuous-integration/drone/pr Build is passing
continuous-integration/drone/push Build is passing
continuous-integration/drone Build is passing

This commit is contained in:
Alex 2022-01-10 14:39:35 +01:00
parent 3586c7257c
commit 9cb2e9e57c
No known key found for this signature in database
GPG key ID: EDABF9711E244EB1
2 changed files with 47 additions and 0 deletions

View file

@ -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)

View file

@ -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.