Register a legacy instance with Notebooks API

Vertex AI Workbench user-managed notebooks is deprecated . 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 you migrate your user-managed notebooks instances to Vertex AI Workbench instances .

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

To use the new functionality and features that are available with the Notebooks API, you must register your legacy instances with the Notebooks API. Before registering your legacy instances, check whether they meet the requirements . You can migrate instances that don't meet the requirements.

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

Requirements and limitations

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

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

  For example, a legacy user-managed notebooks instance in us-west1-a remains in us-west1-a when it is registered with the Notebooks API. However, a legacy user-managed notebooks instance in us-central1-f won't register with the Notebooks API because us-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 the Google Cloud CLI in your preferred terminal or in Cloud Shell :

  gcloud  
  notebooks  
  locations  
  list

  If your legacy instance's zone is not a valid zone for the Notebooks API, you can contact support or your account manager, or you can migrate the legacy instance to a new user-managed notebooks instance .

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

  Single-disk legacy instances cannot use some user-managed notebooks features, such as auto upgrade, even after they are registered with the Notebooks API. To enable your single-disk legacy instance to use all available features, you must migrate your single-disk instance to a dual-disk instance .

  You can migrate your single-disk instance to a dual-disk instance as part of your migration from a legacy instance to an instance registered with the Notebooks API. If you've already registered the legacy instance with the Notebooks API, you can still migrate the instance to a new dual-disk instance to resolve the issue.

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

  Console

  1. In the Google Cloud console, go to the VM instancespage.

     Go to VM instances

  2. Find your current legacy user-managed notebooks instance.

  3. Click the instance name to open the VM instance detailspage.

  4. In the boot diskand additional diskssections, verify how many disks are attached to the VM.

  gcloud

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

     gcloud  
     compute  
     instances  
     describe  
      MY_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 follows disks:, and verify how 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 that isn't a valid zone for the Notebooks API, or if you want to migrate from a single-disk instance to a dual-disk instance, you must create a user-managed notebooks instance and copy your user data from your legacy instance to the new instance.

To create a user-managed notebooks instance and copy your user data from your legacy instance to the new instance, complete the following steps:

1. To use ssh to connect to your legacy instance, in Cloud Shell or any environment where the Google Cloud CLI is installed, enter the following Google Cloud CLI command:

    export 
     
    PROJECT_ID 
    = 
    " MY_PROJECT_ID 
   " 
    export 
     
    ZONE 
    = 
    " MY_ZONE 
   " 
    export 
     
    INSTANCE_NAME 
    = 
    " MY_INSTANCE 
   " 
    gcloud 
     
    compute 
     
    ssh 
     
   \  
    -- 
    project 
     
    $ 
    PROJECT_ID 
     
   \  
    -- 
    zone 
     
    $ 
    ZONE 
     
    $ 
    INSTANCE_NAME 
     
   \  
    -- 
     
    - 
    L 
     
    8080 
    : 
    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 instance with the relevant information.

2. To copy the contents of the legacy instance to a Cloud Storage bucket, use gcloud storage . The following example command copies all of the notebook ( .ipynb ) files from the default directory /home/jupyter/ to a Cloud Storage directory named my-bucket/legacy-notebooks .

   gcloud  
   storage  
   cp  
   /home/jupyter/*.ipynb  
   gs://my-bucket/legacy-notebooks/  
   --recursive

3. Create a user-managed notebooks instance with the same hardware specifications as the legacy instance.

   In this example, Vertex AI Workbench creates a user-managed notebooks instance named new-notebook in the example project using the latest TensorFlow 2 image, with an n1-standard-1 machine type, in the us-west1-a zone.

   In either Cloud Shell or any environment where the Google Cloud CLI is installed, enter the following Google Cloud CLI command:

   gcloud  
   notebooks  
   instances  
   create  
   new-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. Use ssh to connect to the user-managed notebooks instance that you just created.

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

   gcloud  
   storage  
   cp  
   gs://my-bucket/legacy-notebooks/*.ipynb  
   /home/jupyter/  
   --recursive

6. In the new user-managed notebooks instance, open JupyterLab and confirm that 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 register your 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 legacy instances automatically. If you create legacy instances after the Notebooks API is enabled, you must register them manually by using one of the following methods.

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

gcloud  
notebooks  
instances  
register  
 MY_INSTANCE_NAME 
  
 \ 
  
--location = 
 MY_ZONE 

What's next

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