Manage features through metadata

This page describes how to manage some Vertex AI Workbench instance features by modifying the instance's metadata key-value pairs.

Metadata keys

For information about features and their respective metadata keys, see the following table.

Feature

Description

Metadata key

Accepted values and defaults

Enables Cloud Storage FUSE on a container image

Mounts /dev/fuse onto the container and enables gcsfuse for use on the container.

container-allow-fuse

true : Enables Cloud Storage FUSE.
false (default): Doesn't enable Cloud Storage FUSE.

nbconvert

Lets you export and download notebooks as a different file type.

notebook-disable-nbconvert

true : Turns off nbconvert.
false (default): Enables nbconvert.

Delete to trash

Uses the operating system's trash behavior when deleting from JupyterLab.

notebook-enable-delete-to-trash

true : Enables deleting to the trash.
false (default): Uses the default JupyterLab behavior.

Dataproc

Enables access to Dataproc kernels.

For more information, see Create a Dataproc-enabled instance .

disable-mixer

true : Turns off access to Dataproc kernels.
false (default): Enables access to Dataproc kernels.

Idle shutdown

Enables idle shutdown.

For more information, see Idle shutdown .

idle-timeout-seconds

An integer representing the idle time in seconds. The default value is 10800 seconds (180 minutes).

Guest attributes

Enables guest attributes. Required for running idle shutdown.

For more information, see Requirements for running idle shutdown .

enable-guest-attributes

true (default): Enables guest attributes.

false : Turns off guest attributes.

Scheduled OS patches

Schedules automatic OS updates of the instance. This enables Debian's unattended upgrade service and only applies to VM-based images.

install-unattended-upgrades

true : Turns on automatic OS updates.
false (default): Turns off automatic OS updates.

Custom Jupyter user

Specifies the name of the default Jupyter user. This setting determines the name of the folder for your notebooks. For example, instead of the default /home/jupyter/ directory, you can change the directory to /home/ CUSTOM_NAME . This metadata key doesn't affect access to the instance.

jupyter-user

A string. The default value is jupyter .

File downloading

Lets you download files from JupyterLab.

notebook-disable-downloads

true : Turns off file downloading.
false (default): Enables file downloading.

Root access

Enables root access.

notebook-disable-root

true : Turns off root access.
false (default): Enables root access.

Terminal access

Enables terminal access.

notebook-disable-terminal

true : Turns off terminal access.
false (default): Enables terminal access.

Scheduled upgrades

Schedules automatic upgrades of the instance.

notebook-upgrade-schedule

The weekly or monthly schedule that you set, in unix-cron format , for example, 00 19 * * MON means weekly on Monday, at 1900 hours Greenwich Mean Time (GMT). This feature is off by default.

Post-startup script

Runs a custom script after startup.

post-startup-script

The URI of a post-startup script in Cloud Storage, for example: gs://bucket/hello.sh . This feature is off by default.

Post-startup script behavior

Defines when and how the post-startup script runs.

post-startup-script-behavior

run_once (default): Runs the post-startup script once after instance creation or upgrade.
run_every_start : Runs the post-startup script after every start.
download_and_run_every_start : Redownloads the post-startup script from its source then runs the script after every start.

Report event health

Checks health every 30 seconds for VM metrics.

report-event-health

true (default): Enables event health reporting.
false : Turns off event health reporting.

Enable JupyterLab 4 preview

Enables JupyterLab 4 ( Preview ) on your instance. For more information, see JupyterLab 4 preview .

enable-jupyterlab4-preview

true : Enables JupyterLab 4.
false (default): Enables JupyterLab 3.

Metadata managed by Compute Engine

Some of the metadata keys are predefined by Compute Engine. For more information, see Predefined metadata keys .

Protected metadata keys

Some metadata keys are reserved for system use only. If you assign values to these metadata keys, the new values will be overwritten by the system values.

Reserved metadata keys include and are not limited to:

data-disk-uri
enable-oslogin
framework
notebooks-api
notebooks-api-version
nvidia-driver-gcs-path
proxy-url
restriction
shutdown-script
title
version

Create an instance with specific metadata

You can create a Vertex AI Workbench instance with specific metadata by using the Google Cloud console, the Google Cloud CLI, Terraform, or the Notebooks API.

Console

When you create a Vertex AI Workbench instance, you can add metadata in the Environmentsection of Advanced options.

The Add metadata button in the Environment section

gcloud

When you create a Vertex AI Workbench instance, you can add metadata by using the following command:

gcloud  
workbench  
instances  
create  
 INSTANCE_NAME 
  
--metadata = 
  KEY 
 
 = 
 VALUE

Terraform

To add metadata, create the resource with metadata key-value pairs.

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"
    vm_image {
      project = "cloud-notebooks-managed"
      family  = "workbench-instances"
    }
    metadata = {
      key = "value"
    }
  }
}

Notebooks API

Use the instances.create method with metadata values to manage the corresponding features.

Update an instance's metadata

You can update the metadata of a Vertex AI Workbench instance by using the Google Cloud console, the Google Cloud CLI, Terraform, or the Notebooks API.

Console

To update the metadata of a Vertex AI Workbench instance, do the following:

In the Google Cloud console, go to the Instancespage.

Go to Instances
In the list of instances, click the name of the instance that you want to update.
On the Instance detailspage, click Software and security.
In the Metadatasection, update the metadata key-value pairs that you want to change.
Click Submit.

gcloud

You can update the metadata on a Vertex AI Workbench instance by using the following command:

gcloud  
workbench  
instances  
update  
 INSTANCE_NAME 
  
--metadata = 
  KEY 
 
 = 
 VALUE

Terraform

You can change the metadata key-value pairs to manage the corresponding features on Vertex AI Workbench instances.

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"
    vm_image {
      project = "cloud-notebooks-managed"
      family  = "workbench-instances"
    }
    metadata = {
      key = "updated_value"
    }
  }
}

Notebooks API

Use the instances.patch method with metadata values and gce_setup.metadata in the updateMask to manage the corresponding features.

Remove metadata from an instance

You can remove metadata from a Vertex AI Workbench instance by using the Google Cloud console, the Google Cloud CLI, Terraform, or the Notebooks API.

Console

To remove metadata from a Vertex AI Workbench instance, do the following:

In the Google Cloud console, go to the Instancespage.

Go to Instances
In the list of instances, click the name of the instance that you want to modify.
On the Instance detailspage, click Software and security.
In the Metadatasection, to the right of a key-value pair that you want to delete, click Delete.
Click Submit.

gcloud

You can remove metadata from a Vertex AI Workbench instance by using the following command:

gcloud  
workbench  
instances  
update  
 INSTANCE_NAME 
  
--metadata = 
 KEY

Terraform

You can remove metadata key-value pairs to manage the corresponding features of a Vertex AI Workbench instance.

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"
    vm_image {
      project = "cloud-notebooks-managed"
      family  = "workbench-instances"
    }
    metadata = {
    }
  }
}

Notebooks API

Use the instances.patch method with the metadata value set to an empty string and gce_setup.metadata in the updateMask to remove the corresponding feature.