Upgrade the environment of an instance

Vertex AI Workbench 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 Vertex AI Workbench instance.

Reasons to upgrade

You might want to upgrade the environment of your Vertex AI Workbench instance for any of the following reasons:

  • To use new capabilities that are only available in a newer version of your environment.

  • To benefit from framework updates, package updates, and bug fixes that have been implemented in a newer version of your environment.

Upgrade methods

There are two ways to upgrade a Vertex AI Workbench instance:

  • Automatic upgrade: Enable auto upgrade when you create a Vertex AI Workbench 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 Vertex AI Workbench instance meets the requirements for upgrading, you can upgrade the instance manually.

Requirements and limitations

Backward compatibility with your Vertex AI Workbench isn't guaranteed. Make a copy of your data before upgrading a Vertex AI Workbench instance.

To determine whether you can upgrade a specific Vertex AI Workbench instance, see the following requirements and limitations:

  • The Notebooks API must be enabled in the instance's Google Cloud project. For more information, see List enabled services and Enable an API.

  • If your Vertex AI Workbench instance is container-based, Vertex AI Workbench upgrades the OS. The image version depends on the specific image pulled by your Dockerfile.

    To help make sure the upgrade uses the most recent version of the image, consider using the latest tag in your Dockerfile.

If upgrading your instance is not an option for you, consider migrating your data to a new Vertex AI Workbench instance.

How the upgrade works

Vertex AI Workbench 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 or preserved?

The following table shows which components of your Vertex AI Workbench instance are upgraded and which are preserved.

Component Upgrade result
Machine learning frameworks Upgraded
Machine learning data Preserved
Preinstalled dependencies Upgraded
User-installed libraries By default, must be reinstalled (see User-installed libraries)
Local files in the /home/jupyter directory Preserved
Local files in any other /home/ directory Not preserved
Preinstalled operating system packages Upgraded
User-installed operating system packages Not preserved
GPU drivers Upgraded
Notebooks Preserved
User configurations Preserved

User-installed libraries

By default, Vertex AI Workbench instances store pip and Conda libraries in the boot disk, which is replaced during an upgrade. When you install pip libraries, you can include the --user flag to install them in the /home/jupyter/ directory, where they are preserved during an upgrade.

By default, if you install pip or Conda libraries in a kernel created from a custom container, the libraries only persist while the kernel is running. Each time the kernel is restarted, those libraries will need to be reinstalled. To install persistent libraries in a custom container, include the library installations in your Dockerfile. When installing pip libraries in a kernel created from a custom container, you can include the --user flag so that the libraries will persist until instance restart.

Environment versions

Your Vertex AI Workbench instance has an environment version number that you can verify:

  1. In the Google Cloud console, go to the Instances page.

    Go to Instances

  2. In the list of instances, find the version number of your instance's environment in the Version column.

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 Vertex AI Workbench instance, see Create a specific version of a Vertex AI Workbench instance.

Before you begin

Before you upgrade, complete the following steps.

  1. Check the release notes to learn about updates to newer versions.

  2. Make a copy of your data as a backup.

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 checkUpgradability. 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 an internal upgrade method to upgrade the instance.

Create a Vertex AI Workbench instance with auto upgrade enabled

To create a Vertex AI Workbench 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 the Google Cloud console.

  1. In the Google Cloud console, go to the Instances page.

    Go to Instances

  2. Click  Create new.

  3. In the New instance dialog, click Advanced options.

  4. In the Create instance dialog, in the Details section, provide the following information for your new instance:

    • Name: Provide a name for your new instance.
    • Region and Zone: Select a region and zone for the new instance. For best network performance, select the region that is geographically closest to you. See the available Vertex AI Workbench locations.

  5. In the System health section, select Environment auto-upgrade.

  6. Choose whether to upgrade your notebook Weekly or Monthly.

  7. In the Weekday field, select the option that you want.

  8. In the Hour field, choose an hour of the day.

  9. Complete the rest of the instance creation dialog, and then click Create.

Edit the auto upgrade schedule

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

  1. In the Google Cloud console, go to the Instances page.

    Go to Instances

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

  3. On the Instance details page, in the Environment auto-upgrade section, edit the schedule.

  4. Click Submit to save your changes.

Manual upgrade

You can manually upgrade Vertex AI Workbench 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 Google Cloud console.

  1. In the Google Cloud console, go to the Instances page.

    Go to Instances

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

  3. On the Instance details page, next to VM details, click View in Compute Engine.

    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 Vertex AI Workbench instance in the Google Cloud console.

  1. In the Google Cloud console, go to the Instances page.

    Go to Instances

  2. If your instance isn't running, start the instance. Vertex AI Workbench can only upgrade instances when they're running.

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

  4. On the Instance details page, click  Upgrade.

  5. Make sure you have made a copy of the data on your instance before continuing.

  6. After your data is backed up, click Upgrade. Vertex AI Workbench upgrades and starts your instance.

Roll back an upgrade

To roll back an upgrade, complete the following steps:

  1. In the Google Cloud console, go to the Instances page.

    Go to Instances

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

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

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