docs: add a guide for migrating from Hydra v1 to Hydra v2

[grantzvolsky]

Related Issue or Design Document

Checklist

• [x] I have read the contributing guidelines and signed the CLA.
• [ ] I have referenced an issue containing the design document if my change introduces a new feature.
• [x] I have read the security policy.
• [x] I confirm that this pull request does not address a security vulnerability. If this pull request addresses a security vulnerability, I confirm that I got green light (please contact [email protected]) from the maintainers to push the changes.
• [ ] I have added tests that prove my fix is effective or that my feature works.
• [ ] I have added necessary documentation within the code base (if appropriate).

Further comments

[tomekpapiernik]

Hey @grantzvolsky, I checked out this document and I have some doubts whether this should be a separate document at all. From what I can see, there's barely anything "new" here when I compare the process to the general upgrade guide for Hydra.

I feel that any specifics of the process could be added to the existing "upgrade" document - there are just one or two things that look like they're Hydra v2-specific. Is deploying to a "dry-run env" something that's absolutely necessary? I get why you included this in the document, but truth be told - this is something the users can do if they want to, but if they're feeling adventurous they can apply the upgrade on "prod", right? Hence, this looks more like a suggestion to me.

This document is also very inconsistent when it comes to the terminology it uses. On one occasion it's "upgrade", then it's "migration". From my point of view, bringing up software to a new version is an upgrade, while moving data between containers is a migration. So in this case, you upgrade Hydra to v2 and a part of this process is migrating the SQL DB.

Also, you say that there's no downgrade path from v2. Is this by any chance true for other versions?

[grantzvolsky]

@tomekpapiernik

From what I can see, there's barely anything "new" here when I compare the process to the general upgrade guide for Hydra.

It is positive that we have been able to make the migration to Hydra 2.x automatic, as it was initially unclear whether this would be possible. We achieved this with some rather heavy migrations, so while it is possible to carry out the migration without manual intervention, it does require a great deal of care.

I feel that any specifics of the process could be added to the existing "upgrade" document - there are just one or two things that look like they're Hydra v2-specific.

Eventually, yes, that is a good idea to update the existing upgrade document with bits of the process presented here.

This document is also very inconsistent when it comes to the terminology it uses. On one occasion it's "upgrade", then it's "migration".

Upgrade refers to code. Migration refers to data. Please highlight the usages where this distinction isn't clear.

Is deploying to a "dry-run env" something that's absolutely necessary?

Different deployments will have different requirements and preferences. The point of this guide is to cover the essentials that minimize the risk of something going wrong. However, due to the diversity of environments in which Hydra is deployed, the guide cannot be prescriptive. Furthermore, the reason for this guide to be in a separate document is to make it easier to collect and integrate feedback specifically for the 2.x release. As stated above, the migrations included here are quite heavy.

Also, you say that there's no downgrade path from v2. Is this by any chance true for other versions?

One should not generally rely on down migrations, but v2 is an exception in that it doesn't offer them.

[grantzvolsky]

@aeneasr I expect that we'll add more information after we get feedback from beta testers, but for now this is it. Any feedback is welcome.

By the way, should I close this PR and add the changes to https://github.com/ory/docs/pull/874 instead?

[piotrmsc]

@grantzvolsky please take a look on comments after review :)

[grantzvolsky]

@tomekpapiernik I've updated the title & added some comments.

[tomekpapiernik]

@grantzvolsky I talked to @piotrmsc yesterday and I think I understand the process now. From what I understood, it all boils down to:

1. Download the new Hydra CLI version.
2. Run the hydra migrate sql command to migrate the DB to the "new, v2 format".
3. Run the newest version of Hydra, however you (the user) do it in your setup.

This process is described in the existing document here: https://www.ory.sh/docs/hydra/guides/upgrade

If you feel the v1 to v2 migration needs any additional procedures other than these, please add them to the existing documents. IMO adding one more document that's basically the same content but with just a little-to-no twist won't do users no good and will rather unnecessarily confuse them.