Create a shared reservation


This document explains how to create shared reservations, which are reservations shared across multiple projects, and manage which projects in your organization can consume the shared reservations.

A shared reservation can be used by the project that hosts the reservation (owner project) and by the projects the reservation is shared with (consumer projects). Use shared reservations if your organization has multiple projects that need virtual machine (VM) instances with the same properties reserved. By using shared reservations, you can improve the utilization of your reservations and reduce the number of reservations that you need to create and manage. To learn more about reservations, see Reservations of Compute Engine zonal resources.

For other methods of creating reservations, see instead the following pages:

  • If you have any 1-year or 3-years commitments in the current project, then your reserved resources automatically receive any applicable committed use discounts (CUDs). You can also create and attach a reservation to a commitment when you purchase the commitment. To learn more, see Attach reservations to commitments.

  • To create a reservation that can only be used by a single project, see Create a reservation for a single project.

Before you begin

  • Review the requirements and restrictions for reservations.
  • Review the requirements and restrictions for shared reservations.
  • Make sure the project you use to create shared reservations has been added to the allowlist for the Shared Reservations Owner Projects (compute.sharedReservationsOwnerProjects) organization policy constraint by an organization policy administrator. This allowlist is empty by default, so you can't create shared reservations until your organization grants this permission to one or more projects. For more details on viewing and editing the organization policy constraint, see Allowing and restricting projects from creating and modifying shared reservations in this document.
  • If you haven't already, set up authentication. Authentication is the process by which your identity is verified for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine as follows.

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    1. Install the Google Cloud CLI, then initialize it by running the following command:

      gcloud init
    2. Set a default region and zone.

    Terraform

    To use the Terraform samples on this page from a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.

    1. Install the Google Cloud CLI.
    2. To initialize the gcloud CLI, run the following command:

      gcloud init
    3. Create local authentication credentials for your Google Account:

      gcloud auth application-default login

    For more information, see Set up authentication for a local development environment.

    REST

    To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

      Install the Google Cloud CLI, then initialize it by running the following command:

      gcloud init

Required roles

To get the permissions that you need to create shared reservations, ask your administrator to grant you the following IAM roles:

For more information about granting roles, see Manage access.

These predefined roles contain the permissions required to create shared reservations. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to create shared reservations:

  • compute.reservations.create on the project
  • To view organization policies: orgpolicy.policy.get on the organization
  • To edit organization policies: orgpolicy.policy.set on the organization
  • To specify an instance template: compute.instanceTemplates.useReadOnly on the instance template

You might also be able to get these permissions with custom roles or other predefined roles.

Best practices

When creating shared reservations, the following best practices are recommended. By following them, you can help optimize the manageability and utilization of shared reservations in your organization.

  • Have the owner project create the shared reservation but not consume it.
    • To spread spendings across projects, it's recommended to only have consumer projects consume a shared reservation. The owner project should only be used to create the shared reservation.
    • The owner project must have sufficient quota for twice the resources to reserve. For more information, see Additional requirements for shared reservations.
  • Minimize the number of projects in your organization that you allow to create shared reservations. You can control this through the Shared Reservations Owner Projects (compute.sharedReservationsOwnerProjects) organization policy constraint.
    • You can only list the reservations created by each project. This means that shared reservations are only listed in the owner project—you cannot list the reservations shared with each project or list all shared reservations in each organization—so having only a few owner projects makes it easier to monitor and manage your shared reservations.
    • Limit the sharing of a shared reservation to a few projects only to manage the quota of your reserved resources more easily.
    • For more information, see Allow and restrict projects from creating and modifying shared reservations.
  • Minimize the number of separate shared reservations with identical VM properties.
    • An organization can have up to 100 shared reservations for each unique combination of VM properties. As a result, minimizing the number of shared reservations with identical VM properties that you create helps mitigate this limit.
    • Having fewer shared reservations improves manageability.
  • Only share reservations between projects with the same Cloud Billing account.
    • Limit each shared reservation to only be shared with consumer projects that have the same Cloud Billing account as the owner project. This makes it easier for you to see if a reservation was consumed and how it was billed.
    • If you enabled CUD sharing and you're eligible to receive CUDs at the Cloud Billing account level, then, to maximize the CUDs you receive for your consumed reservations, limit your shared reservations to that commitment's Cloud Billing account. Doing this lets you maintain consistent billing across projects that create and consume shared reservations.
  • For future reservation requests, carefully review the total count of VMs that you request.
    • If you are creating a future reservation request, ensure that you request a total count of VMs that accounts for all of the following:
      • All matching reserved VMs that will already exist at the future date.
      • All matching unreserved VMs that will already exist at the future date.
      • Any matching unused on-demand reservations that will already exist at the future date.
      • The increase in usage that you want to reserve at the future date.

      For example, suppose you need 10 additional VMs at the future date and you'll already have the following resources at the future date:

      • 40 matching reserved VMs
      • 50 matching unreserved VMs

      or

      • 40 matching reserved VMs
      • 50 matching unused on-demand reservations

      Because your existing usage at the future date already adds up to 90 matching VMs and reservations, and you need an additional ten VMs, you must specify a total count of 100 in your future reservation request.

      For more information, see Count and provision reserved resources.

Allow and restrict projects from creating and modifying shared reservations

By default, no projects are allowed to create or modify shared reservations in an organization. Add projects to the Shared Reservations Owner Projects (compute.sharedReservationsOwnerProjects) organization policy constraint to allow them to create and modify shared reservations. For more information about organization policy constraints, see Introduction to the Organization Policy Service.

Use the following steps to view and edit the Shared Reservations Owner Projects (compute.sharedReservationsOwnerProjects) organization policy constraint.

View the shared reservations organization policy constraint

To see which projects are allowed to create and modify shared reservations, use the Google Cloud console or gcloud CLI.

Console

Follow the steps for Viewing organization policies using the Shared Reservations Owner Projects constraint.

gcloud

To see which projects the compute.sharedReservationsOwnerProjects constraint allows to create and modify shared reservations:

  1. Download the policy for your organization as a file named policy.yaml, using the gcloud resource-manager org-policies describe command:

    gcloud resource-manager org-policies describe compute.sharedReservationsOwnerProjects --organization=ORGANIZATION_ID > policy.yaml
    

    Replace ORGANIZATION_ID with the organization ID of your organization.

  2. Use a text editor to open the policy.yaml file and view the compute.sharedReservationsOwnerProjects constraint. The projects that are allowed to create and modify shared reservations are listed under its allowedValues:

    ...
    constraint: constraints/compute.sharedReservationsOwnerProjects
    listPolicy:
      allowedValues:
      - projects/PROJECT_NUMBER_1
      - projects/PROJECT_NUMBER_2
      - projects/PROJECT_NUMBER_3
    ...
    

    where PROJECT_NUMBER_1, PROJECT_NUMBER_2, and PROJECT_NUMBER_3 are the project numbers of the only projects in your organization that are allowed to create shared reservations.

  3. Optional: Delete the policy.yaml file.

    • If you are using a Linux or macOS terminal, use the following command:

      rm policy.yaml
      
    • If you are using a Windows terminal, use the following command:

      del policy.yaml
      

Edit the shared reservations organization policy constraint

To edit which projects are allowed to create and modify shared reservations, use the Google Cloud console or gcloud CLI.

Console

Follow the steps for Customizing policies for list constraints using the Shared Reservations Owner Projects constraint.

gcloud

To edit which projects the compute.sharedReservationsOwnerProjects constraint allows to create and modify shared reservations, use one of the following methods:

  • To grant permission to a single project to create and modify shared reservations, use the gcloud resource-manager org-policies allow command. You can repeat this command for each project that you want to grant this permission to.

    gcloud resource-manager org-policies allow compute.sharedReservationsOwnerProjects projects/PROJECT_NUMBER \
        --organization=ORGANIZATION_ID
    

    Replace the following:

    • PROJECT_NUMBER: the project number (not project ID) of a project in your organization that you want to allow to create and modify shared reservations.
    • ORGANIZATION_ID: the organization ID of your organization.
  • To grant or revoke the permissions for multiple projects to create and modify shared reservations, replace the organization policy constraint:

    1. To download the policy for your organization as a file named policy.yaml, use the gcloud resource-manager org-policies describe command:

      gcloud resource-manager org-policies describe compute.sharedReservationsOwnerProjects --organization=ORGANIZATION_ID > policy.yaml
      

      Replace ORGANIZATION_ID with the organization ID of your organization.

    2. Use a text editor to modify the policy.yaml file so that the compute.sharedReservationsOwnerProjects constraint lists all of the projects that you want to be allowed to create and modify shared reservations under its allowedValues.

      • For each project that you want to grant the permission to create and modify shared reservations, add the project in a new line under allowedValues.
      • For each project that you want to revoke the permission to create and modify shared reservations, delete the line for that project.

      When you are finished, make sure the policy.yaml file looks similar to the following:

      ...
      constraint: constraints/compute.sharedReservationsOwnerProjects
      listPolicy:
        allowedValues:
        - projects/PROJECT_NUMBER_1
        - projects/PROJECT_NUMBER_2
        - projects/PROJECT_NUMBER_3
      ...
      

      where PROJECT_NUMBER_1, PROJECT_NUMBER_2, and PROJECT_NUMBER_3 are the project numbers (not project IDs) of all of the projects in your organization that you want to be allowed to create and modify shared reservations.

    3. Save the policy.yaml file and close the text editor.

    4. To update the policy for your organization with your changes, use the gcloud resource-manager org-policies set-policy command:

      gcloud resource-manager org-policies set-policy --organization=ORGANIZATION_ID policy.yaml
      

      Replace ORGANIZATION_ID with the organization ID of your organization.

    5. Optional: Delete the policy.yaml file.

      • If you are using a Linux or macOS terminal, use the following command:

        rm policy.yaml
        
      • If you are using a Windows terminal, use the following command:

        del policy.yaml
        

You might need to wait a few minutes for the edit to take effect.

Create a shared reservation

This section explains how to create shared reservations. After you create a shared reservation, it can be modified only by the owner project, but the resources for a shared reservation can be consumed by the owner project or any consumer projects.

To consume a reservation, a VM must have properties that exactly match that reservation. To specify the properties of the VMs that you want to reserve, select one of the following sections in this document:

  • Recommended: Specify an instance template

    This section explains how to use an instance template to define the properties of a shared reservation. By using an instance template, you can define the properties of a reservation and the VMs that can consume the reservation in the same place. However, because templates are project-specific, you can't use the same template to create VMs that can consume the reservation outside of the project that created the reservation. For the projects the reservation is shared with, you must create similar templates in those projects or create VMs by specifying properties directly.

  • Specify properties directly

    This section explains how to directly define the properties of a shared reservation. This method requires you to manually ensure that the properties of your VMs and reservations match exactly—any mismatched properties prevent consumption.

By default, a reservation can be automatically consumed by any VMs with properties that match it. If you want to control reservation consumption, do one or more of the following:

Specify an instance template

To create a shared reservation by specifying an instance template, you can use the Google Cloud console, gcloud CLI, or REST.

Console

To create a shared reservation by specifying an instance template, do the following:

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

    Go to Reservations

    The Reservations page appears.

  2. Click Create reservation.

    The Create a reservation page appears.

  3. In the Name field, enter a name for your reservation.

  4. Select the Region and Zone where you want to reserve resources.

  5. In the Share type section, do the following:

    1. To specify a shared reservation, click Shared.

    2. Click Add projects, and then select the projects from the current project's organization that you want to share the reservation with.

  6. In the Use with VM instance section, select one of the following options:

    • To allow matching VM instances to automatically use this reservation, click Use reservation automatically (default).

    • To consume this reservation's resources only when creating matching VMs that specifically target this reservation by name, click Select specific reservation.

  7. In the Number of VM instances field, enter the number of VMs that you want to reserve.

  8. In the Machine configuration section, do the following:

    1. To specify the properties of your VMs from an existing instance template, select Use instance template.

    2. In the Instance template field, select the instance template of your choice. If you select a regional instance template, you can only reserve resources within the region of the instance template.

  9. In the Auto-delete section, you can enable the auto-delete option to let Compute Engine automatically delete the reservation at a specific date and time. Automatically deleting reservations can be useful to avoid unnecessary charges when you stop consuming the reservation.

  10. To create the reservation, click Create.

    Creating the shared reservation might take some time to complete. This action redirects you to the Reservations page.

gcloud

To create a shared reservation by specifying an instance template, use the gcloud compute reservations create command.

To create a shared reservation by specifying an instance template without any optional flags, run the following command:

gcloud compute reservations create RESERVATION_NAME \
    --project=PROJECT_ID \
    --share-setting=projects \
    --share-with=CONSUMER_PROJECT_IDS \
    --source-instance-template=projects/PROJECT_ID/LOCATION/instanceTemplates/INSTANCE_TEMPLATE_NAME \
    --vm-count=NUMBER_OF_VMS \
    --zone=ZONE

Replace the following:

  • RESERVATION_NAME: the name of the reservation to create.

  • PROJECT_ID: the ID of the project where you want to reserve resources and where the instance template exists.

  • CONSUMER_PROJECT_IDS: a comma-separated list of IDs of projects that can consume this reservation—for example, project-1,project-2. You can include up to 100 consumer projects. These projects must be in the same organization as the owner project. Don't include the owner project. By default, it is already allowed to consume the reservation.

  • LOCATION: the location of the instance template. Specify one of the following values:

    • For a global instance template: global.

    • For a regional instance template: regions/REGION. Replace REGION with the region where the instance template is located. If you specify a regional instance template, you can only reserve VMs within the region of the instance template.

  • INSTANCE_TEMPLATE_NAME: the name of an existing instance template. If you specify an instance template, you can't override any of its properties when creating the reservation. Otherwise, you encounter errors.

  • NUMBER_OF_VMS: the number of VMs to reserve.

  • ZONE: the zone in which to reserve resources.

For example, to create a reservation by specifying a global instance template in zone us-central1-a, share the reservation with projects project-1 and project-2, and reserve ten VMs that each use an N2 predefined machine type with 4 vCPUs, run the following command:

gcloud compute reservations create my-reservation \
    --project=example-project \
    --share-setting=projects \
    --share-with=project-1,project-2 \
    --source-instance-template=projects/example-project/global/example-instance-template \
    --vm-count=10 \
    --zone=us-central1-a

Optionally, you can do one or more of the following:

  • To specify that only VMs that specifically target this reservation can consume it, include the --require-specific-reservation flag.

    gcloud compute reservations create example-reservation \
        --require-specific-reservation \
        ...
    
  • To enable Compute Engine to automatically delete the reservation, select one of the following methods:

    • To delete the reservation at a specific date and time, use the gcloud beta compute reservations create command and include the --delete-at-time flag.

      gcloud beta compute reservations create reservation-example \
          --delete-at-time=DELETE_AT_TIME \
          ...
      

      Replace DELETE_AT_TIME with a date and time formatted as an RFC 3339 timestamp, which must be as follows:

      YYYY-MM-DDTHH:MM:SSOFFSET
      

      Replace the following:

      • YYYY-MM-DD: a date formatted as a 4-digit year, 2-digit month, and a 2-digit day of the month, separated by hyphens (-).

      • HH:MM:SS: a time formatted as a 2-digit hour using a 24-hour time, 2-digit minutes, and 2-digit seconds, separated by colons (:).

      • OFFSET: the time zone formatted as an offset of Coordinated Universal Time (UTC). For example, to use the Pacific Standard Time (PST), specify -08:00. Alternatively, to use no offset, specify Z.

    • To delete the reservation after a specific duration, use the gcloud beta compute reservations create command and include the --delete-after-duration flag.

      gcloud beta compute reservations create reservation-example \
          --delete-after-duration=DELETE_AFTER_DURATION \
          ...
      

      Replace DELETE_AFTER_DURATION with a duration in days, hours, minutes, or seconds. For example, specify 30m for 30 minutes, or 1d2h3m4s for 1 day, 2 hours, 3 minutes, and 4 seconds.

REST

To create a shared reservation by specifying an instance template, make a POST request to the reservations.insert method.

For example, to create a shared reservation by specifying an instance template without any optional fields and share the reservation with two consumer projects, make the following POST request:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations

{
  "name": "RESERVATION_NAME",
  "shareSettings": {
    "shareType": "SPECIFIC_PROJECTS",
    "projectMap": {
      "CONSUMER_PROJECT_ID_1": {
        "projectId": "CONSUMER_PROJECT_ID_1"
      },
      "CONSUMER_PROJECT_ID_2": {
        "projectId": "CONSUMER_PROJECT_ID_2"
      }
    }
  },
  "specificReservation": {
    "count": "NUMBER_OF_VMS",
    "sourceInstanceTemplate": "projects/PROJECT_ID/LOCATION/instanceTemplates/INSTANCE_TEMPLATE_NAME"
  }
}

Replace the following:

  • PROJECT_ID: the ID of the project where you want to reserve resources and where the instance template exists.

  • ZONE: the zone in which to reserve resources.

  • RESERVATION_NAME: the name of the reservation to create.

  • CONSUMER_PROJECT_ID_1 and CONSUMER_PROJECT_ID_2: the IDs of projects that can consume this reservation. You can include up to 100 consumer projects. These projects must be in the same organization as the owner project. Don't include the owner project. By default, it is already allowed to consume the reservation.

  • NUMBER_OF_VMS: the number of VMs to reserve.

  • LOCATION: the location of the instance template. Specify one of the following values:

    • For a global instance template: global.

    • For a regional instance template: regions/REGION. Replace REGION with the region where the instance template is located. If you specify a regional instance template, you can only reserve VMs within the region of the instance template.

  • INSTANCE_TEMPLATE_NAME: the name of an existing instance template. If you specify an instance template, you can't override any of its properties when creating the reservation. Otherwise, you encounter errors.

For example, to create a reservation for ten VMs in zone us-central1-a by specifying a global instance template, and share the reservation with projects project-1 and project-2, make the following POST request:

POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/reservations

{
  "name": "my-reservation",
  "shareSettings": {
    "shareType": "SPECIFIC_PROJECTS",
    "projectMap": {
      "project-1": {
        "projectId": "project-1"
      },
      "project-2": {
        "projectId": "project-2"
      }
    }
  },
  "specificReservation": {
    "count": "10",
    "sourceInstanceTemplate": "projects/example-project/global/instanceTemplates/example-instance-template"
  }
}

Optionally, you can do one or more of the following:

  • To specify that only VMs that specifically target this reservation can consume it, include the specificReservationRequired field in the request body and set it to true.

    POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/reservations
    
    {
      "name": "example-reservation",
      "specificReservationRequired": true,
      ...
    }
    
  • To enable Compute Engine to automatically delete the reservation, select one of the following methods:

    • To delete the reservation at a specific date and time, make a POST request to the beta.reservations.insert method. In the request body, include the deleteAtTime field.

      POST https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/reservations
      
      {
        "name": "example-reservation",
        "deleteAtTime": "DELETE_AT_TIME",
        ...
      }
      

      Replace DELETE_AT_TIME with a date and time formatted as an RFC 3339 timestamp, which must be as follows:

      YYYY-MM-DDTHH:MM:SSOFFSET
      

      Replace the following:

      • YYYY-MM-DD: a date formatted as a 4-digit year, 2-digit month, and a 2-digit day of the month, separated by hyphens (-).

      • HH:MM:SS: a time formatted as a 2-digit hour using a 24-hour time, 2-digit minutes, and 2-digit seconds, separated by colons (:).

      • OFFSET: the time zone formatted as an offset of Coordinated Universal Time (UTC). For example, to use the Pacific Standard Time (PST), specify -08:00. Alternatively, to use no offset, specify Z.

    • To delete the reservation after a specific duration, make a POST request to the beta.reservations.insert method. In the request body, include the deleteAfterDuration field.

      POST https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/reservations
      
      {
        "name": "example-reservation",
        "deleteAfterDuration": {
          "seconds": "DELETE_AFTER_DURATION"
        },
        ...
      }
      

      Replace DELETE_AFTER_DURATION with a duration in seconds. For example, specify 86400 for 86,400 seconds (1 day).

Specify VM properties directly

To create a shared reservation by specifying properties directly, use the Google Cloud console, gcloud CLI, Terraform, or REST.

Console

To create a shared reservation, do the following:

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

    Go to Reservations

    The Reservations page appears.

  2. Click Create reservation.

    The Create a reservation page appears.

  3. In the Name field, enter a name for your reservation.

  4. Select the Region and Zone where you want to reserve resources.

  5. In the Share type section, do the following:

    1. To specify a shared reservation, click Shared.

    2. Click Add projects, and then select the projects from the current project's organization that you want to share the reservation with.

  6. In the Use with VM instance section, select one of the following options:

    • To allow matching VMs to automatically consume this reservation, click Use reservation automatically (default).

    • To consume this reservation's resources only when creating matching VMs that specifically target this reservation by name, click Select specific reservation.

  7. In the Number of VM instances field, enter the number of VMs that you want to reserve.

  8. In the Machine configuration section, select Specify machine type, and then specify the following:

    1. In the Machine family, Series, and Machine type fields, select a machine family, series, and machine type.

    2. Optional: To specify a minimum CPU platform and/or GPUs, do the following:

      1. To expand the CPU Platform and GPU section, click the expander arrow.

      2. Optional: To specify a minimum CPU platform, in the CPU Plaform list, select an option.

      3. Optional: To add GPUs, click Add GPU. Then, in the GPU type and Number of GPUs fields, select the type and number of GPUs for each VM.

    3. Optional: To add Local SSDs, do the following:

      1. In the Number of disks field, select the number of Local SSDs for each VM.

      2. In the Interface type field, select the interface for the Local SSDs.

  9. In the Auto-delete section, you can enable the auto-delete option to let Compute Engine automatically delete the reservation at a specific date and time. Automatically deleting reservations can be useful to avoid unnecessary charges when you stop consuming the reservation.

  10. To create the reservation, click Create.

    Creating the shared reservation might take some time to complete. This action redirects you to the Reservations page.

gcloud

To create a shared reservation, use the gcloud compute reservations create command.

To create a shared reservation without any optional flags, run the following command:

gcloud compute reservations create RESERVATION_NAME \
    --machine-type=MACHINE_TYPE \
    --project=PROJECT_ID \
    --share-setting=projects \
    --share-with=CONSUMER_PROJECT_IDS \
    --vm-count=NUMBER_OF_VMS \
    --zone=ZONE

Replace the following:

  • RESERVATION_NAME: the name of the reservation to create.

  • MACHINE_TYPE: a machine type to use for each VM. Specify one of the following values:

    • For a predefined machine type: MACHINE_FAMILY-standard-CPUS.

    • For a custom machine type: MACHINE_FAMILY-custom-CPUS-MEMORY. Before specifying a custom machine type, review the limitations for VMs with custom machine types.

    Replace the following:

    • MACHINE_FAMILY: the machine family.

    • CPUS: the number of vCPUs.

    • MEMORY: the total memory for a reserved VM. Memory must be a multiple of 256 MB and must be supplied in MB.

    For example, to specify an N2 custom machine type with 4 vCPUs and 5 GB of memory, which is 5,120 MB, specify n2-custom-4-5120.

  • PROJECT_ID: the ID of the project where you want to reserve resources.

  • CONSUMER_PROJECT_IDS: a comma-separated list of IDs of projects that can consume this reservation—for example, project-1,project-2. You can include up to 100 consumer projects. These projects must be in the same organization as the owner project. Don't include the owner project. By default, it is already allowed to consume the reservation.

  • NUMBER_OF_VMS: the number of VMs to reserve.

  • ZONE: the zone in which to reserve resources.

For example, to create a reservation for ten VMs in zone us-central1-a by specifying a global instance template, and share the reservation with projects project-1 and project-2, run the following command:

gcloud compute reservations create my-reservation \
    --machine-type=n2-standard-4 \
    --project=example-project \
    --share-setting=projects \
    --share-with=project-1,project-2 \
    --vm-count=10 \
    --zone=us-central1-a

Optionally, you can do one or more of the following:

  • To add graphics processing units (GPUs) to each reserved VM, include the --accelerator flag.

    gcloud compute reservations create my-reservation \
        --accelerator=count=NUMBER_OF_ACCELERATORS,type=ACCELERATOR_TYPE
        ...
    

    Replace the following:

    • NUMBER_OF_ACCELERATORS: the number of GPUs to add per reserved VM.

    • ACCELERATOR_TYPE: the type of GPU to add to the reserved VMs.

    Make sure that the machine type you specify in the reservation supports the types of GPUs you specify and that the GPU is available in the zone where you want to reserve resources. Otherwise, creating the reservation fails.

  • To add one or more Local SSDs to each reserved VM, include one or more --local-ssd flags. You can specify up to 24 Local SSDs. Each Local SSD is 375 GB.

    For example, to specify two Local SSDs when creating a reservation, include two --local-ssd flags.

    gcloud compute reservations create my-reservation \
        --local-ssd=size=375,interface=INTERFACE_1 \
        --local-ssd=size=375,interface=INTERFACE_2 \
        ...
    

    Replace INTERFACE_1 and INTERFACE_2 with the type of interface you want each Local SSD to use. Specify one of the following values:

    • For NVME disk interfaces: nvme.

    • For SCSI disk interfaces: scsi.

    Make sure that the machine type you specify for the reserved VMs supports the chosen disk interfaces. Otherwise, creating the reservation fails. For more information, see how to choose a disk interface.

  • To have the reserved VMs use a specific minimum CPU platform instead of the zone's default CPU platform, include the --min-cpu-platform flag.

    gcloud compute reservations create my-reservation \
        --min-cpu-platform="MIN_CPU_PLATFORM" \
        ...
    

    Replace MIN_CPU_PLATFORM with a minimum CPU platform. To make sure that a CPU platform is available in the zone where you're reserving resources, view the available CPU platforms by zone.

  • To specify that only VMs that specifically target this reservation can consume it, include the --require-specific-reservation flag.

    gcloud compute reservations create example-reservation \
        --require-specific-reservation \
        ...
    
  • To enable Compute Engine to automatically delete the reservation, select one of the following methods:

    • To delete the reservation at a specific date and time, use the gcloud beta compute reservations create command and include the --delete-at-time flag.

      gcloud beta compute reservations create reservation-example \
          --delete-at-time=DELETE_AT_TIME \
          ...
      

      Replace DELETE_AT_TIME with a date and time formatted as an RFC 3339 timestamp, which must be as follows:

      YYYY-MM-DDTHH:MM:SSOFFSET
      

      Replace the following:

      • YYYY-MM-DD: a date formatted as a 4-digit year, 2-digit month, and a 2-digit day of the month, separated by hyphens (-).

      • HH:MM:SS: a time formatted as a 2-digit hour using a 24-hour time, 2-digit minutes, and 2-digit seconds, separated by colons (:).

      • OFFSET: the time zone formatted as an offset of Coordinated Universal Time (UTC). For example, to use the Pacific Standard Time (PST), specify -08:00. Alternatively, to use no offset, specify Z.

    • To delete the reservation after a specific duration, use the gcloud beta compute reservations create command and include the --delete-after-duration flag.

      gcloud beta compute reservations create reservation-example \
          --delete-after-duration=DELETE_AFTER_DURATION \
          ...
      

      Replace DELETE_AFTER_DURATION with a duration in days, hours, minutes, or seconds. For example, specify 30m for 30 minutes, or 1d2h3m4s for 1 day, 2 hours, 3 minutes, and 4 seconds.

Terraform

To create a reservation, use the google_compute_reservation Terraform resource. To specify a shared reservation, define the share_settings block:

  • Set the share_type field to SPECIFIC_PROJECTS.
  • In the project_map block, specify the project IDs of the projects that you want to share this reservation with.

For more information about how to use Terraform, see Using Terraform with Google Cloud.

REST

To create a shared reservation, make a POST request to the reservations.insert method.

For example, to create a shared reservation without any optional fields and share the reservation with two consumer projects, make the following POST request:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations

{
  "name": "RESERVATION_NAME",
  "shareSettings": {
    "shareType": "SPECIFIC_PROJECTS",
    "projectMap": {
      "CONSUMER_PROJECT_ID_1": {
        "projectId": "CONSUMER_PROJECT_ID_1"
      },
      "CONSUMER_PROJECT_ID_2": {
        "projectId": "CONSUMER_PROJECT_ID_2"
      }
    }
  },
  "specificReservation": {
    "count": "NUMBER_OF_VMS",
    "instanceProperties": {
      "machineType": "MACHINE_TYPE",
    }
  }
}

Replace the following:

  • PROJECT_ID: the ID of the project where you want to reserve resources.

  • ZONE: the zone in which to reserve resources.

  • RESERVATION_NAME: the name of the reservation to create.

  • CONSUMER_PROJECT_ID_1 and CONSUMER_PROJECT_ID_2: the IDs of projects that can consume this reservation. You can include up to 100 consumer projects. These projects must be in the same organization as the owner project. Don't include the owner project. By default, it is already allowed to consume the reservation.

  • NUMBER_OF_VMS: the number of VMs to reserve.

  • MACHINE_TYPE: a machine type to use for each VM. Specify one of the following values:

    • For a predefined machine type: MACHINE_FAMILY-standard-CPUS.

    • For a custom machine type: MACHINE_FAMILY-custom-CPUS-MEMORY. Before specifying a custom machine type, review the limitations for VMs with custom machine types.

    Replace the following:

    • MACHINE_FAMILY: the machine family.

    • CPUS: the number of vCPUs.

    • MEMORY: the total memory for a reserved VM. Memory must be a multiple of 256 MB and must be supplied in MB.

    For example, to specify an N2 custom machine type with 4 vCPUs and 5 GB of memory, which is 5,120 MB, specify n2-custom-4-5120.

For example, to create a reservation by specifying a global instance template in zone us-central1-a, share the reservation with projects project-1 and project-2, and reserve ten VMs that each use an N2 predefined machine type with 4 vCPUs, make the following POST request:

POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/reservations

{
  "name": "my-reservation",
  "shareSettings": {
    "shareType": "SPECIFIC_PROJECTS",
    "projectMap": {
      "project-1": {
        "projectId": "project-1"
      },
      "project-2": {
        "projectId": "project-2"
      }
    }
  },
  "specificReservation": {
    "count": "10",
    "instanceProperties": {
      "machineType": "n2-standard-4",
    }
  }
}

Optionally, you can do one or more of the following:

  • To add graphics processing units (GPUs) to each reserved VM, include the guestAccelerators field in the request body.

    POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/reservations
    
    {
      "name": "example-reservation",
      "specificReservation": {
        "instanceProperties": {
          "guestAccelerators": [
            {
              "acceleratorCount": NUMBER_OF_ACCELERATORS,
              "acceleratorType": "ACCELERATOR_TYPE"
            }
          ],
          ...
        },
        ...
      }
    }
    

    Replace the following:

    • NUMBER_OF_ACCELERATORS: the number of GPUs to add per reserved VM.

    • ACCELERATOR_TYPE: the type of GPU to add to the reserved VMs.

    Make sure that the machine type you specify in the reservation supports the types of GPUs you specify and that the GPU is available in the zone where you want to reserve resources. Otherwise, creating the reservation fails.

  • To add one or more Local SSDs to each reserved VM, include the localSsds field in the request body. You can specify up to 24 Local SSDs. Each Local SSD is 375 GB.

    For example, to specify two Local SSDs when creating a reservation, specify the following:

    POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/reservations
    
    {
      "name": "example-reservation",
      "specificReservation": {
        "instanceProperties": {
          "localSsds": [
            {
              "diskSizeGb": "375",
              "interface": "INTERFACE_1"
            },
            {
              "diskSizeGb": "375",
              "interface": "INTERFACE_2"
            }
          ],
          ...
        },
        ...
      }
    }
    

    Replace INTERFACE_1 and INTERFACE_2 with the type of interface you want each Local SSD to use. Specify one of the following values:

    • For NVME disk interfaces: NVME.

    • For SCSI disk interfaces: SCSI.

    Make sure that the machine type you specify for the reserved VMs supports the chosen disk interfaces. Otherwise, creating the reservation fails. For more information, see how to choose a disk interface.

  • To have the reserved VMs use a specific minimum CPU platform instead of the zone's default CPU platform, include the minCpuPlatform field in the request body.

    POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/reservations
    
    {
      "name": "example-reservation",
      "specificReservation": {
        "instanceProperties": {
          "minCpuPlatform": "MIN_CPU_PLATFORM",
          ...
        },
        ...
      }
    }
    

    Replace MIN_CPU_PLATFORM with a minimum CPU platform. To make sure that a CPU platform is available in the zone where you're reserving resources, view the available CPU platforms by zone.

  • To specify that only VMs that specifically target this reservation can consume it, include the specificReservationRequired field in the request body and set it to true.

    POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/reservations
    
    {
      "name": "example-reservation",
      "specificReservationRequired": true,
      ...
    }
    
  • To enable Compute Engine to automatically delete the reservation, select one of the following methods:

    • To delete the reservation at a specific date and time, make a POST request to the beta.reservations.insert method. In the request body, include the deleteAtTime field.

      POST https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/reservations
      
      {
        "name": "example-reservation",
        "deleteAtTime": "DELETE_AT_TIME",
        ...
      }
      

      Replace DELETE_AT_TIME with a date and time formatted as an RFC 3339 timestamp, which must be as follows:

      YYYY-MM-DDTHH:MM:SSOFFSET
      

      Replace the following:

      • YYYY-MM-DD: a date formatted as a 4-digit year, 2-digit month, and a 2-digit day of the month, separated by hyphens (-).

      • HH:MM:SS: a time formatted as a 2-digit hour using a 24-hour time, 2-digit minutes, and 2-digit seconds, separated by colons (:).

      • OFFSET: the time zone formatted as an offset of Coordinated Universal Time (UTC). For example, to use the Pacific Standard Time (PST), specify -08:00. Alternatively, to use no offset, specify Z.

    • To delete the reservation after a specific duration, make a POST request to the beta.reservations.insert method. In the request body, include the deleteAfterDuration field.

      POST https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/reservations
      
      {
        "name": "example-reservation",
        "deleteAfterDuration": {
          "seconds": "DELETE_AFTER_DURATION"
        },
        ...
      }
      

      Replace DELETE_AFTER_DURATION with a duration in seconds. For example, specify 86400 for 86,400 seconds (1 day).

Troubleshooting

Learn how to troubleshoot reservation creation.

What's next