Upgrade an AI Platform Notebooks instance's environment

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

Upgrade methods

There are two ways to upgrade an AI Platform Notebooks instance:

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

  2. Manual upgrade: If an existing AI Platform 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 AI Platform Notebooks instance:

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

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

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

  • If the AI Platform Notebooks instance is container-based, AI Platform 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

AI Platform 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 AI Platform 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 AI Platform Notebooks instance's environment has a version number that you can verify on the AI Platform Notebooks page, in the Environment Version column.

The available environments are updated with new versions regularly (see the AI Platform Deep Learning VM Image release notes), but with each released version, not all of the environments are updated. AI Platform 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 an AI Platform Notebooks instance, you specify a recurring time period in which AI Platform 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, AI Platform 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, AI Platform 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 AI Platform 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 AI Platform Notebooks instance using the Google Cloud Console.

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

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

    Go to the AI Platform Notebooks page

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

    Create new AI Platform Notebooks instance with options

  4. On the Create a notebook instance page, expand the Environment upgrade 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 AI Platform 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 AI Platform 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 AI Platform 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 AI Platform Notebooks console.

Edit the auto upgrade schedule

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

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

    Go to the AI Platform 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 AI Platform Notebooks instances that meet the requirements.

To check whether a newer version of your instance's environment is available, go to the AI Platform 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 an AI Platform 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 an AI Platform Notebooks instance using the Google Cloud Console.

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

    Go to the AI Platform 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. AI Platform Notebooks upgrades and starts your instance.

Use the gcloud command-line tool

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

    AI Platform Notebooks upgrades the instance.

Rollback an upgrade

Complete the following steps to rollback an upgrade.

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

    Go to the AI Platform 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. AI Platform Notebooks rolls your instance back to the previous version.