Register a legacy instance with Notebooks API

This page describes the two different ways to create a user-managed notebooks instance, and how to register a legacy user-managed notebooks instance with the Notebooks API. If you created user-managed notebooks instances before the Notebooks API was Generally Available, or continued to create notebooks using the Compute Engine API after general availability, you must register those instances with the Notebooks API so you can use the new functionality and features that were added with the Notebooks API.

Two ways to create a user-managed notebooks instance

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

  • Use the Notebooks API. This method gives you the most up-to-date features and functionality.

  • Use the Compute Engine API. User-managed notebooks instances created using this method are called legacy instances. They do not have the latest updates to features and functionality.

Register a legacy instance with the Notebooks API

You must register legacy instances to be able to manage them using the Notebooks API.

To register your legacy instance with the Notebooks API, you can use the Register all option in the Google Cloud Console, or use the register method provided by the Notebooks API.

Using the console

To use the Register all option in the Cloud Console, complete the following steps.

  1. Before you attempt to migrate your instance, review the requirements and limitations.

  2. Go to the User-managed notebooks page in the Cloud Console.

    Go to the User-managed notebooks page

  3. If you have one or more legacy user-managed notebooks instances, a message appears indicating that you need to register them with the Notebooks API. Next to this message, click Register all.

  4. If you do not have any legacy user-managed notebooks instances, but have not yet enabled the Notebooks API, click Enable Notebooks API to ensure that new user-managed notebooks instances will be created using the Notebooks API.

Using the API

To use the register method provided by the Notebooks API, complete the following steps.

  1. Before you attempt to migrate your instance, review the requirements and limitations.

  2. Type the following command in either Cloud Shell or any environment where the Cloud SDK is installed. Replace MY_INSTANCE_NAME and MY_ZONE with the relevant information.

    gcloud notebooks instances register MY_INSTANCE_NAME --location=MY_ZONE
    

Requirements and limitations

Consider the following requirements and limitations before registering your legacy instances with the Notebooks API.

  • The 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 will fail to register with the Notebooks API because us-central1-f is not a supported zone for the Notebooks API.

    To get a list of the valid zones for the Notebooks API notebooks instances, type the following command in either Cloud Shell or any environment where the Cloud SDK is installed.

    gcloud notebooks locations list
    

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

  • 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 instance to use all available features, you must migrate your single-disk instance to a dual-disk instance. You can do this as part of your migration from 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.

    Using the console

    1. Go to the Compute Engine page in the Cloud Console.

      Go to the Compute Engine VM instances page

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

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

    4. In the boot disk and additional disks sections, verify how many disks are attached to the VM.

    Using the CLI

    1. Type the following command in either Cloud Shell or any environment where the Cloud SDK is installed.

      Replace MY_INSTANCE_NAME and MY_ZONE with the relevant information.

      gcloud compute instances describe MY_INSTANCE_NAME --zone=MY_ZONE
      
    2. Review the information that follows disks:, and verify how many disks are attached to the VM.

Migrating an instance to a new user-managed notebooks instance

If your legacy user-managed notebooks instance is not able to be migrated because it's located in a zone that the Notebooks API doesn't support, or if you want to migrate from a single-disk instance to a dual-disk instance, you must create a new user-managed notebooks instance and copy your legacy instance's user data to the new instance. To do so, complete the following steps:

  1. Use ssh to connect to your legacy instance by typing the following command in either Cloud Shell or any environment where the Cloud SDK is installed. Replace MY_PROJECT_ID, MY_ZONE, and MY_INSTANCE with the relevant information.

    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
    
  2. Copy the contents of the legacy instance to a Cloud Storage bucket using gsutil. 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.

    gsutil cp -R /home/jupyter/*.ipynb gs://my-bucket/legacy-notebooks/
    
  3. Create a new user-managed notebooks instance with the same hardware specifications as the legacy instance. You can create the instance using the Cloud Console or use the following example command in either Cloud Shell or any environment where the Cloud SDK is installed. In this example, Vertex AI Workbench creates a new 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.

    gcloud notebooks instances create new-notebook \
    --vm-image-project=example \
    --vm-image-family=tf2-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. Copy the contents of the legacy instance from the Cloud Storage bucket to the new instance using gsutil. The following example command copies all of the notebook (.ipynb) files from the Cloud Storage directory to the new instance's /home/jupyter/ directory.

    gsutil cp -R gs://my-bucket/legacy-notebooks/*.ipynb  /home/jupyter/
    
  6. In the new user-managed notebooks instance, open JupyterLab and confirm that the user data and assets have been successfully copied.

  7. Optionally, delete the legacy instance.

What's next

Go to the User-managed notebooks page in the Cloud Console to register legacy instances and enable the Notebooks API.

Go to the User-managed notebooks page