Register a legacy instance with Notebooks API

Vertex AI Workbench user-managed notebooks isdeprecated. On April 14, 2025, support for user-managed notebooks ended and the ability to create user-managed notebooks instances was removed. Existing instances will continue to function until March 30, 2026, but patches, updates, and upgrades won't be available. To continue using Vertex AI Workbench, we recommend that youmigrate your user-managed notebooks instances to Vertex AI Workbench instances.

This page shows how to migrate and register a legacyuser-managed notebooks instance with the Notebooks API. Instancescreated by using the Compute Engine API are called legacy instances. Legacyinstances don't have the latest updates to functionality and features.

To use the new functionality and features that are available with theNotebooks API, you mustregister your legacy instances withthe Notebooks API. Before registering your legacy instances, check whetherthey meet therequirements. You canmigrate instances that don't meet the requirements.

If you enable the Notebooks API before registering your legacy instances, theNotebooks API activation process attempts to register your existing legacyinstances automatically.

Requirements and limitations

Before registering your legacy instances with the Notebooks API, considerthe following requirements and limitations.

• Source and destination zones must match and be a valid zonefor the Notebooks API.

  For example, a legacy user-managed notebooks instanceinus-west1-a remains inus-west1-a when it is registered withthe Notebooks API. However, a legacy user-managed notebooksinstance inus-central1-f won't register with the Notebooks API becauseus-central1-f isn't a valid zone for the Notebooks API.

  To get a list of the valid zones for the Notebooks API notebooks instances,run the following command by using theGoogle Cloud CLI inyour preferred terminal or inCloud Shell:

  gcloudnotebookslocationslist

  If your legacy instance's zone is not a valid zone for the Notebooks API,you can contactsupportor your account manager, or you canmigrate the legacy instance to anew user-managed notebooksinstance.

• Only dual-disk instances can use all user-managed notebooksfeatures.

  Single-disk legacy instances cannot use someuser-managed notebooks features, such as auto upgrade, evenafter they are registered with the Notebooks API. To enable yoursingle-disk legacy instance to use all available features, you mustmigrate your single-disk instance to a dual-diskinstance.

  You can migrate your single-disk instance to a dual-disk instance as partof your migration from a legacy instance to an instance registered with theNotebooks API. If you've already registered the legacy instance with theNotebooks API, you can still migrate the instance to anew dual-diskinstance to resolve the issue.

  To verify the number of disks, complete the following steps.

  Console

  1. In the Google Cloud console, go to theVM instances page.

     Go to VM instances

  2. Find your current legacy user-managed notebooksinstance.

  3. Click the instance name to open theVM instance details page.

  4. In theboot disk andadditional disks sections, verifyhow many disks are attached to the VM.

  gcloud

  1. InCloud Shellor any environment where theGoogle Cloud CLIis installed, enter the followingGoogle Cloud CLI command:

     gcloudcomputeinstancesdescribeMY_INSTANCE_NAME\--zone=MY_ZONE

     Replace the following:

     • MY_INSTANCE_NAME: the name of your instance
     • MY_ZONE: the zone of your instance

  2. Review the information that followsdisks:, and verifyhow many disks are attached to the VM.

Migrate a legacy instance to a new user-managed notebooks instance

If your legacy user-managed notebooks instance is in a zone thatisn't a valid zone for the Notebooks API, or if you want to migrate from asingle-disk instance to a dual-disk instance, you must create a user-managed notebooks instance and copy your user data from yourlegacy instance to the new instance.

To create a user-managed notebooks instance and copy your userdata from your legacy instance to the new instance, complete the followingsteps:

1. To usessh to connect to your legacy instance, inCloud Shellor any environment where theGoogle Cloud CLIis installed, enter the followingGoogle Cloud CLI command:

   exportPROJECT_ID="MY_PROJECT_ID"exportZONE="MY_ZONE"exportINSTANCE_NAME="MY_INSTANCE"gcloudcomputessh\--project$PROJECT_ID\--zone$ZONE$INSTANCE_NAME\---L8080:localhost:8080

   Replace the following:

   • MY_PROJECT_ID: the ID of your Google Cloud project
   • MY_ZONE: the zone of your instance
   • MY_INSTANCE: the name of your instancewith the relevant information.

2. To copy the contents of the legacy instance to aCloud Storagebucket, usegcloud storage. The following example command copies all ofthe notebook (.ipynb) files from the default directory/home/jupyter/ to a Cloud Storage directory namedmy-bucket/legacy-notebooks.

   gcloudstoragecp/home/jupyter/*.ipynbgs://my-bucket/legacy-notebooks/--recursive

3. Create a user-managed notebooks instancewith the same hardwarespecifications as the legacy instance.

   In this example, Vertex AI Workbench createsa user-managed notebooks instance namednew-notebookin theexample projectusing the latest TensorFlow 2 image, with ann1-standard-1 machine type, in theus-west1-a zone.

   In eitherCloud Shellor any environment where theGoogle Cloud CLIis installed, enter the followingGoogle Cloud CLI command:

   gcloudnotebooksinstancescreatenew-notebook\--vm-image-project=example\--vm-image-family=tf-latest-cpu\--machine-type=n1-standard-1\--location=us-west1-a

   The new user-managed notebooks instance is dual-disk.It has a boot disk and a data disk.

4. Usessh to connect to the user-managed notebooks instancethat you just created.

5. To copy the contents of the legacy instance from theCloud Storage bucket to the new instance, usegcloud storage.The following example command copies all ofthe notebook (.ipynb) files from the Cloud Storage directoryto the new instance's/home/jupyter/ directory.

   gcloudstoragecpgs://my-bucket/legacy-notebooks/*.ipynb/home/jupyter/--recursive

6. In the new user-managed notebooks instance,open JupyterLab and confirmthat the user data and assets have been successfully copied.

7. Optional: delete the legacy instance.

Register a legacy instance with the Notebooks API

To use the Notebooks API to manage your legacy instances, you must registeryour legacy instances with the Notebooks API.

If you enable the Notebooks API before registering your legacy instances,the Notebooks API activation process attempts to register your existing legacyinstances automatically. If you create legacy instances after the Notebooks APIis enabled, you must register them manually by using one of the followingmethods.

To register your legacy instance with the Notebooks API, you canuse the Google Cloud console or the Notebooks API.

gcloudnotebooksinstancesregisterMY_INSTANCE_NAME\--location=MY_ZONE

What's next

• Create a user-managed notebooks instance by using a custom container