Skip to content

Upgrade Nebari

Updated 9 min read

Upgrade Nebari

Section titled “Upgrade Nebari”

Backup existing data

Section titled “Backup existing data”

Perform manual backups of the NFS data and JupyterHub database.

It is strongly recommended you backup your data before upgrading!

Install latest version of Nebari

Section titled “Install latest version of Nebari”

Use pip or conda to install the latest Nebari version.

Terminal window
pip install --upgrade nebari

or

Terminal window
conda update nebari

Nebari upgrade command

Section titled “Nebari upgrade command”

Run the following to upgrade Nebari.

Terminal window
nebari upgrade -c nebari-config.yaml

The upgrade command may print some manual instructions that need to be run before continuing with the upgrade. If so, complete those instructions before continuing on.

Re-deploy Nebari

Section titled “Re-deploy Nebari”

If you are deploying Nebari from your local machine (see this section for CI/CD deployments), you will now have a nebari-config.yaml file that you can deploy.

Terminal window
nebari deploy -c nebari-config.yaml

CI/CD: render and commit to git

Section titled “CI/CD: render and commit to git”

For CI/CD (GitHub/GitLab) workflows, you will need to regenerate the workflow files based on the latest Nebari version's templates.

With the newly upgraded nebari-config.yaml file, run:

Terminal window
nebari render -c nebari-config.yaml

(Note that nebari deploy would perform this render step too, but will also immediately redeploy your Nebari.)

Commit all the files (nebari-config.yaml and GitHub/GitLab workflow files) back to the remote repo. All files need to be committed together in the same commit.

Migrating from QHub (deprecated) to Nebari

Section titled “Migrating from QHub (deprecated) to Nebari”

Backup existing data

Section titled “Backup existing data”

Always backup your data before upgrading!

Locate configuration file

Section titled “Locate configuration file”

Locate your qhub-config.yaml configuration file.

For CI/CD deployments, you will need to git clone <repo URL> into a folder on your local machine if you haven't done so already.

Upgrade the QHub command package

Section titled “Upgrade the QHub command package”

To install (or upgrade) to a specific version of the python package used to manage Nabari, you can run the following, choosing either pip or conda:

Terminal window
pip install --upgrade nebari

or

Terminal window
conda update nebari


### Upgrade `nabari-config.yaml` file


In the folder containing your qhub configuration file, run:


```shell
nebari upgrade -c nebari-config.yaml

Upgrading will output a newer version of nebari-config.yaml that is compatible with the updated version of Nebari. 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 (including a JSON file (nabari-users-import.json) used to import existing users into Keycloak if they are not already there).

Validate special customizations in nebari-config.yaml

Section titled “Validate special customizations in nebari-config.yaml”

You may have made special customizations to your nebari-config.yaml, such as using your own versions of Docker images. Please check your nebari-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 Nebari's images.

Redeploy QHub

Section titled “Redeploy QHub”

For local deployments, run the following:

Terminal window
nebari deploy -c qhub-config.yaml

CI/CD: render and commit to git

Section titled “CI/CD: render and commit to git”

For CI/CD (GitHub/GitLab) workflows, update the workflow files. Run the following with the updated nebari-config.yaml file:

Terminal window
nebari render -c nebari-config.yaml

Commit all the files (nebari-config.yaml and GitHub/GitLab workflow files) back to the remote repo. All files need to be committed together in the same commit.

Upgrade QHub from pre-0.4.0 to another QHub version

Section titled “Upgrade QHub from pre-0.4.0 to another QHub version”

Backup existing data

Section titled “Backup existing data”

Perform manual backups of the NFS data and JupyterHub database.

Always backup your data before upgrading!

Locate configuration file

Section titled “Locate configuration file”

Locate your qhub-config.yaml configuration file.

For CI/CD deployments, you will need to git clone <repo URL> into a folder on your local machine if you haven't done so already.

Upgrade the QHub command package

Section titled “Upgrade the QHub command package”

To install (or upgrade) to a specific version of the python package used to manage QHub, you can run the following, choosing either pip or conda:

Terminal window
pip install --upgrade qhub==<version>

or

Terminal window
conda install qhub=<version>

Upgrade qhub-config.yaml file

Section titled “Upgrade qhub-config.yaml file”

In the folder containing your qhub configuration file, run:

###TO DO: is there a QHub command?

Terminal window
nebari upgrade -c nebari-config.yaml

Upgrading will output a newer version of qhub-config.yaml that is compatible with the updated 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 (including a JSON file (qhub-users-import.json) used to import existing users into Keycloak if they are not already there).

Validate special customizations to qhub-config.yaml

Section titled “Validate special customizations to qhub-config.yaml”

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 QHub's images.

Redeploy QHub

Section titled “Redeploy QHub”

For local deployments, run the following: ###TO DO: is there a QHub command?

Terminal window
nebari 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 current upgrade.

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.

When you are ready, remove the prevent_deploy setting from the config file, and run the nebari deploy -c nebari-config.yaml again.

CI/CD: render and commit to git

Section titled “CI/CD: render and commit to git”

For CI/CD (GitHub/GitLab) workflows, update the workflow files. Run the following with the updated nebari-config.yaml file:

###TO DO: is there a QHub command?

Terminal window
nebari render -c nebari-config.yaml

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.