Upgrade a user-managed notebooks instance's environment

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 a user-managed notebooks instance's environment.

Upgrade methods

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

  1. Auto 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.

  2. Manual upgrade: If an existing user-managed 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 user-managed notebooks instance:

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

  • The user-managed notebooks instance's environment must be version M54 or higher. To verify your instance's version, go to the Notebooks page, and on the User-managed notebooks tab, find the version number of your instance in the Environment version column.

  • The user-managed notebooks instance must have been created using the Notebooks API or must have been registered with the Notebooks API.

  • If the user-managed notebooks instance is container-based, Vertex AI Workbench upgrades the OS, but the image version that is created depends on the specific image pulled by your Dockerfile. Consider including the latest tag in your Dockerfile to help make sure the upgrade uses the most recent version of the image.

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's environment has a version number that you can verify on the User-managed 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. Vertex AI Workbench 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 user-managed notebooks instance, 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 upgradeInternal to upgrade the instance.

Create a new instance with auto upgrade enabled

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

Use the Google Cloud Console

Complete the following steps to create an auto upgrade-enabled user-managed 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. In the Google Cloud Console, go to the Notebooks page.

    Go to Notebooks

  3. Make sure the User-managed notebooks tab is selected.

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

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

  6. Select Enable environment auto-upgrade.

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

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

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

Use the gcloud command-line tool

Complete the following steps to create an auto upgrade-enabled user-managed 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 user-managed 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 User-managed notebooks page.

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 Notebooks page.

    Go to Notebooks

  2. On the User-managed notebooks tab, select 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 user-managed 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 user-managed 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 user-managed notebooks instance using the Google Cloud Console.

  1. In the Google Cloud Console, go to the Notebooks page.

    Go to Notebooks

  2. On the User-managed notebooks tab, select 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. Vertex AI Workbench upgrades and starts your instance.

Use the gcloud command-line tool

Complete the following steps to create an auto upgrade-enabled user-managed 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
    

    Vertex AI Workbench upgrades the instance.

Roll back an upgrade

Complete the following steps to roll back an upgrade.

  1. In the Google Cloud Console, go to the Notebooks page.

    Go to Notebooks

  2. On the User-managed notebooks tab, select the instance you would like to roll back.

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

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