Create a notebook

Vertex AI Workbench is a single development environment used for the entire data science workflow. To set up an end-to-end notebook-based production environment, create JupyterLab instance notebook instances that come with built-in integrations. For more information, see https://jupyter.org/.

After you create a JupyterLab instance in Vertex AI Workbench, open the Notebook IDE in its JupyterLab environment.

This document describes the process to create a JupyterLab instance notebook in Vertex AI Workbench. For information about backing up and restoring data, see Back up and restore Vertex AI Workbench notebook data.

Create a JupyterLab instance

This section shows you how to create a JupyterLab instance in Vertex AI Workbench. All JupyterLab instances have JupyterLab 3 preinstalled. After you create a JupyterLab instance, use the GDC console to open JupyterLab in Vertex AI Workbench. For more information, see Open a JupyterLab notebook.

Before you create a JupyterLab instance, you must select a project. After you select a project, do the following to create a JupyterLab instance:

Confirm the account you used to sign in to Google Distributed Cloud (GDC) air-gapped is bound to the Workbench Notebooks Admin role. For more information, see Set up project-wide role bindings using the GDC console.
If you aren't signed in to the GDC console, sign in using the steps in Sign in to the GDC console.
In the navigation pane, expand Vertex AI, and click Workbench.
Click Create Notebook.
For Notebook name, type a name for your JupyterLab instance. Vertex AI uses the name you choose to create a URL for accessing your notebook.
From Environment, select a Docker image for your JupyterLab instance.
From Cluster, select a cluster for your JupyterLab instance. If a cluster isn't available, work with your Platform Administrator (PA) to add one or more clusters.
In CPUs / Memory, choose how many CPUs and how many GBs of RAM you want. For CPU-intensive workloads, you can choose more than one CPU.
From GPUs, select how many GPUs you want. In Vertex AI Workbench, a GPU is one NVIDIA Multi-Instance GPU (MIG) slice of an A100 Tensor Core GPU. For more information about MIGs, refer to https://www.nvidia.com/en-us/technologies/multi-instance-gpu in Nvidia's documentation.
In Workspace volume, choose the size of your volume in GBs.
Click Create.

Open a JupyterLab notebook

If you know the URL for your JupyterLab notebook, open your JupyterLab notebook by typing its URL into a web browser. You can bookmark the URL to quickly open it in the future.

If you don't know the URL for your JupyterLab notebook, use the GDC console to open it:

If you aren't signed in to the GDC console, sign in using the steps in Sign in to the GDC console.
In the navigation pane, expand Vertex AI, and click Workbench.
Find the JupyterLab instance you want to open, and click its Open JupyterLab link.
If you are prompted to authenticate, follow the authentication steps for your identity provider.
In the JupyterLab instance, open or create a JupyterLab notebook.

For more information, see Create a JupyterLab notebook.

To share a JupyterLab notebook, do the following:

Get the URL for the JupyterLab notebook. To locate the URL, follow the steps in Open a JupyterLab notebook, and make a note of its URL.
Confirm the person you want to share the JupyterLab notebook with is bound to the Workbench Notebooks Viewer role. For more information, see Grant IAM permission to open a JupyterLab notebook.
Share the URL of the JupyterLab notebook with the person you want to open the JupyterLab notebook.

Grant IAM permission to open a JupyterLab notebook

To access all JupyterLab notebooks in a project, you must grant an Application Operator the Workbench Notebooks Viewer role. To bind a role to another Application Operator, do one of the following:

Have your Project IAM Administrator to grant the Application Operator the Workbench Notebooks Viewer role.
Ask your Project IAM Administrator to grant you the Project IAM Admin role to set up role bindings.

If you have permission to set up role bindings, you can use the GDC console or the gdcloud CLI to bind the Workbench Notebooks Viewer role to another Application Operator yourself.

Allow access to JupyterLab notebooks (GDC console)

This section shows you how to grant the Workbench Notebooks Viewer role using the GDC console.

To use the GDC console to grant permission to open JupyterLab notebooks in a project, follow the steps in Set up project-wide role bindings using the GDC console, and select the Workbench Notebooks Viewer role.

Allow access to JupyterLab notebooks (gdcloud CLI)

This section shows you how to grant the workbench-notebooks-viewer role using the gdcloud CLI.

Create or locate your `kubeconfig` file

Before you run the command, you must have a kubeconfig file. The kubeconfig file for the root administrator is required for a single-tenant deployment. The kubeconfig file for the org admin cluster is required for a multi-tenant deployment.

If you don't have a kubeconfig file, work with your Infrastructure Operator (IO) or Platform Administrator (PA) to locate it. A kubeconfig file is created when an IO creates a root admin cluster or when a PA signs in to a cluster.

Make a note of the name and path of your kubeconfig file. You use it in the gdcloud CLI command to allow access to JupyterLab notebooks in a project.

Run the `kubectl` command

Use the following kubectl command to bind the workbench-notebooks-viewer role to a user. The workbench-notebooks-viewer role grants a user permission to view all notebooks in a project namespace.

kubectl --kubeconfig CLUSTER_KUBECONFIG create rolebinding \
    role-binding-USER-NAME-workbench-notebooks-viewer \
    --role=workbench-notebooks-viewer \ -n PROJECT_NAMESPACE \
    --user=USER_NAME

Replace CLUSTER_KUBECONFIG with the path to the kubeconfig file you made a note of in Create or locate your kubeconfig file.
Replace USER_NAME with the username of the user you want to grant access to your project's notebooks.
Replace PROJECT_NAMESPACE with your project's namespace.

Use a Vertex AI pre-trained model in a JupyterLab notebook

The recommended way to interact with a Vertex AI pre-trained model in a JupyterLab notebook is to use client libraries. You can programmatically use the client library of any of the three pre-trained models installed with Vertex AI on Distributed Cloud:

Optical Character Recognition (OCR) - Use the OCR client library to detect text in images.
Translation - Use the Translation client library to translate text to another language.
Speech-to-Text - Use the Speech-to-Text client library to get text transcriptions from audio files.

To use the Vertex AI pre-trained models in a JupyterLab notebook, do the following:

Enable the Vertex AI pre-trained APIs. For more information, see View Vertex AI service statuses and endpoints.
Install the client libraries. For more information, see Install Vertex AI client libraries.
Open or create a JupyterLab notebook. For more information, see Create a JupyterLab instance and Open a JupyterLab notebook.

After you complete these steps, use your JupyterLab notebook to write code with the Vertex AI client libraries. For more information, see the following topics:

Delete a JupyterLab instance

This section shows you how to delete a JupyterLab instance. Before you delete a JupyterLab instance, consider backing up its files to a bucket.

If you aren't signed into the GDC console, sign in using the steps in Sign in to the GDC console.
In the navigation pane, expand Vertex AI, and click Workbench.
Select the notebook you want to delete, and do one of the following:
- Click Delete in the menu bar.
- Click the three vertical dots at the end of the row for the JupyterLab instance you want to delete.
In the confirmation dialog, click Delete.

Upgrade a JupyterLab instance

After your Infrastructure Operator (IO) updates Distributed Cloud, you can update your JupyterLab instances. For each JupyterLab instance you want to update, do the following:

Save any files from that JupyterLab instance that you want to retain after the update. An AO can save their files to a bucket.
After the update, use the GDC console to create a new JupyterLab instance in Vertex AI Workbench After Distributed Cloud has upgraded, it creates a JupyterLab instance with a new version of a JupyterLab instance. For example, the new JupyterLab instance contains any client library updates that came with the updated Distributed Cloud. For more information, see Create a JupyterLab instance.
Copy the files from the old JupyterLab instance to the new JupyterLab instance.
Optional: Delete the previous version of your JupyterLab instance. For more information, see Delete a JupyterLab instance.