# Use reservations

This document explains how to use
[Compute Engine reservations](https://docs.cloud.google.com/compute/docs/instances/reservations-overview.md.txt)
to gain a high level of assurance that your Colab Enterprise runtimes
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](https://docs.cloud.google.com/compute/docs/instances/reservations-overview).

## Overview

To use a reservation with Colab Enterprise, you perform the following
tasks:

1. [Create a reservation](https://docs.cloud.google.com/colab/docs/reservations.md.txt#create).

2. [Add your reservation to a new runtime template](https://docs.cloud.google.com/colab/docs/reservations.md.txt#add-reservation).

3. [Use the reservation](https://docs.cloud.google.com/colab/docs/reservations.md.txt#use) by running code on a runtime derived from
   your runtime template.

## Limitations and requirements

All limitations of Compute Engine reservations apply when
Colab Enterprise runtimes consume reservations. See [How reservations
work](https://docs.cloud.google.com/compute/docs/instances/reservations-overview#how-reservations-work).

In addition, when using reservations with
Colab Enterprise, the following limitations
and requirements apply:

- [Committed use discounts](https://docs.cloud.google.com/docs/cuds.md.txt) don't apply.

- Your reservation must be one of the following:

  - In the same project as your Colab Enterprise notebook and runtime.
  - Shared with the same project as your Colab Enterprise notebook and runtime.
- A reservation's VM properties must match exactly with your
  Colab Enterprise runtime to consume the reservation. For example,
  if a reservation specifies an `e2-standard-8` machine type,
  then the Colab Enterprise runtime can only consume the
  reservation if it also uses an `e2-standard-8` machine type. See
  [Requirements](https://docs.cloud.google.com/compute/docs/instances/reservations-overview.md.txt#requirements%22).

## Before you begin

1. Review the [requirements](https://docs.cloud.google.com/compute/docs/instances/reservations-overview.md.txt#requirements) and [restrictions](https://docs.cloud.google.com/compute/docs/instances/reservations-overview.md.txt#restrictions) for reservations.
2. Review the [quota requirements](https://docs.cloud.google.com/compute/docs/instances/reservations-overview.md.txt#requirements-shared-reservations) and [restrictions](https://docs.cloud.google.com/compute/docs/instances/reservations-overview.md.txt#restrictions-shared-reservations) for shared reservations.

### Required roles


To get the permissions that
you need to use reservations with Colab Enterprise,

ask your administrator to grant you the
following IAM roles on the project:

- [Colab Enterprise User](https://docs.cloud.google.com/iam/docs/roles-permissions/aiplatform.md.txt#aiplatform.colabEnterpriseUser) (`roles/aiplatform.colabEnterpriseUser`)
- [Compute Admin](https://docs.cloud.google.com/iam/docs/roles-permissions/compute.md.txt#compute.admin) (`roles/compute.admin`)


For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).


You might also be able to get
the required permissions through [custom
roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined
roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined).
One or more of the required roles includes the `dataform.repositories.list` permission. Users who are granted the `dataform.repositories.list` permission or the [Code Creator
(`roles/dataform.codeCreator`)](https://docs.cloud.google.com/dataform/docs/access-control#dataform.codeCreator) role in a project can list the names of code assets in that project by using the Dataform API or the Dataform command-line interface (CLI). Non-administrators using BigQuery Studio can only see code assets that they created or that were shared with them.

## 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:

- [Create a reservation for a single
  project](https://docs.cloud.google.com/compute/docs/instances/reservations-single-project)
- [Create a shared reservation](https://docs.cloud.google.com/compute/docs/instances/reservations-shared.md.txt)

The reservation can include GPU accelerators.

## Add your reservation to a new runtime template

To create a runtime template that uses your reservation, do the following:

1. In the Google Cloud console, go to
   the Colab Enterprise **Runtime templates** page.

   [Go to Runtime templates](https://console.cloud.google.com/agent-platform/colab/runtime-templates)
2. Click **New
   template**.

   The **Create new runtime template** dialog appears.
3. In the **Runtime basics** section, enter
   a **Display name**.

4. In the **Region** menu, select the region where you want
   your runtime template.

5. In the **Configure compute** section,
   in the **Machine type** menu, select a machine type.
   The runtime template's machine type must match your reservation's
   machine type.

   If the machine types for your reservation and runtime template don't match, Colab Enterprise won't be able to create a runtime from this runtime template.
6. In the **Reservations** menu, select the specific
   reservation that you want to use or select
   **Use automatically selected reservations**.

   For more information about consuming automatically selected or
   specifically targeted reservations, see the
   **Consumption type** section of
   [How
   reservations work](https://docs.cloud.google.com/compute/docs/instances/reservations-overview#how-reservations-work).
7. Complete the rest of the dialog, and then click
   **Create**.

   Your runtime template appears in the list on
   the **Runtime templates** tab.

## Use your reservation

To use your reservation, do the following:

1. [Create a runtime](https://docs.cloud.google.com/colab/docs/create-runtime.md.txt) from your new runtime
   template.

2. Open or [create a notebook](https://docs.cloud.google.com/colab/docs/create-console-quickstart.md.txt).

3. In your notebook, [connect to the runtime](https://docs.cloud.google.com/colab/docs/connect-to-runtime.md.txt),
   and run code.

## Stop using your reservation

To stop using your reservation, you can
[delete your reservation](https://docs.cloud.google.com/compute/docs/instances/reservations-delete.md.txt).

If you want to continue using your reservation with other resources, but
don't want your Colab Enterprise notebooks to use it, delete the
runtime and runtime template that are associated with your reservation.

## Billing

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

- The Compute Engine resources at Compute Engine pricing. These
  charges have the label `goog-vertex-ai-product: colab-enterprise` on the SKU.
  See [Compute Engine pricing](https://cloud.google.com/compute/all-pricing).

- Colab Enterprise management fees in addition to your
  infrastructure usage. See [Colab Enterprise pricing](https://cloud.google.com/colab/pricing).

## Troubleshoot

This section shows you how to resolve issues when using reservations with
Colab Enterprise.

### Unable to create a runtime


An error similar to the following occurs when you try to create a runtime.

```
Failed to create notebook runtime with error: Invalid value for field
'resource.reservationAffinity': '{"consumeReservationType":
"SPECIFIC_ALLOCATION", "key": "compute.googleapis.com/reservation-name...'.
No available resources in specified reservations.
```

This error occurs when a reservation's VM properties don't match your Colab Enterprise
runtime. For example, if a reservation specifies an `e2-standard-8` machine type,
then the Colab Enterprise runtime can only consume the reservation if it also uses an
`e2-standard-8` machine type. For more information,
see [Requirements](https://docs.cloud.google.com/compute/docs/instances/reservations-overview.md.txt#requirements).

To resolve this issue, create a runtime template with a configuration that matches the
reservation's VM properties.

<br />

## What's next

- To grant a principal access to your runtime template, see [Manage access
  to a runtime template](https://docs.cloud.google.com/colab/docs/manage-access-runtime-template).

- To learn more about Compute Engine reservations, see
  [Reservations of Compute Engine zonal
  resources](https://docs.cloud.google.com/compute/docs/instances/reservations-overview).