Create a Vertex AI Workbench instance

Console

1. In the Google Cloud console, go to the Instances page.

   Go to Instances

2. Click add_box Create new.

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

4. In the Create instance dialog, 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 Vertex AI Workbench 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:

   • JupyterLab version: To enable JupyterLab 4 (Preview), select JupyterLab 4.x. If unselected, your instance will use JupyterLab 3. For more information, see JupyterLab 4 preview.
   • Version: Use the latest version or a previous version of Vertex AI Workbench 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. The accelerator type that you want must be available in your instance's zone. To learn about accelerator availability by zone, see GPU regions and zones availability. For information about the different GPUs, see GPUs on Compute Engine.

     Select Install NVIDIA GPU driver automatically for me.

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

     • 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 data disk settings, select a 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.

   • 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 from the service project.

     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.

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

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

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.

     To learn more about granting access, see Manage access.

   • Security options: Select or clear the following checkboxes:

     • Root access to the instance
     • nbconvert
     • File downloading
     • Terminal access

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 an instance and automatically starts it. 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 Vertex AI Workbench 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 zone where you want your instance to be located
• VM_IMAGE_PROJECT: the ID of the Google Cloud project that VM image belongs to; the default Google Cloud project ID for supported images is cloud-notebooks-managed
• VM_IMAGE_NAME: the image name; to find the image name of a specific version, see Find the specific version
• MACHINE_TYPE: the machine type of your instance's VM

• METADATA: custom metadata to apply to this instance; for example, to specify a post-startup-script, you can use the post-startup-script metadata tag, in the format: --metadata=post-startup-script=gs://BUCKET_NAME/hello.sh

Execute the following command:

gcloud workbench instances create INSTANCE_NAME \
    --project=PROJECT_ID \
    --location=LOCATION \
    --vm-image-project=VM_IMAGE_PROJECT \
    --vm-image-name=VM_IMAGE_NAME \
    --machine-type=MACHINE_TYPE \
    --metadata=METADATA

gcloud workbench instances create INSTANCE_NAME `
    --project=PROJECT_ID `
    --location=LOCATION `
    --vm-image-project=VM_IMAGE_PROJECT `
    --vm-image-name=VM_IMAGE_NAME `
    --machine-type=MACHINE_TYPE `
    --metadata=METADATA

gcloud workbench instances create INSTANCE_NAME ^
    --project=PROJECT_ID ^
    --location=LOCATION ^
    --vm-image-project=VM_IMAGE_PROJECT ^
    --vm-image-name=VM_IMAGE_NAME ^
    --machine-type=MACHINE_TYPE ^
    --metadata=METADATA

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

Vertex AI Workbench creates an instance and automatically starts it. When the instance is ready to use, Vertex AI Workbench activates an Open JupyterLab link in the Google Cloud console.

Terraform

The following sample uses the google_workbench_instance Terraform resource to create a Vertex AI Workbench instance named workbench-instance-example.

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

resource "google_workbench_instance" "default" {
  name     = "workbench-instance-example"
  location = "us-central1-a"

  gce_setup {
    machine_type = "n1-standard-1"
    accelerator_configs {
      type       = "NVIDIA_TESLA_T4"
      core_count = 1
    }
    vm_image {
      project = "cloud-notebooks-managed"
      family  = "workbench-instances"
    }
  }
}

Console

To change the JupyterLab version on an existing instance, do the following:

1. In the Google Cloud console, go to the Instances page.

   Go to Instances

2. Click the name of your instance to open the Instance details page.

3. On the System tab, do one of the following:

   • To enable the preview, select Enable JupyterLab 4 preview.

   • To turn off the preview and use JupyterLab 3, clear Enable JupyterLab 4 preview.

4. Click Submit.

5. Reset your instance.

gcloud

You can change the JupyterLab version on an existing instance by using the following command:

gcloud workbench instances update INSTANCE_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --metadata=enable-jupyterlab4-preview=ENABLEMENT_BOOLEAN

Replace the following:

• PROJECT_ID: your project ID
• LOCATION: the zone where you want your instance to be located
• INSTANCE_NAME: the name of your Vertex AI Workbench instance

• ENABLEMENT_BOOLEAN: use one of the following:

  • true: enables the JupyterLab 4 preview
  • false: turns off the JupyterLab 4 preview and changes to JupyterLab 3