Creating a shared reservation

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 for Compute Engine zonal resources.

If you want to create a reservation that can only be used by the project that creates it, see Creating reservations 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 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.
    • By limiting each shared reservation to only be shared with consumer projects that have the same billing account as the owner project, it is clearer for you to see if a reservation was consumed (and thus billed) or not.
    • If you have committed-use discounts for a billing account, limiting your shared reservations to that billing account helps 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 Cloud Console or gcloud tool.

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.

    rm policy.yaml
    

Editing the shared reservations organization policy constraint

To see which projects are allowed to create and modify shared reservations, use the Cloud Console or gcloud tool.

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 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 only lists 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 of the only 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.

      rm policy.yaml
      

Creating a shared reservation

Create a shared reservation for VM instances using the gcloud tool 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 instance can only consume a reservation if the instance's properties exactly match the reservation's instance properties:

  • Zone
  • Machine type (machine family, vCPUs, and memory)
  • Minimum CPU platform
  • GPU type
  • GPU count
  • Local SSD interface
  • Local SSD size

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 GPUs or local SSDs, you must create a reservation that includes those resources at the same time when purchasing your commitment. For more information, see Combining reservations with committed-use discounts.

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

gcloud

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

gcloud beta 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 this 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 beta 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 beta 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/beta/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",
    "projects": ["CONSUMER_PROJECT_ID_1", "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 this 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 surrounded by quotes in a comma-separated list, 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.

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/beta/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",
    "projects": ["project-1", "project-2"],
  }
  "specificReservationRequired": true
}

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

If this reservation does not consume instances as expected, see Ensuring utilization of reservations.

What's next