Create a user-managed notebooks instance

Create a user-managed notebooks instance

Vertex AI Workbench user-managed notebooks is deprecated. On January 30, 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, we recommend that you migrate your user-managed notebooks instances to Vertex AI Workbench instances.

This page shows you how to create a user-managed notebooks instance by using the Google Cloud console or the Google Cloud CLI. While creating your instance, you can configure your instance's hardware, encryption type, network, and other details.

Before you begin

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

1. 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.

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

   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

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Notebooks API.

   Enable the API

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

   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

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the Notebooks API.

   Enable the API

8. 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. See Requesting an increase in quota on the Compute Engine Resource 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 ensure that your user account has the necessary permissions to create a Vertex AI Workbench user-managed notebooks instance, ask your administrator to grant your user account the following IAM roles on the project:

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

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

Your administrator might also be able to give your user account the required permissions through custom roles or other predefined roles.

Create a user-managed notebooks instance

You can create a user-managed notebooks instance by using the Google Cloud console, the Google Cloud CLI, or Terraform.

Console

To create a user-managed notebooks instance by using the Google Cloud console, do the following:

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

   Go to User-managed notebooks

2. Click  Create new.

   The New instance window opens.

3. In the New instance window, click Advanced options.

4. In the Details section, provide the following information for your new instance:

   • Name: Provide a name for your new instance. The name must start with a letter followed by up to 62 lowercase letters, numbers, or hyphens (-), and cannot end with a hyphen.
   • Region and Zone: Select a region and zone for the new instance. For best network performance, select the region that is geographically closest to you. See the available user-managed notebooks locations.
   • Labels: Optional. Provide custom key-value labels for the instance.
   • Tags: Optional. Provide tags for the instance.

5. In the Environment section, provide the following:

   • Operating system: Select the operating system that you want to use.
   • Environment: Select the environment that you want to use.
   • Version: Use the latest version or a previous version of user-managed notebooks instances.
   • Post-startup script: Optional. Click Browse to select a script to run one time, after the instance is created. The path must be a URL or Cloud Storage path, for example: gs://PATH_TO_FILE/FILE_NAME.
   • Metadata: Optional. Provide custom metadata keys for the instance.

6. In the Machine type section, provide the following:

   • Machine type: Select the number of CPUs and amount of RAM for your new instance. Vertex AI Workbench provides monthly cost estimates for each machine type that you select.

   • GPU: Optional. If you want GPUs, select the GPU type and Number of GPUs for your new instance. For information about the different GPUs, see GPUs on Compute Engine.

     Select Install NVIDIA GPU driver automatically for me.

     Note: You can modify the machine type and GPU configuration for your instance after it is created. For more information, see Change machine type and configure GPUs of a user-managed notebooks instance.

   • Shielded VM: Optional. Select or clear the following:

     • Secure Boot
     • Virtual Trusted Platform Module (vTPM)
     • Integrity monitoring

   • Idle shutdown: Optional.

     • To change the number of minutes before shutdown, in the Time of inactivity before shutdown (Minutes) field, change the value to an integer from 10 through 1440.

     • To turn off idle shutdown, clear Enable Idle Shutdown.

7. In the Disks section, provide the following:

   • Disks: Optional. To change the default boot or data disk settings, select a Boot disk type, Boot disk size in GB, Data disk type, and Data disk size in GB. For more information about disk types, see Storage options.

   • Delete to trash: Optional. Select this checkbox to use the operating system's default trash behavior, If you use the default trash behavior, files deleted by using the JupyterLab user interface are recoverable but these deleted files do use disk space.

   • Backup: Optional. To sync a Cloud Storage location with your instance's data disk, click Browse and specify the Cloud Storage location. To learn about storage costs, see Cloud Storage pricing.

   • Encryption: Select Google-managed encryption key or Customer-managed encryption key (CMEK). To use CMEK, see Customer-managed encryption keys.

8. In the Networking section, provide the following:

   • Networking: Adjust the network options to use a network in your current project or a Shared VPC network from a host project, if one is configured. If you are using a Shared VPC in the host project, you must also grant the Compute Network User role (roles/compute.networkUser) to the Notebooks Service Agent in the host project.

     Note: When you select Include Google-provided role grants in the IAM & Admin section, the Notebooks Service Agent is automatically created in the visible service project. The Notebooks Service Agent service account is [e-mail].

     1. In the Network field, select the network that you want. You can select a VPC network, as long as the network has Private Google Access enabled or can access the internet. For more information, see network configuration options.

     2. In the Subnetwork field, select the subnetwork that you want.

   • To turn off the external IP address, clear the Assign external IP address checkbox.

   • To turn off proxy access, clear the Allow proxy access checkbox.

     Note: If you turn off proxy access, you must use SSH to connect to your instance's JupyterLab interface.

9. In the IAM and security section, provide the following:

   • IAM and security: To grant access to the instance's JupyterLab interface, complete one of the following steps:

     • To grant access to JupyterLab through a service account, select Service account.

       • To use the default Compute Engine service account, select Use default Compute Engine service account.

       • To use a custom service account, clear Use default Compute Engine service account, and then, in the Service account email field, enter your custom service account email address.

     • To grant a single user access to the JupyterLab interface, do the following:

       1. Select Single user, and then, in the User email field, enter the user account that you want to grant access. If the specified user is not the creator of the instance, you must grant the specified user the Service Account User role (roles/iam.serviceAccountUser) on the instance's service account.

       2. Your instance uses a service account to interact with Google Cloud services and APIs.

          • To use the default Compute Engine service account, select Use default Compute Engine service account.

          • To use a custom service account, clear Use default Compute Engine service account, and then, in the Service account email field, enter your custom service account email address.

     Note: To grant access to the instance through the service account or single user option, you must use an individual's user account email address. Group access is not supported.

     To learn more about granting access, see Manage access.

     Note: After you create an instance with service account access, the service account can't be changed. To use a different service account, you must create a new instance specifying the service account that you want. Attempting to change the service account by using the Compute Engine API can cause loss of functionality.

   • Security options: Select or clear the following checkboxes:

     • Root access to the instance
     • nbconvert
     • File downloading
     • Terminal access
     Note: User-managed notebooks instances that use the Dataproc Hub framework permit file downloading even if you don't select File downloading.

10. In the System health section, provide the following:

    • Environment upgrade and system health: To automatically upgrade to newly released environment versions, select Environment auto-upgrade and complete the Upgrade schedule.

    • In Reporting, select or clear the following checkboxes:

      • Report system health
      • Report custom metrics to Cloud Monitoring
      • Install Cloud Monitoring
      • Report DNS status for required Google domains

11. Click Create.

    Vertex AI Workbench creates and automatically starts your user-managed notebooks instance. When the instance is ready to use, Vertex AI Workbench activates an Open JupyterLab link.

gcloud

By default, the Google Cloud CLI creates a user-managed notebooks instance with an external IP address. To create an instance without an external IP address, you must specify a subnet that has Private Google Access enabled. For more information, see networking configuration options.

1. To create a user-managed notebooks instance from the command line, from Cloud Shell or any terminal where the Google Cloud CLI is installed, use the gcloud notebooks instances create command:

   gcloud notebooks instances create INSTANCE_NAME \
     --vm-image-project=deeplearning-platform-release \
     --vm-image-family=VM_IMAGE_FAMILY \
     --machine-type=MACHINE_TYPE \
     --location=LOCATION
   

   Replace the following:

   • INSTANCE_NAME: the name of your new instance; must start with a letter followed by up to 62 lowercase letters, numbers, or hyphens (-), and cannot end with a hyphen.
   • VM_IMAGE_FAMILY: the image family name that you want to use to create your instance
   • MACHINE_TYPE: the machine type of your instance's VM
   • LOCATION: the Google Cloud location where you want your new instance to be

2. Access your instance from the Google Cloud console.

For information about all commands for creating an instance from the command line, see the gcloud CLI documentation.

Terraform

The following sample uses the google_notebooks_instance Terraform resource to create a new user-managed notebooks instance named notebooks-instance-basic.

To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.

resource "google_notebooks_instance" "basic_instance" {
  name         = "notebooks-instance-basic"
  location     = "us-central1-a"
  machine_type = "e2-medium"

  vm_image {
    project      = "deeplearning-platform-release"
    image_family = "tf-ent-2-9-cu113-notebooks"
  }
}

Open the notebook

To open a user-managed notebooks instance, complete the following steps:

1. In the Google Cloud console, next to your user-managed notebooks instance's name, click Open JupyterLab.

2. Your user-managed notebooks instance opens JupyterLab.

Network configuration options

A user-managed notebooks instance must access service endpoints that are outside your VPC network.

You can provide this access in one of the following ways:

• Assign an external IP address to the user-managed notebooks instance. This is done automatically when you create a new instance with default properties. Make sure your environment meets the requirements for accessing Google APIs and services.

• Connect the user-managed notebooks instance to a subnet where Private Google Access is enabled. Make sure your environment meets the requirements for Private Google Access.

If you use the private.googleapis.com or restricted.googleapis.com VIP to provide access to the service endpoints, add DNS entries for each of the required service endpoints:

• notebooks.googleapis.com
• *.notebooks.cloud.google.com
• *.notebooks.googleusercontent.com
• *.kernels.googleusercontent.com

Network tags

Your new user-managed notebooks instance automatically has the deeplearning-vm and notebook-instance network tags assigned.

These tags let you manage network access to and from your user-managed notebooks instance by referencing the tags in your VPC networking firewall rules. For more information about network tags, see Add network tags.

To view the network tags for a user-managed notebooks instance, do the following:

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

   Go to VM instances

2. Click the name of the instance.

3. In the Networking section, find Network tags.

Troubleshooting

If you encounter a problem when you create a notebook, see Troubleshooting Vertex AI Workbench for help with common issues.

What's next

• Install dependencies on your new user-managed notebooks instance.

• Learn about monitoring the health status of your user-managed notebooks instance.