Upgrade the environment of a user-managed notebooks instance

User-managed notebooks instances are Deep Learning VM Images instances with JupyterLab notebook environments enabled and ready for use. This page describes how to upgrade the environment of a user-managed notebooks instance.

Upgrade methods

There are two ways to upgrade a user-managed notebooks instance:

  • Automatic upgrade: Enable auto upgrade when you create a user-managed notebooks instance. During a recurring time period that you specify, Vertex AI Workbench checks whether your instance can be upgraded, and if so, Vertex AI Workbench upgrades your instance.

  • Manual upgrade: If an existing user-managed notebooks instance meets the requirements for upgrading, you can upgrade the instance manually.

Requirements and limitations

Backward compatibility with your user-managed notebooks isn't guaranteed. Back up your data before upgrading a user-managed notebooks instance.

To determine whether you can upgrade a specific user-managed notebooks instance, see the following requirements and limitations:

How the upgrade works

User-managed 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 user-managed notebooks instance are upgraded and which are preserved.

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

Environment versions

Your user-managed notebooks instance has an environment version number that you can verify:

  1. In the Google Cloud console, go to the User-managed notebooks page.

    Go to User-managed notebooks

  2. In the Environment version column, find the version number of your instance.

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

For information about how to use a specific version to create a user-managed notebooks instance, see Create a specific version of a user-managed notebooks instance.

Automatic upgrade

Vertex AI Workbench can automatically upgrade instances that are running. If your instance is stopped, it doesn't automatically upgrade your instance, even if you enabled auto upgrade when you created it.

When you enable automatic environment upgrades, you specify a recurring time period in which Vertex AI Workbench 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, Vertex AI Workbench 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, Vertex AI Workbench uses the upgradeInternal method to upgrade the instance.

Create a user-managed notebooks instance with auto upgrade enabled

To create a user-managed notebooks instance with auto upgrade enabled, select the Enable environment auto-upgrade checkbox and set a schedule when you create the instance.

You can specify auto-upgrade by using either the Google Cloud console, notebook.new (https://notebook.new), or the Google Cloud CLI.

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

Console

  1. In the Google Cloud console, go to the User-managed notebooks page.

    Go to User-managed notebooks

  2. Click  New notebook, and then select Customize instance.

  3. The Create a user-managed notebook page opens.

    For information about enabling auto upgrade, see Environment upgrade and system health.

notebook.new

  1. Go to notebook.new (https://notebook.new).

  2. The Create a user-managed notebook dialog opens.

    For information about enabling auto upgrade, see Environment upgrade and system health.

gcloud

  1. From Cloud Shell or any environment where the Google Cloud CLI is installed, enter the following Google Cloud CLI command:

     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 Cloud console.

Edit the auto upgrade schedule

To edit the auto upgrade schedule after you have created your user-managed notebooks instance, complete the following steps:

  1. In the Google Cloud console, go to the User-managed notebooks page.

    Go to User-managed notebooks

  2. Click the instance name that needs the schedule change.

  3. On the Notebook details page, click  Edit.

  4. In Upgrade schedule, edit the schedule.

  5. Click Submit to save your changes.

Manual upgrade

You can manually upgrade user-managed notebooks instances that meet the requirements.

Check for a newer version of your instance's environment

To check whether a newer version of your instance's environment is available, access your instance from the Cloud console.

  1. In the Google Cloud console, go to the User-managed notebooks page.

    Go to User-managed notebooks

  2. Click the instance name that you want to check for availability of a newer environment version.

  3. On the Notebook details page, click  View VM details.

    If a newer version of the environment is available, a "This instance needs to be upgraded" message appears.

Upgrade your instance's environment to a newer version

You can manually upgrade a user-managed notebooks instance in the Google Cloud console or by using the Google Cloud CLI.

Console

  1. In the Google Cloud console, go to the User-managed notebooks page.

    Go to User-managed notebooks

  2. Click the instance name that you want to upgrade.

  3. On the Notebook details page, 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. Vertex AI Workbench upgrades and starts your instance.

gcloud

  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 upgradable, the response is true. If the response is false, the instance cannot be upgraded, but you can still attempt to migrate your data to a new instance.

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

  3. If the instance is upgradable, use the API method upgrade to upgrade the instance:

    gcloud notebooks instances upgrade INSTANCE_NAME \
        --location=LOCATION
    

    Vertex AI Workbench upgrades the instance.

Roll back an upgrade

To roll back an upgrade, complete the following steps:

  1. In the Google Cloud console, go to the User-managed notebooks page.

    Go to User-managed notebooks

  2. Click the instance name that you would like to roll back.

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

  4. Vertex AI Workbench rolls your instance back to the previous version.