Use reservations with Vertex AI Workbench instances

This document explains how to use Compute Engine reservations to gain a high level of assurance that your Vertex AI Workbench instances have enough virtual machine (VM) resources to run.

Reservations are a Compute Engine feature. They help make sure that you have the resources available to create VMs with the same hardware (memory and vCPUs) and optional resources (GPUs and Local SSD disks) whenever you need them.

When you create a reservation, Compute Engine verifies that the requested capacity is available in the specified zone. If so, then Compute Engine reserves the resources, creates the reservation, and the following happens:

  • The reserved resources are immediately available for you to consume, and they remain available until you delete the reservation.

  • You're charged for the reserved resources at the same on-demand rate as running VMs, including any applicable discounts, until the reservation is deleted. While consuming a reservation, a VM doesn't incur duplicate charges for resources since the reservation is already billed for the cost of the reserved resources. To learn more, see Reservations of Compute Engine zonal resources.

Limitations and requirements

All limitations of Compute Engine reservations apply when Vertex AI Workbench instances consume reservations. See How reservations work.

In addition, when using reservations with Vertex AI Workbench instances, the following limitations and requirements apply:

  • Your reservation must be one of the following:

    • In the same project as your Vertex AI Workbench instance.
    • Shared with the same project as your Vertex AI Workbench instance.

  • A reservation's VM properties must match exactly with your Vertex AI Workbench instance to consume the reservation. For example, if a reservation specifies an e2-standard-8 machine type, then the Vertex AI Workbench instance can only consume the reservation if it also uses an e2-standard-8 machine type. See Requirements.

  • Using reservations with Vertex AI Workbench is only available through the Notebooks API. Using reservations with Vertex AI Workbench by using the Google Cloud console isn't supported.

Before you begin

  1. Review the requirements and restrictions for reservations.
  2. Review the quota requirements and restrictions for shared reservations.
  3. 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.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Enable the Compute Engine and Notebooks APIs.

    Enable the APIs

    6.

  6. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  7. Enable the Compute Engine and Notebooks APIs.

    Enable the APIs

    8.

Required roles

To get the permissions that you need to use reservations with Vertex AI Workbench instances, ask your administrator to grant you the following IAM roles on the project:

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Create a reservation

Create a Compute Engine reservation. It can be a single-project reservation or a shared reservation. For more information, see the following documents:

The reservation can include GPU accelerators.

Use a reservation with a new instance

You can add your reservation when creating a new Vertex AI Workbench instance by using the REST API.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: your project ID
  • LOCATION: the zone where your instance is located
  • INSTANCE_NAME: the name of your instance
  • MACHINE_TYPE: the machine type of your instance
  • RESERVATION_TYPE: the type of reservation; must be RESERVATION_ANY or RESERVATION_SPECIFIC
  • RESERVATION_NAME: the name of your reservation when using the RESERVATION_SPECIFIC type
    • For reservations in the same project, you can use the reservation ID.
    • For reservations in a different project, you must use the full reservation path.

HTTP method and URL: 

POST https://notebooks.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/instances?instanceId=INSTANCE_NAME

Request JSON body: 

{
  "gce_setup": {
    "machine_type": "MACHINE_TYPE",
    "reservation_affinity": {
      "consume_reservation_type": "RESERVATION_TYPE",
      "key": "compute.googleapis.com/reservation-name",
      "values": ["RESERVATION_NAME"]
    }
  }
}

To send your request, choose one of these options:

curl

Save the request body in a file named request.json, and execute the following command: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://notebooks.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/instances?instanceId=INSTANCE_NAME"

PowerShell

Save the request body in a file named request.json, and execute the following command: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://notebooks.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/instances?instanceId=INSTANCE_NAME" | Select-Object -Expand Content
If successful, the response body contains an instance of Operation.

Stop using your reservation

To stop using your reservation, you can delete your reservation.

If you want to continue using your reservation with other resources, but don't want your existing Vertex AI Workbench instance to use it, you must delete the instance.

Billing

When consuming a Compute Engine reservation, you're billed for the following:

  • The Compute Engine resources, including any applicable committed use discounts (CUDs), at Compute Engine pricing. These charges have the label goog-vertex-ai-product: workbench-instances on the SKU. See Compute Engine pricing.

  • Vertex AI Workbench management fees in addition to your infrastructure usage. See Vertex AI Workbench pricing.

Troubleshoot

To find methods for diagnosing and resolving errors, related to using reservations with Vertex AI Workbench instances, see Troubleshooting Vertex AI Workbench instances.

What's next