Create a shared reservation

Stay organized with collections Save and categorize content based on your preferences.

This document describes how to create shared reservations and manage which projects in your organization can create shared reservations.

Reservations provide a very high level of assurance in obtaining capacity for Compute Engine zonal resources. A shared reservation can be used by the project that created 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 instance 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. For more information, see Reservations of Compute Engine zonal resources.

If you want to create a reservation that can only be used by the project that creates it, see Create a reservation for a single project instead.

Before you begin

Best practices

The following best practices are recommended when creating shared reservations. By following them, you can help optimize the manageability and utilization of shared reservations in your organization as well as mitigate the limitations of some of the requirements of 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 under 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.
    • Projects are charged quota for both creation and consumption of the shared reservation, so limiting creation to a few projects can make it easier for you to manage your resource quotas.
    • For more information, see Allowing and restricting projects from creating and modifying shared reservations.
  • Minimize the number of separate shared reservations with identical instance properties.
    • An organization can have up to 100 shared reservations for each unique combination of instance properties. As a result, minimizing the number of shared reservations with identical instance properties that you create helps mitigate this limit.
    • Having fewer shared reservations improves manageability.
  • Only share reservations between projects with the same billing account.
    • Limit each shared reservation to only be shared with consumer projects that have the same 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 have committed-use discounts for a billing account, limit your shared reservations to that billing account to help maintain consistent billing across projects that create and consume shared reservations.

Allowing and restricting 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.

Viewing 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
      

Editing 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 a new line under for that project 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.

Creating a shared reservation

Create a shared reservation for VM instances using the gcloud CLI or Compute Engine API. The shared reservation can only be modified by the owner project, but the resources for a shared reservation can be consumed by the owner project or any consumer projects.

A VM can only consume a reservation if all the following properties for both the VM and reservation are exactly matching:

  • Project
  • Zone
  • Machine type
  • Minimum CPU platform
  • GPU type and count
  • Local SSD type and count

By default, a shared reservation is automatically consumed by any matching VM instances that are created in the owner project or a consumer project. To create a reservation that isn't consumed automatically, use the specificReservationRequired option when creating the reservation or create an instance without consuming a reservation.

You don't need to create a commitment in order to reserve resources. However, if you want committed use discount pricing on your reserved resources, you must create and attach the reservation to a commitment at the time of purchasing the commitment. Consequently, your shared reservation can either be a standalone shared reservation or a shared reservation that is attached to a commitment.

For more information about how to purchase a commitment with an attached reservation, see Combining reservations with committed-use discounts.

To create a shared reservation, use the gcloud CLI or Compute Engine API.

Console

  1. In the Google Cloud console, select the owner project where you want to create the shared reservation and go to the Committed use discounts page.

    Go to Committed use discounts

  2. Click Create reservation.

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

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

  5. To specify that your reservation is a shared reservation, select Shared as the Share type

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

  7. In the Use with VM instance field, select one of the following options:

    • To use this shared reservation's resources only when creating matching VM instances that specifically target this reservation by name, select Select specific reservation.
    • To allow matching VM instances to automatically use this reservation, select Use reservation automatically.

    For this example, select Select specific reservation.

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

  9. Specify the resources that you want to reserve for each VM instance:

    • If you want to reserve VMs that match an existing instance template, select Use instance template and select an instance template from the list.
    • Otherwise, select Specify machine type and specify the following:
      1. In the Machine family, Series, and Machine type fields, select a machine family, series, and machine type.
      2. Optional: Specify a minimum CPU platform and/or GPUs:
        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: Add local SSDs:
        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.
  10. To create the shared reservation, click Create.

gcloud

Use the gcloud compute reservations create command with the --share-setting=projects and --share-with flags:

gcloud compute reservations create RESERVATION_NAME \
    --machine-type=MACHINE_TYPE \
    --min-cpu-platform=MINIMUM_CPU_PLATFORM \
    --vm-count=NUMBER_OF_VMS \
    --accelerator=count=NUMBER_OF_ACCELERATORS,type=ACCELERATOR_TYPE \
    --local-ssd=size=375,interface=INTERFACE_1 \
    --local-ssd=size=375,interface=INTERFACE_2 \
    --zone=ZONE \
    --project=OWNER_PROJECT_ID \
    --share-setting=projects \
    --share-with=CONSUMER_PROJECT_IDS
    

Replace the following:

  • RESERVATION_NAME: the name of the reservation to create.
  • MACHINE_TYPE: a predefined or custom machine type.

    • For predefined machine types, use the format MACHINE_FAMILY-standard-CPUS; for example, n2-standard-4.
    • For custom machine types, use the format MACHINE_FAMILY-custom-CPUS-MEMORY; for example n2-custom-4-5120. For a full list of restrictions, read the specifications for custom machine types.

    Replace the following:

    • MACHINE_FAMILY: the family of machine types; for example, specify n2 for N2 VMs.
    • CPUS: the number of vCPUs.
    • MEMORY: the total memory for a reserved instance. Memory must be a multiple of 256 MB and must be supplied in MB; for example, to create an N2 VM with 4 vCPUs and 5 GB of memory, which is 5120 MB, use n2-custom-4-5120.
  • MINIMUM_CPU_PLATFORM: the minimum CPU to use for each instance.

  • NUMBER_OF_VMS: the quantity of VM instances to reserve.

  • NUMBER_OF_ACCELERATORS: the number of GPUs to add, per instance.

  • ACCELERATOR_TYPE: the type of accelerator.

  • INTERFACE_1 and INTERFACE_2: the type of interface you want the local SSDs for each instance to use. Valid options are: scsi and nvme. Each local SSD is 375 GB. Repeat the --local-ssd flag for each local SSD that you want to add, up to 24 local SSDs per instance.

  • ZONE: the zone in which to reserve resources.

  • OWNER_PROJECT_ID: Optional: The project ID of the project that you want to create this shared reservation. If you omit the --project flag, the current project is used as the owner project by default.

  • CONSUMER_PROJECT_IDS: a comma-separated list of the project IDs of projects that you want to share this reservation with, for example project-1,project-2. You can include 1 to 100 consumer projects. These projects must be in the same organization as the owner project. Do not include the OWNER_PROJECT_ID, which is already allowed to consume this reservation by default.

You must include the --share-setting=projects flag to share this reservation with other projects.

Optionally, add the --require-specific-reservation flag to indicate that only VM instances that explicitly target this reservation can use it.

For example, to make a shared reservation in us-central1-a that can only be used when this reservation is specifically targeted, use a command similar to the following. This example reserves 10 custom machines, each with 8 Intel Haswell (or more recent) vCPUs, 10 GB of memory, 2 V100 GPUs, and 375 GB local SSD. The example shared reservation is created in the project my-owner-project and can be consumed by my-owner-project, project-1, or project-2.

gcloud compute reservations create my-reservation \
    --machine-type=custom-8-10240 \
    --min-cpu-platform="Intel Haswell" \
    --vm-count=10 \
    --accelerator=count=2,type=nvidia-tesla-v100 \
    --local-ssd=size=375,interface=scsi \
    --zone=us-central1-c \
    --project=my-owner-project \
    --share-setting=projects \
    --share-with=project-1,project-2 \
    --require-specific-reservation
 

API

Construct a POST request to the reservations.insert method and include the shareSetting field. Set the "shareType" field to "SPECIFIC_PROJECTS" and the "projects" field to a comma-separated list of project IDs.

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

{
  "name": "RESERVATION_NAME",
  "specificReservation": {
    "count": "NUMBER_OF_VMS",
    "instanceProperties": {
      "machineType": "MACHINE_TYPE",
      "minCpuPlatform": "MINIMUM_CPU_PLATFORM",
      "guestAccelerators": [
        {
          "acceleratorCount": "NUMBER_OF_ACCELERATORS",
          "acceleratorType": "ACCELERATOR_TYPE"
        }
      ],
      "localSsds": [
        {
          "diskSizeGb": "375",
          "interface": "INTERFACE_1"
        },
        {
          "diskSizeGb": "375",
          "interface": "INTERFACE_2"
        }
      ]
    }
  },
  "shareSettings": {
    "shareType": "SPECIFIC_PROJECTS",
    "projectMap": {
      "CONSUMER_PROJECT_ID_1": {
        "projectId": "CONSUMER_PROJECT_ID_1"
      },
      "CONSUMER_PROJECT_ID_2": {
        "projectId": "CONSUMER_PROJECT_ID_2"
      }
    }
  }
}

Replace the following:

  • OWNER_PROJECT_ID: The project ID of the project that you want to be the owner project and create this reservation.
  • ZONE: the zone in which to reserve resources.
  • RESERVATION_NAME: the name of the reservation to create.
  • NUMBER_OF_VMS: the quantity of VM instances to reserve.
  • MACHINE_TYPE: a predefined or custom machine type.

    • For predefined machine types, use the format MACHINE_FAMILY-standard-CPUS; for example, n2-standard-4.
    • For custom machine types, use the format MACHINE_FAMILY-custom-CPUS-MEMORY; for example n2-custom-4-5120. For a full list of restrictions, read the specifications for custom machine types.

    Replace the following:

    • MACHINE_FAMILY: the family of machine types; for example, specify n2 for N2 VMs.
    • CPUS: the number of vCPUs.
    • MEMORY: the total memory for a reserved instance. Memory must be a multiple of 256 MB and must be supplied in MB; for example, to create an N2 VM with 4 vCPUs and 5 GB of memory, which is 5120 MB, use n2-custom-4-5120.
  • MINIMUM_CPU_PLATFORM: the minimum CPU to use for each instance.

  • NUMBER_OF_ACCELERATORS: the number of GPUs to add, per instance.

  • ACCELERATOR_TYPE: the type of accelerator.

  • INTERFACE_1 and INTERFACE_2: the type of interface you want the local SSDs for each instance to use. Valid options are: scsi and nvme. Each local SSD is 375 GB. Repeat the localSsds.diskSizeGb and localSsds.interface fields for each local SSD that you want to add, up to 24 local SSDs per instance.

  • CONSUMER_PROJECT_ID_1 and CONSUMER_PROJECT_ID_2: the project IDs of projects that you want to share this reservation with. You can include 1 to 100 consumer projects. These projects must be in the same organization as the owner project. Do not include the OWNER_PROJECT_ID, which is already allowed to consume this reservation by default.

Optionally add the "specificReservationRequired": true field, as shown in the following example, to indicate that only VM instances that explicitly target this reservation can use it.

For example, to make a shared reservation in us-central1-a that can only be used when this reservation is specifically targeted, use a command similar to the following. This example reserves 10 custom machines, each with 8, Intel Haswell (or more recent) vCPUs, 10 GB of memory, 2 V100 GPUs, and a 375 GB local SSD: The example shared reservation is created by the project my-owner-project and can be consumed by my-owner-project, project-1, or project-2.

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

{
  "name": "reservation-1",
  "specificReservation":
  {
    "count": "10",
    "instanceProperties":
    {
      "machineType": "custom-8-10240",
      "minCpuPlatform": "Intel Haswell",
      "guestAccelerators":
      [
        {
          "acceleratorCount": 2,
          "acceleratorType": "nvidia-tesla-v100"
        }
      ],
      "localSsds":
      [
        {
          "diskSizeGb": "375",
          "interface": "SCSI"
        }
      ]
    }
  },
  "shareSettings": {
    "shareType": "SPECIFIC_PROJECTS",
    "projectMap": {
      "project-1": {
        "projectId": "project-1"
      },
      "project-2": {
        "projectId": "project-2"
      }
    }
  }
  "specificReservationRequired": true
}

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.

To see your created reservation—for example, to check if it has been automatically consumed any instances—describe the reservation.

Troubleshooting

Learn how to troubleshoot reservation creation.

What's next