This is a guide to the general upgrade of QHub to a new version.
You should always backup your data before upgrading.
Note that for some releases (e.g. to v0.4), the cluster cannot be upgraded in-situ so you must perform a redeployment (backup the old cluster, redeploy a new upgraded cluster and then restore your data).
To perform a redeployment upgrade see the breaking upgrade documentation.
Here we suppose a user would like to upgrade to a version
<version>, probably the latest full release of
QHub on PyPI.
You may be deploying QHub based on a local configuration file, or you may be using CI/CD workflows in GitHub or GitLab.
Either way, you will need to locate a copy of your
qhub-config.yaml configuration file to upgrade it (and commit back
to your git repo in the CI/CD case).
For CI/CD deployments, you will need to
git clone <repo URL> into a folder on your local machine if you haven’t done
Step 1: Upgrade the
qhub command package#
To install (or upgrade) your pip installation of the Python package used to manage QHub:
pip install --upgrade qhub
The above will install the latest full version of QHub. For a specific older version use:
pip install --upgrade qhub==<version>
Step 2: Upgrade
In the folder containing your QHub configuration file, run:
qhub upgrade -c qhub-config.yaml
This will output a newer version of
qhub-config.yaml that’s compatible with the new version of
qhub. The process
outputs a list of changes it has made. The
upgrade command creates a copy of the original unmodified config file
qhub-config.yaml.old.backup) as well as any other files that may be required by the upgraded cluster (if any).
Step 3: Validate special customizations to
You may have made special customizations to your
qhub-config.yaml, such as using your own versions of Docker images.
Please check your
qhub-config.yaml and decide if you need to update any values that would not have been changed
automatically - or, for example, you may need to build new versions of your custom Docker images to match any changes in
Step 4: Redeploy QHub#
If you are deploying QHub from your local machine (not using CI/CD) then you will now have a
that you can deploy.
qhub deploy -c qhub-config.yaml
At this point you may see an error message saying that deployment is prevented due to the
prevent_deploy setting in
your YAML file. This is a safeguard to ensure that you only proceed if you are aware of possible breaking changes in the
For example, we may be aware that you will lose data due to this upgrade, so need to note a specific upgrade process to keep your data safe. Always check the release notes of the release in this case and get in touch with us if you need assistance. For example, you may find that your existing cluster is intentionally deleted so that a new replacement can be deployed instead, in which case your data must be backed up so it can be restored after the upgrade.
CI/CD: render and commit to git#
For CI/CD (GitHub/GitLab) workflows, then as well as generating the updated
qhub-config.yaml files as above, you will
also need to regenerate the workflow files based on the latest
qhub version’s templates.
With the newly upgraded
qhub-config.yaml file, run:
qhub render -c qhub-config.yaml
qhub deploy would perform this render step too, but will also immediately redeploy your QHub.)
Commit all the files (
qhub-config.yaml and GitHub/GitLab workflow files) back to the remote repo. All files need to be
committed together in the same commit.