Create a managed notebooks instance

Create a managed notebooks instance

Vertex AI Workbench managed notebooks is deprecated. On January 30, 2025, support for managed notebooks will end and the ability to create 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 managed notebooks instances to Vertex AI Workbench instances.

This page shows you how to create a 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

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

Create an instance with default properties

You can create a managed notebooks instance by using either the Google Cloud console or the gcloud CLI:

Console

1. In the Google Cloud console, go to the Managed notebooks page.

   Go to Managed notebooks

2. Click  New notebook.

3. In the Notebook name field, enter a name for your instance. The name must start with a letter followed by up to 62 lowercase letters, numbers, or hyphens (-), and cannot end with a hyphen.

4. Click the Region list, and select a region for your instance.

5. Choose a permission option to define which users can access the managed notebooks instance:

   • Service Account: This option grants access to all users who have access to the Compute Engine service account that you link to the runtime. To specify your own service account, clear the Use Compute Engine default service account checkbox, and enter the service account email address that you want to use. For more information about service accounts, see Types of service accounts.

   • Single User: This option grants access to only a specific user. In the User email field, enter the user account email address of the user who will use the managed notebooks instance.

   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.

6. Click Create.

   Vertex AI Workbench automatically starts the instance. When the instance is ready to use, Vertex AI Workbench activates an Open JupyterLab link.

gcloud

Before using any of the command data below, make the following replacements:

• INSTANCE_NAME: The name of your managed notebooks instance; must start with a letter followed by up to 62 lowercase letters, numbers, or hyphens (-), and cannot end with a hyphen
• PROJECT_ID: Your project ID
• LOCATION: The region where you want your instance to be located
• ACCESS_MODE: the access mode that you want to use; for example, SINGLE_USER or SERVICE_ACCOUNT
• OWNER_EMAIL_ADDRESS: the email address of the single user or service account that needs access to the instance's JupyterLab interface
• MACHINE_TYPE: the machine type of your instance's VM

Execute the following command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud notebooks runtimes create INSTANCE_NAME --project=PROJECT_ID --location=LOCATION --runtime-access-type=ACCESS_MODE --runtime-owner=OWNER_EMAIL_ADDRESS --machine-type=MACHINE_TYPE

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud notebooks runtimes create INSTANCE_NAME --project=PROJECT_ID --location=LOCATION --runtime-access-type=ACCESS_MODE --runtime-owner=OWNER_EMAIL_ADDRESS --machine-type=MACHINE_TYPE

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud notebooks runtimes create INSTANCE_NAME --project=PROJECT_ID --location=LOCATION --runtime-access-type=ACCESS_MODE --runtime-owner=OWNER_EMAIL_ADDRESS --machine-type=MACHINE_TYPE

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

Vertex AI Workbench automatically starts the instance after creation. When the instance is ready to use, you can access it from the Google Cloud console.

Create an instance by using advanced settings

1. In the Google Cloud console, go to the Managed notebooks page.

   Go to Managed notebooks

2. Click  New notebook.

3. In the Notebook name field, enter a name for your instance. The name must start with a letter followed by up to 62 lowercase letters, numbers, or hyphens (-), and cannot end with a hyphen.

4. Click the Region list, and select a region for your instance.

5. Choose a permission option to define which users can access the managed notebooks instance:

   • Service Account: This option grants access to all users who have access to the Compute Engine service account that you link to the runtime. To specify your own service account, clear the Use Compute Engine default service account checkbox, and enter the service account email address that you want to use. For more information about service accounts, see Types of service accounts.

   • Single User: This option grants access to only a specific user. In the User email field, enter the user account email address of the user who will use the managed notebooks instance.

   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.

6. Click Advanced settings and complete the dialog using the directions in the following sections.

Use custom Docker images

To run notebook files in a custom Docker container, add the custom Docker container image to your managed notebooks instance.

The custom Docker container image must be located in Artifact Registry. You must have access to the container image.

1. In the Environment section, in Custom Docker images, select the Provide custom Docker images checkbox.

2. Enter a Docker container image path, or click Select to add one from Artifact Registry.

3. To add another custom Docker image, click  Add another Docker image, and repeat these steps.

Configure hardware

Select a hardware configuration for your environment. You can change this later from the JupyterLab user interface.

Confirm GPU availability

GPU accelerator availability is based on region, machine type, and the number of GPUs that you want. You might want to confirm availability by using the following resources:

• GPU regions and zones availability. The accelerator type that you want must be available in your instance's zone.
• NVIDIA® A100 GPUs. Check GPU availability for your machine type.

Configure the hardware

To configure your hardware, complete the following:

1. In the Hardware configuration section, select a Machine type.

2. If you want to use GPUs, select a GPU type. If you don't see the GPU type that you want, check GPU availability for your machine type and zone.

3. If you chose to use GPUs, select a Number of GPUs, and then select Install NVIDIA GPU driver automatically for me.

4. Select a Data disk type and Data disk size in GB.

5. To use the operating system's default trash behavior, select the Delete to trash checkbox. 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.

Select encryption type

Choose either the default Google-managed encryption key or a Customer-managed encryption key (CMEK). To learn more about using CMEK with managed notebooks, see Use customer-managed encryption keys.

1. In the Disk encryption section, select either the default Google-managed encryption key or select Customer-managed encryption key (CMEK).

2. If you select Customer-managed encryption key (CMEK), click the list, and select your customer-managed key.

   • If the key that you want to use is not in the list, enter your encryption key's resource ID.

   • To create a customer-managed encryption key, see Creating symmetric encryption keys.

Enable idle shutdown

Idle shutdown is enabled by default to shut down your instance after 180 minutes of inactivity. You can change the number of minutes of inactivity before shutdown, or you can disable idle shutdown. To learn more, see Idle shutdown.

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

• To disable idle shutdown, in the Idle shutdown section, clear Enable Idle Shutdown.

Configure your network

By default, your managed notebooks instance uses a Google-managed VPC network, which requires no configuration. If you want to, you can instead specify a VPC network located within your project or a network that is shared with you. If you specify a network, the network requires a private services access connection. The network must also have internet access, or you must enable Private Google Access for the network.

1. In the Networking section, select either Networks in this project or Networks shared with me.

2. In the Network field, select the network that you want to use.

3. In the Subnetwork field, select the subnetwork that you want to use.

4. To enable an external IP address, select the Enable external IP address checkbox. If the specified network doesn't have internet access, or if you don't enable the external IP address, you must enable Private Google Access for the network in order to use this instance.

5. If you have not already configured a private services access connection for this network, click Set up connection and complete the following:

   1. In the Create a private services access connection dialog, enable the Service Networking API, and then click Enable API. If the Service Networking API is already enabled, click Continue.

   2. In the Allocate an IP range section, complete the dialog to select one or more existing IP ranges, create a new IP range, or use an automatically allocated IP range.

   3. When you have finished, click Continue.

   4. In the Create a connection section, review the network and allocated IP range that you selected, and then click Create connection.

Configure security options

Enable or disable the following options:

• nbconvert: nbconvert lets users export and download a notebook file as a different file type, such as HTML, PDF, or LaTeX.
• File downloading from Notebook UI: This setting lets users download files from the JupyterLab user interface.
• Terminal: This enables terminal access to your managed notebooks instance from within the JupyterLab user interface.

Finish creating the instance

1. Click Create.

   Vertex AI Workbench automatically starts the instance. When the instance is ready to use, Vertex AI Workbench activates an Open JupyterLab link.

Create an instance by using Terraform

You can create a managed notebooks instance by using the google_notebooks_runtime Terraform resource. Use the following sample to create a new managed notebooks instance named notebooks-runtime-basic.

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

resource "google_notebooks_runtime" "basic_runtime" {
  name     = "notebooks-runtime-basic"
  location = "us-central1"

  access_config {
    access_type   = "SINGLE_USER"
    runtime_owner = "[e-mail]"
  }

  virtual_machine {
    virtual_machine_config {
      machine_type = "n1-standard-4"
      data_disk {
        initialize_params {
          disk_size_gb = "100"
          disk_type    = "PD_STANDARD"
        }
      }
    }
  }
}

Open JupyterLab

After you create your instance, Vertex AI Workbench automatically starts the instance. When the instance is ready to use, Vertex AI Workbench activates an Open JupyterLab link.

1. Next to your managed notebooks instance's name, click Open JupyterLab.

2. The first time you access a managed notebooks instance's JupyterLab user interface, you must grant the gcloud CLI permission to access your data and authenticate your managed notebooks instance.

   1. In the Authenticate your managed notebook dialog, click the button to get an authentication code.

   2. Choose an account and click Allow. Copy the authentication code.

   3. In the Authenticate your managed notebook dialog, paste the authentication code, and then click Authenticate.

Your managed notebooks instance opens JupyterLab.

Open a new notebook file

1. Select File > New > Notebook.

2. In the Select kernel dialog, select Python, and then click Select.

3. Your new notebook file opens.

What's next

• Try one of the tutorials that is included in your new managed notebooks instance. In the JupyterLab  File Browser, open the tutorials folder, and open one of the notebook files.