Migrate from user-managed notebooks to Vertex AI Workbench instances

Vertex AI Workbench user-managed notebooks isdeprecated. On April 14, 2025, support for user-managed notebooks will end and the ability to create user-managed notebooks instances will be removed. Existing instances will continue to function but patches, updates, and upgrades won't be available. To continue using Vertex AI Workbench, complete the steps on this page tomigrate your user-managed notebooks instances to Vertex AI Workbench instances.

This page describes how to migrate froma user-managed notebooks instance to a Vertex AI Workbench instance.You can migrate by using the Vertex AI Workbench migration tool ormigrate your instance's data and files manually.

Overview of the migration tool

Vertex AI Workbench provides a migration tool for migrating froma user-managed notebooks instance to a Vertex AI Workbench instance.

The migration tool creates a Vertex AI Workbench instance with aconfiguration similar to the user-managed notebooks instancethat you want to migrate. For example,the migration tool creates an instance that has the same or similarmachine type, network configuration, idle shutdown settings,and other specifications. Then, the files on youruser-managed notebooks instance's data disk are copied to theVertex AI Workbench instance.

Vertex AI Workbench doesn't delete or change youruser-managed notebooks instance, so after migration youcan continue to use it. If you don't need theuser-managed notebooks instanceanymore,delete it to avoid further charges for that instance.

Billing

If your user-managed notebooks instanceuses Extreme Persistent Disks,then your migration generates charges for I/O operations.See "Extreme provisioned IOPS" in thePersistent Disk and Hyperdisk pricing section ofDisk pricing.

After migration, the user-managed notebooks instance still existsand generates charges as before. If you don't needthe user-managed notebooks instanceanymore,delete it to avoid further charges for that instance.

Default migration tool behaviors

The Vertex AI Workbench migration tool attempts tomigrate your user-managed notebooks instance toa Vertex AI Workbench instance with matching specifications.When a specification in your user-managed notebooks instanceisn't available in Vertex AI Workbench instances, Vertex AI Workbenchuses a default specification when possible. When the migration toolcan't migrate a specification ofyour user-managed notebooks instance,it doesn't migrate the instance.

The following table lists some of the key default migration behaviorsfor the migration tool.

Specifying the post-startup script

User-managed notebooks instances that use a post-startup scriptmust be migrated to an instance with thePostStartupScriptOptionoption specified. Use this option to indicate whether you want toskip or rerun the post-startup script in your newVertex AI Workbench instance.

Specifying thePostStartupScriptOption option isn't supportedin the Google Cloud console. To specify thePostStartupScriptOption option when you migrateyour user-managed notebooks instance, you mustuse the Google Cloud CLI or REST API.

Before you begin

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Notebooks API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Notebooks API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

Enable the API

Required roles

To get the permissions that you need to migrate a user-managed notebooks instance to a Vertex AI Workbench instance, ask your administrator to grant you the Notebooks Runner (roles/notebooks.runner) IAM role on the project. For more information about granting roles, seeManage access to projects, folders, and organizations.

This predefined role contains the permissions required to migrate a user-managed notebooks instance to a Vertex AI Workbench instance. To see the exact permissions that are required, expand theRequired permissions section:

You might also be able to get these permissions withcustom roles or otherpredefined roles.

Pre-migration check

Before you migrate, check your user-managed notebooks instance'smigration eligibility by listing your instances and checkingthe output for any migration warnings or errors.

List your instances

To list your user-managed notebooks instances that aren'tmigrated yet, use theprojects.locations.instances.listmethod with the filtermigrated:false. You can list them by using thegcloud CLI or REST API:

gcloudnotebooksinstanceslist--project=PROJECT_ID\--location=LOCATION--filter=migrated:false--format=default

gcloudnotebooksinstanceslist--project=PROJECT_ID`--location=LOCATION--filter=migrated:false--format=default

gcloudnotebooksinstanceslist--project=PROJECT_ID^--location=LOCATION--filter=migrated:false--format=default

GET https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances?filter=migrated:false

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances?filter=migrated:false"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances?filter=migrated:false" | Select-Object -Expand Content

Check the output for warnings or errors

If migration warnings or errors are detected, the output oftheprojects.locations.instances.list method includes this information.

Warnings appear when specific components inyour user-managed notebooks instance's configuration won'tmigrate to the same specification in a Vertex AI Workbench instance.For example, if your user-managed notebooks instance uses anunsupported accelerator, a warning appears in the output. In this case,the instance is migrated without any accelerators. You can attachaccelerators after migration. Review the warnings inthe output, consider themigration tool's default behaviors,and assess whether the migration tool is acceptable for your migration.

One or more errors in the output means that you can't migratethe user-managed notebooks instance by using the migration tool.You mustmigrate the instance manually.

For more information about migration warnings and errors, seewarningsanderrorsin theInstanceMigrationEligibility documentation.

Migrate by using the migration tool

You can migrate your user-managed notebooks instance by usingthe Google Cloud console, the gcloud CLI, or REST API.

gcloudnotebooksinstancesmigrateRUNTIME_ID\--project=PROJECT_ID\--location=LOCATION\--post-startup-script-option=POST_STARTUP_SCRIPT_OPTION

gcloudnotebooksinstancesmigrateRUNTIME_ID`--project=PROJECT_ID`--location=LOCATION`--post-startup-script-option=POST_STARTUP_SCRIPT_OPTION

gcloudnotebooksinstancesmigrateRUNTIME_ID^--project=PROJECT_ID^--location=LOCATION^--post-startup-script-option=POST_STARTUP_SCRIPT_OPTION

POST https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID:migrate

{  "postStartupScriptOption": (POST_STARTUP_SCRIPT_OPTION)}

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID:migrate"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID:migrate" | Select-Object -Expand Content

Migrate manually

To migrate your instance to a Vertex AI Workbench instance manually,consider using the following methods:

• Use Cloud Storage and the terminal: Copy your data and filesto Cloud Storage and then to another instance by using the terminal.

• Use GitHub: Copy your data and files to a GitHub repositoryby using the Git extension for JupyterLab.

This guide describes how to migrate data and files by usingCloud Storage and the terminal.

Requirements

You must have terminal access to youruser-managed notebooks instance.Terminal access is manually set when you create an instance. Theterminal access setting cannot be changed after the instance is created.

Migrate manually by using Cloud Storage and the terminal

To migrate data and files to a new Vertex AI Workbench instanceby using Cloud Storage and the terminal, do the following.

1. Create a Cloud Storage bucketin the same project where your user-managed notebooks instanceis located.

2. In that same project,Createa Vertex AI Workbench instance to migrate your data to.When you create this instance:

   • Enable terminal access.
   • Specify the machine type, network,and other characteristics to match what you need.

3. In your user-managed notebooks instance'sJupyterLab interface, selectFile >New > Terminal to open a terminal window.

4. Use thegcloud CLI to copy your user datato a Cloud Storage bucket. The following example commandcopies all of the files from your instance's/home/jupyter/ directoryto a directory in a Cloud Storage bucket.

   gcloudstoragecp/home/jupyter/*gs://BUCKET_NAMEPATH--recursive

   Replace the following:

   • BUCKET_NAME: The name of yourCloud Storage bucket
   • PATH: The path to the directorywhere you want to copy your files, for example:/copy/jupyter/

5. In your new Vertex AI Workbench instance'sJupyterLab interface, selectFile >New > Terminal to open a terminal window.

6. Use the gcloud CLI to copy your data to the new instance.The following example command copies all ofthe files from a Cloud Storage directory to theyour new instance's/home/jupyter/ directory.

   gcloudstoragecpgs://BUCKET_NAMEPATH*/home/jupyter/--recursive

Confirm the migration

After the migration, the original user-managed notebooks instancecontinues to work as before. Confirm that your migration was a successbefore you delete the original instance.

Delete the user-managed notebooks instance

If you don't need the user-managed notebooks instance thatyou migrated from, delete it to avoid further charges for that instance.

1. In the Google Cloud console, go to theUser-managed notebooks page.

   Go to User-managed notebooks

2. Select the instance that you want to delete.

3. Clickdelete Delete.(Depending on the size of your window,theDelete button might be inthemore_vert options menu.)

4. To confirm, clickDelete.

Troubleshoot

To find methods for diagnosing and resolving migration issues, seeTroubleshootingVertex AI Workbench.

What's next

• Learn more aboutVertex AI Workbench instances.