Upgrade to 0.4.0 [documentation]

[danlester]

We need to work out communications to help upgrade to version 0.4.0. This could be a combination of release notes and docs.

There are general upgrade docs ready to be released but these are not specific to 0.4.0 which may need special consideration especially in light of #1040.

My suggested process

Assumes #1047 and #957 have been merged.

Backup and move existing URL

Using the old version of qhub:

1. Perform manual backups (Complication: after release the docs will include details about Keycloak, but the only thing relevant will just be Zipping up the NFS files).

2. Rename the existing domain

This will allow the existing cluster to remain alive in case it is needed, but the idea would be not to have it in use from now on.

In the qhub-config.yaml for example:

project_name: myqhub
domain: qhub.myproj.com

could become:

project_name: myqhub
domain: qhub-old.myproj.com

Run qhub deploy using the existing (old) version of qhub.

Upgrade the config file

Now we need to go back to the original qhub-config.yaml file which contained the original domain.

Run the general upgrade docs process up to the point before redeployment.

Actually, I've noticed that steps 5 and 6 are specific to the 0.4.0 upgrade, so should probably be marked as such. They could be moved to 0.4.0-specific documentation, but of course they may also be required if someone upgrades directly from 0.3.14 -> 0.4.1.

You should end up with a new qhub-config.yaml file and a qhub-users-import.json.

Rename the project

Need to rename the project to avoid clashes with the existing (old) cluster. The domain should remain as the preferred main one that was always in use previously.

For example:

project_name: myqhub
domain: qhub.myproj.com

could become:

project_name: myqhubnew
domain: qhub.myproj.com

Deploy and restore backups

When attempting to redeploy, it should first fail due to prevent_deploy flag needing to be removed for safety.

After deployment, carry out steps 5 and 6 of the general upgrade docs (OAuth URL updates if relevant, plus inport Keycloak users).

Change the Keycloak root password at /auth URL - don't update the qhub-config.yaml file to reflect this.

Restore NFS from backup - docs needed...

Also need to chown all uids immediately after restore while the 'restore pod' is mounted:

chown -R 1000:100 /mnt/home

[magsol]

Too technical for release notes, too specific for upgrade notes. Where should this go in the docs?