Create a user-managed notebooks instance with a custom container

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.

You can create a user-managed notebooks instance based on a customcontainer. Using a custom container lets you customize auser-managed notebooks environment for your specific needs.The container must be accessible to yourGoogle Cloud service account and expose a service on port 8080.We recommend creating a container derived from aDeep Learning Containersimage,because those images are already configured to be compatiblewith user-managed notebooks.

How custom container kernels are updated

Vertex AI Workbench pulls the latest container image for your kernel:

• When you create your instance.

• When you upgrade your instance.

• When you start your instance.

The custom container kernel doesn't persist when your instance is stopped,so each time your instance is started, Vertex AI Workbench pullsthe latest version of the container image.

If your instance is running when a new version of a container is released,your instance's kernel isn't updated until you stop and start your instance.

Before you begin

Before you can create a user-managed notebooks instance,you must have aGoogle Cloud project and enable the Notebooks APIfor that project.

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

1. If you plan to use GPUs with your user-managed notebooks instance,check the quotas page in the Google Cloud console to ensure that you have enough GPUs available in your project. If GPUs are not listed on the quotas page, or you require additional GPU quota, you can request a quota increase. SeeRequesting an increase in quota on the Compute EngineResource quotas page.

Required roles

If you created the project, you have the Owner (roles/owner) IAM role on the project, which includes all required permissions. Skip this section and start creating your user-managed notebooks instance. If you didn't create the project yourself, continue in this section.

To get the permissions that you need to create a Vertex AI Workbench user-managed notebooks instance, ask your administrator to grant you the following IAM roles on the project:

• Notebooks Admin (roles/notebooks.admin)
• Service Account User (roles/iam.serviceAccountUser)

For more information about granting roles, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

Make sure your custom container is ready

Make sure you have a custom container that is accessible to yourGoogle Cloud service account. For information about how to create acustom container from aDeep Learning Containers image, seeCreating a derivative container.

Create an instance with a custom container

To create a user-managed notebooks instancewith a custom container, complete the following steps:

1. In the Google Cloud console, go to theUser-managed notebooks page.Or go tonotebook.new (https://notebook.new) and skip the next step.

   Go to User-managed notebooks

2. Clickadd_box Create new.

3. ClickAdvanced options.

4. On theCreate instance page,in theDetails section,provide the following information for your new instance:

   • Name: a name for your new instance
   • Region andZone: Select a region and zone forthe new instance. For best network performance,select the region that is geographically closest to you.See the availableuser-managed notebookslocations.

5. In theEnvironment section, in theEnvironment field,selectCustom container.

6. In theDocker container image field, add a Docker container imagein one of the following ways:

   • Enter a Docker container image path. For example,to use a TensorFlow 2.12 container image with accelerators fromDeep Learning Containers,enterus-docker.pkg.dev/deeplearning-platform-release/gcr.io/tf-cpu.2-12.py310.
   • ClickSelect to add a Docker container image fromArtifact Registry. Then on theArtifact Registry tabwhere your container image is stored, change the projectto the project that includes your container image, and selectyour container image.

7. Make the rest of your selections, or leave them on their defaultsetting.

8. ClickCreate. Vertex AI Workbench createsa user-managed notebooks instance for you, basedon your custom container.

What's next

• Read about how topush container images toArtifact Registry.If the container images you push to Artifact Registry are derived fromaDeep Learning Containersimage,you can use these container images when creatinguser-managed notebooks instances.
• Learn more about modifying your custom containers by readingBest practices for writingDockerfiles.