Upgrade a Notebooks instance's environment

Notebooks instances are Deep Learning VM Images instances with JupyterLab notebook environments enabled and ready for use. This page describes how to upgrade a Notebooks instance's environment.

Upgrade methods

There are two ways to upgrade a Notebooks instance:

  1. Auto upgrade: Enable auto upgrade when you create a Notebooks instance. During a recurring time period that you specify, Notebooks checks whether your instance can be upgraded, and if so, Notebooks upgrades your instance.

  2. Manual upgrade: If an existing Notebooks instance meets the requirements for upgrading, you can upgrade the instance manually.

Requirements and limitations

See the following requirements to determine whether you can upgrade a specific Notebooks instance:

  • The Notebooks API must be enabled in the instance's project.

  • The Notebooks instance's environment must be version M54 or higher. To verify your instance's version, go to the Notebooks page, and find the version number of your instance in the Environment Version column.

  • The Notebooks instance must have been created using the Notebooks API or must have been registered with the Notebooks API.

  • If the Notebooks instance is container-based, Notebooks upgrades the OS, but the image version that is created depends on the specific image pulled by your Dockerfile. Consider using the latest tag to make sure your image is the most recent version.

How the upgrade works

Notebooks instances that can be upgraded are dual-disk, with one boot disk and one data disk. The upgrade process upgrades the boot disk to a new image while preserving your data on the data disk.

Which components are upgraded

The following table shows which components of your Notebooks instance are upgraded and which are preserved.

Component Upgrade result
Machine learning frameworks Upgraded
Machine learning data Preserved
Pre-installed Python dependencies Upgraded
User-installed Python packages Preserved
Pre-installed operating system packages Upgraded
User-installed operating system packages Preserved
GPU drivers Upgraded
Notebooks Preserved
User configurations Preserved

Environment versions

Your Notebooks instance's environment has a version number that you can verify on the Notebooks page, in the Environment Version column.

The available environments are updated with new versions regularly (see the Deep Learning VM release notes), but with each released version, not all of the environments are updated. Notebooks only upgrades an instance if there is a newer environment version for the VM image that your instance is based on.

Auto upgrade

When you enable auto upgrade for a Notebooks instance, you specify a recurring time period in which Notebooks checks whether the instance can be upgraded, and if it can be, upgrades the instance.

The time period you specify is stored as a notebook-upgrade-schedule metadata entry, in unix-cron format, Greenwich Mean Time (GMT)

To check whether an instance can be upgraded, Notebooks uses the API method isUpgradeable. This method checks for a newer version of the image on the instance's boot disk.

If the instance can be upgraded, Notebooks uses upgradeInternal to upgrade the instance.

Create a new instance with auto upgrade enabled

Use the following steps to enable auto upgrade for a new Notebooks instance in the Google Cloud Console or using the gcloud command-line tool.

Use the Google Cloud Console

Complete the following steps to create an auto upgrade-enabled Notebooks instance using the Google Cloud Console.

  1. Follow the steps in Before you begin to create a Google Cloud project and enable the Notebooks API.

  2. Go to the Notebooks page in the Google Cloud Console.

    Go to the Notebooks page

  3. Click New Instance, and then select Customize instance.

    Create new Notebooks instance with options

  4. On the Create a notebook instance page, expand the Environment upgrade and system health section.

  5. Select Enable environment auto-upgrade.

  6. Select either Weekly or Monthly, and then set the Weekday and Hour. When there is an upgrade available for your Notebooks instance, it will restart and upgrade automatically during this time period.

  7. Complete the rest of the dialog to specify the properties of the type of instance that you want.

  8. At the bottom of the dialog, click Create.

Use the gcloud command-line tool

Complete the following steps to create an auto upgrade-enabled Notebooks instance from the command line with the gcloud notebooks instances create command.

  1. From Cloud Shell or any terminal where Cloud SDK is installed, use the following command to create a new Notebooks instance.

    gcloud notebooks instances create INSTANCE_NAME \
      --metadata=notebook-upgrade-schedule=SCHEDULE \
      --vm-image-project=deeplearning-platform-release \
      --vm-image-family=VM_IMAGE_FAMILY \
      --machine-type=MACHINE_TYPE \
      --location=LOCATION
    

    Replace the following:

    • INSTANCE_NAME: the name of your new instance
    • SCHEDULE: the weekly or monthly schedule that you set, in unix-cron format; for example, "00 19 * * MON" means weekly on Monday, at 1900 hours Greenwich Mean Time (GMT)
    • VM_IMAGE_FAMILY: the image family name that you want to use to create your instance
    • MACHINE_TYPE: the machine type of your instance's VM
    • LOCATION: the Google Cloud location where you want your new instance to be
  2. Access your instance from the Notebooks console.

Edit the auto upgrade schedule

To edit the auto upgrade schedule after you have created your Notebooks instance, complete the following steps:

  1. Go to the Notebooks page in the Google Cloud Console.

    Go to the Notebooks page

  2. Under Instance name, click the instance that needs the schedule change.

  3. On the Notebook details page, click Edit.

  4. Under Environment auto-upgrade, edit the schedule.

  5. Click Submit to save your changes.

Manual upgrade

You can manually upgrade Notebooks instances that meet the requirements.

To check whether a newer version of your instance's environment is available, go to the Notebooks page, click the instance name, and on the VM instance details page, a "This instance needs to be upgraded" message appears if a newer version of the environment is available.

Use the following steps to manually upgrade a Notebooks instance in the Google Cloud Console or using the gcloud command-line tool.

Use the Google Cloud Console

Complete the following steps to manually upgrade a Notebooks instance using the Google Cloud Console.

  1. Go to the Notebooks page in the Google Cloud Console.

    Go to the Notebooks page

  2. Under Instance name, click the instance you would like to upgrade.

  3. Click Upgrade.

  4. As a precaution, make a copy of the data on your instance before continuing.

  5. After your data is backed up, click Upgrade. Notebooks upgrades and starts your instance.

Use the gcloud command-line tool

Complete the following steps to create an auto upgrade-enabled Notebooks instance from the command line with the gcloud notebooks instances create command.

  1. To check whether an instance can be upgraded, use the API method isUpgradeable. This method checks for a newer version of the image on the instance's boot disk.

    gcloud notebooks instances is-upgradeable INSTANCE_NAME \
      --location=LOCATION
    

    Replace the following:

    • INSTANCE_NAME: the name of your instance
    • LOCATION: the Google Cloud location where your instance is located

    If the instance is upgradeable, the response is true. It the response is false, the instance cannot be upgraded, but you may still attempt to migrate your data to a new instance.

  2. If the instance is upgradeable, use the API method upgrade to upgrade the instance.

    gcloud notebooks instances upgrade INSTANCE_NAME \
      --location=LOCATION
    

    Notebooks upgrades the instance.

Rollback an upgrade

Complete the following steps to rollback an upgrade.

  1. Go to the Notebooks page in the Google Cloud Console.

    Go to the Notebooks page

  2. Under Instance name, click the instance you would like to rollback.

  3. On the Notebook details page, under Upgrade instance history, click Rollback.

  4. Notebooks rolls your instance back to the previous version.