Manage image versions

This document describes how to manage image versions for Vertex AI Workbench instances, including software stack details and instructions for creating and upgrading instances.

Reference the Vertex AI Workbench release notes to check what is supported with each image version.

VM images

VM images on Vertex AI Workbench instances use two separate versioning schemes: major and minor.

Major versions: Vertex AI Workbench instances use calendar versioning (YY.MM) to mark major releases which introduce significant changes to the underlying image. These can include updates to support in frameworks, OS, and Python versioning. Once a new major version is released, users can expect the following:
- New features will only be developed in the latest release track.
- Older release branches will continue to be updated at the same cadence but are expected to be phased out in the near future.
The image family name reflects the release train (for example, workbench-instances-YYMM).
Minor versions: The minor version is a date-based tag that indicates the specific build of the image, following the format YYYYMMDD-HHMM-rcX. This includes point releases such as bug fixes and security patches applied to the latest release train.

Legacy release track

Image family: workbench-instances

OS: Debian 11
Python: 3.11
Frameworks: TensorFlow/PyTorch/Base (common ML packages)

Minor versioning: The legacy release images will continue to be updated using milestone versioning incremented numerically (for example, m140) to signify minor updates.

Retrieve image list

VM images are stored in a private repository. To retrieve a list of available VM images and their supported configurations, you can use the gcloud workbench instances get-config command in the Google Cloud CLI or the GetConfig API.

gcloud

To retrieve the valid configurations for Vertex AI Workbench instances in a specific location, use the gcloud workbench instances get-config command.

gcloud workbench instances get-config --location=LOCATION

Replace the following:

LOCATION: the Google Cloud region (for example, us-central1).

cURL

To retrieve the configurations using the API, make a GET request to the getConfig endpoint.

curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://notebooks.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/instances:getConfig"

Replace the following:

PROJECT_ID: your Google Cloud project ID.
LOCATION: the region where you want to retrieve configurations.

Create instance with specific VM image

To create a Vertex AI Workbench instance with a specific VM image version, you can use the gcloud CLI or Terraform:

gcloud

Specify the selected image family or image name using the --vm-image-family or --vm-image-name flag in gcloud workbench instances create.

# Using an image family
gcloud workbench instances create INSTANCE_NAME \
  --vm-image-project=cloud-notebooks-managed \
  --vm-image-family=workbench-instances-2603 \
  --location=LOCATION

# Using a specific image name
gcloud workbench instances create INSTANCE_NAME \
  --vm-image-project=cloud-notebooks-managed \
  --vm-image-name=workbench-2603-20260329-2200-rc0 \
  --location=LOCATION

Replace the following:

INSTANCE_NAME: the name of your instance.
LOCATION: the region where you want to create the instance.

For more information on creating an instance with a specific version, see Create a specific version.

Terraform

In the Terraform configuration, set the vm_image block within the google_workbench_instance resource.

resource "google_workbench_instance" "vm_instance" {
  # ... other configurations
  gce_setup {
    vm_image {
      project      = "cloud-notebooks-managed"
      family       = "workbench-instances-2603" # Or use name = "workbench-instances-2603-20240315-1800-rc0"
    }
  }
  # ...
}

Upgrade a VM image

Vertex AI Workbench instances only support upgrading to the latest version based on the image family. A new instance must be created in order to use an older image.

To upgrade a VM image to the latest version within its image family, you can use the gcloud CLI or Terraform:

gcloud

gcloud workbench instances upgrade INSTANCE_NAME --location=LOCATION

Replace the following:

INSTANCE_NAME: the name of your instance.
LOCATION: the region where your instance is located.

Terraform

To upgrade an instance using Terraform, update the family or name in the vm_image block to the selected version and apply the configuration.

resource "google_workbench_instance" "vm_instance" {
  # ... other configurations
  gce_setup {
    vm_image {
      project      = "cloud-notebooks-managed"
      family       = "workbench-instances-2603" # Update to the latest family
    }
  }
}

For more information on upgrading, see Upgrade an instance's environment.

Custom container image

Custom containers on Vertex AI Workbench instances follow a strictly sequential release model without any image branching or parallel maintenance. A date versioning tag is used, which is shared with all the images used to manage custom containers on Vertex AI Workbench instances for any given release. The versioning tag follows the format YYYYMMDD-HHMM-rcX.

Create a custom container-based instance describes how to build and utilize custom containers on Vertex AI Workbench instances.

Host image

Image family: workbench-container-host

The container host uses Google's Container Optimized OS (COS). The version cannot be specified when creating a new Vertex AI Workbench custom container instance. Instead, new instances use the latest COS image as the container host. The underlying image follows the latest stable OS version from COS. See the Container-Optimized OS release notes.

Custom container base images

Custom containers are built on top of the following Google-provided base containers when using Vertex AI Workbench instances:

Base Container: us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest
Slim Container: us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container-slim:latest

The containers are tagged with their corresponding release tag, which can be observed in the Artifact Registry page.

Create instance with container images

To create a Vertex AI Workbench instance using a custom container, the following methods can be used:

gcloud

gcloud workbench instances create INSTANCE_NAME \
  --project=PROJECT_ID \
  --location=ZONE \
  --container-repository=REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/IMAGE_NAME \
  --container-tag=latest

Replace the following:

INSTANCE_NAME: the name of your instance.
PROJECT_ID: your Google Cloud project ID.
ZONE: the zone where you want to create the instance (for example, us-central1-a).
REGION: the region for the Artifact Registry repository (for example, us).
REPOSITORY_NAME: the name of your Artifact Registry repository.
IMAGE_NAME: the name of your container image.

Terraform

Set the container_image block within the google_workbench_instance resource.

resource "google_workbench_instance" "container_instance" {
  # ... other configurations
  gce_setup {
    container_image {
      repository = "us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container"
      tag  = "latest"
    }
  }
  # ...
}

Upgrading custom containers

To upgrade the container host image, see Upgrading VM image for examples using gcloud or Terraform.

To upgrade the custom container image, a mutable tag (such as :latest) can be used. When the custom container instance is restarted, the image is repulled if changes have been made to that tag in the registry. Alternatively, the instance can be updated to use a different image tag.

Limitations

Vertex AI Workbench instances don't provide an API surface to directly upgrade between major versions. Data disks must be backed up and the restore method used to create a new instance with the latest release. For more information, see Restore a snapshot.