Create a shared reservation

This document explains how to create shared reservations, which are reservationsshared across multiple projects, and manage which projects in your organizationcan 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 (consumerprojects). Use shared reservations if your organization has multiple projectsthat need virtual machine (VM) instances with the same properties reserved.By using shared reservations, you can improve the utilization of yourreservations and reduce the number of reservations that you need to create andmanage. To learn more about reservations, seeReservations of Compute Engine zonal resources.

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

Note: After you create a reservation, it incurs charges for its reservedresources, even when it's not being consumed, until you delete it. For moreinformation, seeBilling.

Before you begin

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, seeManage access to projects, folders, and organizations.

These predefined roles contain the permissions required to create shared reservations. To see the exact permissions that are required, expand theRequired 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 withcustom roles or otherpredefined roles.

Create a shared reservation

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

To consume a reservation, a VM must haveproperties thatexactly matchthat 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 aninstance template to define theproperties of a shared reservation. By using an instance template, you candefine the properties of a reservation and the VMs that can consume thereservation in the same place. However, because templates areproject-specific, you can't use the same template to create VMs that canconsume the reservation outside of the project that created the reservation.For the projects the reservation is shared with, you must create similartemplates in those projects or create VMs by specifying properties directly.

  • Specify an existing VM

    This section explains how to use an existing VM to define the properties ofa reservation. By using the properties of an existing VM, you can consumethe reservation by creating VMs with properties that match the reference VM.

  • Specify properties directly

    This section explains how to directly define the properties of a sharedreservation. This method requires you to manually ensure that the propertiesof your VMs and reservations matchexactly—anymismatched properties prevent consumption.

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

Specify an instance template

Before creating a reservation by specifying an instance template, make sure ofthe following:

  • An instance template contains project-specific settings, so you can onlyaccess and use an instance template within the same project. If you create ashared reservation by specifying an instance template, then you can't usethe same template to create VMs that can consume the reservation outside ofthe project that created the reservation.

  • Create your reservation in the same region and zone as the resourceswithin the instance template. Anyregionalorzonal resourcesspecified in an instance template—such as a machine type or aPersistent Disk volume—restrict the use of the template to the locationswhere those resources exist. For example, if your instance templatespecifies an existing Persistent Disk volume in zoneus-central1-a, thenyou can only create your reservation in the same zone. To check if anexisting template specifies any resources that bind the template to aspecific region or zone,view the details of the instance templateand look for references to regional or zonal resources inside of it.

To create a shared reservation by specifying an instance template, select oneof the following options:

Console

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

    Go to Reservations

  2. ClickCreate reservation. TheCreate a reservation page appears.

  3. In theName field, enter a name for your reservation.

  4. In theRegion andZone lists, select where you want to reserveresources.

  5. In theShare type section, do the following:

    1. To share a reservation with other projects, selectShared.

    2. ClickAdd projects, andthen select the projects from the current project's organizationthat you want to share the reservation with. You can select up to100 consumer projects.

  6. Optional: To letcustom training jobs orprediction jobs inVertex AI consume a reservation of GPU VMs, in theGoogle Cloud services section, selectShare reservation.

  7. In theUse with VM instance section, select one of the followingoptions:

    • To allow matching VMs to automatically consume this reservation,selectUse reservation automatically.

    • To consume this reservation's resources only when you creatematching VMs that specifically target the reservation by name,selectSelect specific reservation.

  8. In theResource details section, do the following:

    • In theNumber of VM instances field, enter the number of VMsthat you want to reserve.

    • To specify VM configurations by using an instance template, selectUse instance template, and then, in the list that appears,select the instance template.

  9. In theAuto-delete section, you can enable the auto-delete option tolet Compute Engine automatically delete the reservation at aspecific date and time. Automatically deleting reservations can beuseful to avoid unnecessary charges when you stop consuming thereservation.

  10. To create the reservation, clickCreate. TheReservations pageappears. Creating the reservation can take up to a minute to complete.To verify when Compute Engine finishes creating it,view your reservations.

gcloud

To create a shared reservation, use thegcloud compute reservations create commandwith the--share-setting=projects and--share-with flags.

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

gcloud compute reservations createRESERVATION_NAME \    --share-setting=projects \    --share-with=CONSUMER_PROJECT_IDS \    --source-instance-template=INSTANCE_TEMPLATE_URL \    --vm-count=NUMBER_OF_VMS \    --zone=ZONE

Replace the following:

  • RESERVATION_NAME: the name of the reservation tocreate.

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

  • CONSUMER_PROJECT_IDS: a comma-separated list ofIDs of projectsthat 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's already allowed toconsume the reservation.

  • INSTANCE_TEMPLATE_URL: the URL of an existinginstance template, which must exist in your project. Specify one of thefollowing values:

    • For a regional instance template:projects/PROJECT_ID/regions/REGION/instanceTemplates/INSTANCE_TEMPLATE_NAME

    • For a global instance template:INSTANCE_TEMPLATE_NAME

  • 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 instancetemplate in zoneus-central1-a, share the reservation with projectsproject-1 andproject-2, and reserve ten VMs that each use an N2predefined machine type with 4 vCPUs, run the following command:

gcloud compute reservations create my-reservation \    --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 canconsume it, include the--require-specific-reservationflag.

    gcloud compute reservations createRESERVATION_NAME \--require-specific-reservation \    --share-setting=projects \    --share-with=CONSUMER_PROJECT_IDS \    --source-instance-template=INSTANCE_TEMPLATE_URL \    --vm-count=NUMBER_OF_VMS \    --zone=ZONE

  • To letcustom training jobsorprediction jobs inVertex AI consume a reservation of GPU VMs, include the--reservation-sharing-policyflag set toALLOW_ALL.

    gcloud compute reservations createRESERVATION_NAME \--reservation-sharing-policy=ALLOW_ALL \    --share-setting=projects \    --share-with=CONSUMER_PROJECT_IDS \    --source-instance-template=INSTANCE_TEMPLATE_URL \    --vm-count=NUMBER_OF_VMS \    --zone=ZONE

  • To enable Compute Engine toautomatically delete the reservation,select one of the following methods:

    Preview — The--delete-at-time and--delete-after-duration flags

    This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

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

      gcloud beta compute reservations createRESERVATION_NAME \--delete-at-time=DELETE_AT_TIME \    --share-setting=projects \    --share-with=CONSUMER_PROJECT_IDS \    --source-instance-template=INSTANCE_TEMPLATE_URL \    --vm-count=NUMBER_OF_VMS \    --zone=ZONE

      ReplaceDELETE_AT_TIME with a date and timeformatted as anRFC 3339 timestamp, whichmust be as follows:

      YYYY-MM-DDTHH:MM:SSOFFSET

      Replace the following:

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

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

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

    • To delete the reservation after a specific duration, use thegcloud beta compute reservations create commandwith the--delete-after-duration flag.

      gcloud beta compute reservations createRESERVATION_NAME \--delete-after-duration=DELETE_AFTER_DURATION \    --share-setting=projects \    --share-with=CONSUMER_PROJECT_IDS \    --source-instance-template=INSTANCE_TEMPLATE_URL \    --vm-count=NUMBER_OF_VMS \    --zone=ZONE

      ReplaceDELETE_AFTER_DURATION with a duration indays, hours, minutes, or seconds. For example, specify30m for 30minutes, or1d2h3m4s for 1 day, 2 hours, 3 minutes, and 4 seconds.

Go

import("context""fmt""io"computepb"cloud.google.com/go/compute/apiv1/computepb""google.golang.org/protobuf/proto")// Creates shared reservation from given template in particular zonefunccreateSharedReservation(wio.Writer,clientClientInterface,projectID,baseProjectId,zone,reservationName,sourceTemplatestring)error{// client, err := compute.NewReservationsRESTClient(ctx)// projectID := "your_project_id". Destination of sharing.// baseProjectId := "your_project_id2". Project where the reservation will be created.// zone := "us-west3-a"// reservationName := "your_reservation_name"// sourceTemplate: existing template path. Following formats are allowed://  - projects/{project_id}/global/instanceTemplates/{template_name}//  - projects/{project_id}/regions/{region}/instanceTemplates/{template_name}//  - https://www.googleapis.com/compute/v1/projects/{project_id}/global/instanceTemplates/instanceTemplate//  - https://www.googleapis.com/compute/v1/projects/{project_id}/regions/{region}/instanceTemplates/instanceTemplatectx:=context.Background()shareSettings:=map[string]*computepb.ShareSettingsProjectConfig{projectID:{ProjectId:proto.String(projectID)},}req:=&computepb.InsertReservationRequest{Project:baseProjectId,ReservationResource:&computepb.Reservation{Name:proto.String(reservationName),Zone:proto.String(zone),SpecificReservation:&computepb.AllocationSpecificSKUReservation{Count:proto.Int64(2),SourceInstanceTemplate:proto.String(sourceTemplate),},ShareSettings:&computepb.ShareSettings{ProjectMap:shareSettings,ShareType:proto.String("SPECIFIC_PROJECTS"),},},Zone:zone,}op,err:=client.Insert(ctx,req)iferr!=nil{returnfmt.Errorf("unable to create reservation: %w",err)}ifop!=nil{iferr=op.Wait(ctx);err!=nil{returnfmt.Errorf("unable to wait for the operation: %w",err)}}fmt.Fprintf(w,"Reservation created\n")returnnil}

Java

importcom.google.cloud.compute.v1.AllocationSpecificSKUReservation;importcom.google.cloud.compute.v1.InsertReservationRequest;importcom.google.cloud.compute.v1.Operation;importcom.google.cloud.compute.v1.Operation.Status;importcom.google.cloud.compute.v1.Reservation;importcom.google.cloud.compute.v1.ReservationsClient;importcom.google.cloud.compute.v1.ShareSettings;importcom.google.cloud.compute.v1.ShareSettingsProjectConfig;importjava.io.IOException;importjava.util.concurrent.ExecutionException;importjava.util.concurrent.TimeUnit;importjava.util.concurrent.TimeoutException;publicclassCreateSharedReservation{publicstaticvoidmain(String[]args)throwsIOException,ExecutionException,InterruptedException,TimeoutException{// TODO(developer): Replace these variables before running the sample.// The ID of the project where you want to reserve resources// and where the instance template exists.// 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 visit this page:// https://cloud.google.com/compute/docs/instances/reservations-shared#shared_reservation_constraintStringprojectId="YOUR_PROJECT_ID";// Zone in which to reserve resources.Stringzone="us-central1-a";// Name of the reservation to be created.StringreservationName="YOUR_RESERVATION_NAME";// The URI of the global instance template to be used for creating the reservation.StringinstanceTemplateUri=String.format("projects/%s/global/instanceTemplates/%s",projectId,"YOUR_INSTANCE_TEMPLATE_NAME");// Number of instances for which capacity needs to be reserved.intvmCount=3;createSharedReservation(projectId,zone,reservationName,instanceTemplateUri,vmCount);}// Creates a shared reservation with the given name in the given zone.publicstaticStatuscreateSharedReservation(StringprojectId,Stringzone,StringreservationName,StringinstanceTemplateUri,intvmCount)throwsExecutionException,InterruptedException,TimeoutException,IOException{// Initialize client that will be used to send requests. This client only needs to be created// once, and can be reused for multiple requests.try(ReservationsClientreservationsClient=ReservationsClient.create()){ShareSettingsshareSettings=ShareSettings.newBuilder().setShareType(String.valueOf(ShareSettings.ShareType.SPECIFIC_PROJECTS))// 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..putProjectMap("CONSUMER_PROJECT_1",ShareSettingsProjectConfig.newBuilder().build()).putProjectMap("CONSUMER_PROJECT_2",ShareSettingsProjectConfig.newBuilder().build()).build();ReservationreservationResource=Reservation.newBuilder().setName(reservationName).setZone(zone).setSpecificReservationRequired(true).setShareSettings(shareSettings).setSpecificReservation(AllocationSpecificSKUReservation.newBuilder().setCount(vmCount).setSourceInstanceTemplate(instanceTemplateUri).build()).build();InsertReservationRequestrequest=InsertReservationRequest.newBuilder().setProject(projectId).setZone(zone).setReservationResource(reservationResource).build();Operationresponse=reservationsClient.insertAsync(request).get(3,TimeUnit.MINUTES);if(response.hasError()){thrownewError("Reservation creation failed!!"+response);}returnresponse.getStatus();}}}

Node.js

// Import the Compute libraryconstcomputeLib=require('@google-cloud/compute');constcompute=computeLib.protos.google.cloud.compute.v1;/** * TODO(developer): Uncomment reservationsClient and zoneOperationsClient before running the sample. */// Instantiate a reservationsClient// reservationsClient = new computeLib.ReservationsClient();// Instantiate a zoneOperationsClient// zoneOperationsClient = new computeLib.ZoneOperationsClient();/** * TODO(developer): Update these variables before running the sample. */// The ID of the project where you want to reserve resources and where the instance template exists.constprojectId=awaitreservationsClient.getProjectId();// The zone in which to reserve resources.constzone='us-central1-a';// The name of the reservation to create.constreservationName='reservation-01';// The number of VMs to reserve.constvmsNumber=3;// The name of an existing instance template.constinstanceTemplateName='global-instance-template-name';// The location of the instance template.constlocation='global';asyncfunctioncallCreateComputeSharedReservation(){// Create reservation for 3 VMs in zone us-central1-a by specifying a instance template.constspecificReservation=newcompute.AllocationSpecificSKUReservation({count:vmsNumber,sourceInstanceTemplate:`projects/${projectId}/${location}/instanceTemplates/${instanceTemplateName}`,});// Create share settings. Share reservation with one customer project.constshareSettings=newcompute.ShareSettings({shareType:'SPECIFIC_PROJECTS',projectMap:{// 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.consumer_project_id:{projectId:'consumer_project_id',},},});// Create a reservation.constreservation=newcompute.Reservation({name:reservationName,specificReservation,specificReservationRequired:true,shareSettings,});const[response]=awaitreservationsClient.insert({project:projectId,reservationResource:reservation,zone,});letoperation=response.latestResponse;// Wait for the create reservation operation to complete.while(operation.status!=='DONE'){[operation]=awaitzoneOperationsClient.wait({operation:operation.name,project:projectId,zone:operation.zone.split('/').pop(),});}console.log(`Reservation:${reservationName} created.`);returnresponse;}returnawaitcallCreateComputeSharedReservation();

Python

from__future__importannotationsimportsysfromtypingimportAnyfromgoogle.api_core.extended_operationimportExtendedOperationfromgoogle.cloudimportcompute_v1defwait_for_extended_operation(operation:ExtendedOperation,verbose_name:str="operation",timeout:int=300)->Any:"""    Waits for the extended (long-running) operation to complete.    If the operation is successful, it will return its result.    If the operation ends with an error, an exception will be raised.    If there were any warnings during the execution of the operation    they will be printed to sys.stderr.    Args:        operation: a long-running operation you want to wait on.        verbose_name: (optional) a more verbose name of the operation,            used only during error and warning reporting.        timeout: how long (in seconds) to wait for operation to finish.            If None, wait indefinitely.    Returns:        Whatever the operation.result() returns.    Raises:        This method will raise the exception received from `operation.exception()`        or RuntimeError if there is no exception set, but there is an `error_code`        set for the `operation`.        In case of an operation taking longer than `timeout` seconds to complete,        a `concurrent.futures.TimeoutError` will be raised.    """result=operation.result(timeout=timeout)ifoperation.error_code:print(f"Error during{verbose_name}: [Code:{operation.error_code}]:{operation.error_message}",file=sys.stderr,flush=True,)print(f"Operation ID:{operation.name}",file=sys.stderr,flush=True)raiseoperation.exception()orRuntimeError(operation.error_message)ifoperation.warnings:print(f"Warnings during{verbose_name}:\n",file=sys.stderr,flush=True)forwarninginoperation.warnings:print(f" -{warning.code}:{warning.message}",file=sys.stderr,flush=True)returnresultdefcreate_compute_shared_reservation(project_id:str,zone:str="us-central1-a",reservation_name="your-reservation-name",shared_project_id:str="shared-project-id",)->compute_v1.Reservation:"""Creates a compute reservation in GCP.    Args:        project_id (str): The ID of the Google Cloud project.        zone (str): The zone to create the reservation.        reservation_name (str): The name of the reservation to create.        shared_project_id (str): The ID of the project that the reservation is shared with.    Returns:        Reservation object that represents the new reservation.    """instance_properties=compute_v1.AllocationSpecificSKUAllocationReservedInstanceProperties(machine_type="n1-standard-1",# Optional. Specifies amount of local ssd to reserve with each instance.local_ssds=[compute_v1.AllocationSpecificSKUAllocationAllocatedInstancePropertiesReservedDisk(disk_size_gb=375,interface="NVME"),],)reservation=compute_v1.Reservation(name=reservation_name,specific_reservation=compute_v1.AllocationSpecificSKUReservation(count=3,# Number of resources that are allocated.# If you use source_instance_template, you must exclude the instance_properties field.# It can be a full or partial URL.# source_instance_template="projects/[PROJECT_ID]/global/instanceTemplates/my-instance-template",instance_properties=instance_properties,),share_settings=compute_v1.ShareSettings(share_type="SPECIFIC_PROJECTS",project_map={shared_project_id:compute_v1.ShareSettingsProjectConfig(project_id=shared_project_id)},),)# Create a clientclient=compute_v1.ReservationsClient()operation=client.insert(project=project_id,zone=zone,reservation_resource=reservation,)wait_for_extended_operation(operation,"Reservation creation")reservation=client.get(project=project_id,zone=zone,reservation=reservation_name)shared_project=next(iter(reservation.share_settings.project_map.values()))print("Name: ",reservation.name)print("STATUS: ",reservation.status)print("SHARED PROJECT: ",shared_project)# Example response:# Name:  your-reservation-name# STATUS:  READY# SHARED PROJECT:  project_id: "123456789012"returnreservation

REST

To create a shared reservation, make aPOST request to thereservations.insert method.In the request body, include the following:

  • TheprojectMap field.

  • TheshareType field set toSPECIFIC_PROJECTS.

For example, to create a shared reservation by specifying an instancetemplate without including any optional fields, and share the reservationwith two consumer projects, make the followingPOST 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": "INSTANCE_TEMPLATE_URL"  }}

Replace the following:

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

  • ZONE: the zone in which to reserve resources.

  • RESERVATION_NAME: the name of the reservation tocreate.

  • CONSUMER_PROJECT_ID_1 andCONSUMER_PROJECT_ID_2: theIDs of projectsthat can consume this reservation. You can include up to 100 consumerprojects. These projects must be in the same organization as the ownerproject. Don't include the owner project. By default, it is alreadyallowed to consume the reservation.

  • NUMBER_OF_VMS: the number of VMs to reserve.

  • INSTANCE_TEMPLATE_URL: the URL of an existinginstance template, which must exist in your project. Specify one of thefollowing values:

    • For a regional instance template:projects/PROJECT_ID/regions/REGION/instanceTemplates/INSTANCE_TEMPLATE_NAME

    • For a global instance template:INSTANCE_TEMPLATE_NAME

For example, to create a reservation for ten VMs in zoneus-central1-a byspecifying a global instance template, and share the reservation withprojectsproject-1 andproject-2, make the followingPOST 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": "example-instance-template"  }}

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

  • To specify that only VMs that specifically target this reservation canconsume it, include thespecificReservationRequired field in therequest body, and set the field totrue.

    For example, to create a specific reservation by specifying an instancetemplate, and share the reservation with two consumer projects, make arequest as follows:

    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": "INSTANCE_TEMPLATE_URL"  },"specificReservationRequired": true}

  • To letcustom training jobsorprediction jobs inVertex AI consume a reservation of GPU VMs, include theserviceShareType field and set it toALLOW_ALL.

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations{  "name": "RESERVATION_NAME","reservationSharingPolicy": {    "serviceShareType": "ALLOW_ALL"  },  "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": "INSTANCE_TEMPLATE_URL"  }}

  • To enable Compute Engine toautomatically delete the reservation,select one of the following methods:

    Preview — ThedeleteAtTime anddeleteAfterDuration fields

    This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

    • To delete the reservation at a specific date and time, make aPOSTrequest to thebeta.reservations.insert method.In the request body, include thedeleteAtTime field.

      For example, to create a reservation by specifying an instancetemplate, auto delete the reservation at a specific date and time,and share the reservation with two consumer projects, make a requestas follows:

      POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/reservations{"deleteAtTime": "DELETE_AT_TIME",  "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": "INSTANCE_TEMPLATE_URL"  }}

      ReplaceDELETE_AT_TIME with a date and timeformatted as anRFC 3339 timestamp, whichmust be as follows:

      YYYY-MM-DDTHH:MM:SSOFFSET

      Replace the following:

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

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

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

    • To delete the reservation after a specific duration, make aPOSTrequest to thebeta.reservations.insert method.In the request body, include thedeleteAfterDuration field.

      For example, to create a reservation by specifying an instancetemplate, auto delete the reservation after a specific duration, andshare the reservation with two consumer projects, make a request asfollows:

      POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/reservations{"deleteAfterDuration": {    "seconds": "DELETE_AFTER_DURATION"  },  "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": "INSTANCE_TEMPLATE_URL"  }}

      ReplaceDELETE_AFTER_DURATION with a duration inseconds. For example, specify86400 for 86,400 seconds (1 day).

Specify an existing VM

You can only create a shared reservation based on an existing VM in the sameproject and zone as the VM.

After creating the reservation, you can consume it by creating VMs withproperties that match the reference VM. You can do this by doing one of thefollowing:

To create a shared reservation that uses the properties of an existing VM, dothe following:

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

    Go to Reservations

  2. ClickCreate reservation. TheCreate a reservation page appears.

  3. In theName field, enter a name for your reservation.

  4. In theRegion andZone lists, select where you want to reserveresources.

  5. In theShare type section, do the following:

    1. To share a reservation with other projects, selectShared.

    2. ClickAdd projects, and thenselect the projects from the current project's organization that youwant to share the reservation with. You can select up to 100 consumerprojects.

  6. Optional: To letcustom training jobs orprediction jobs inVertex AI consume a reservation of GPU VMs, in theGoogle Cloud services section, selectShare reservation.

  7. In theUse with VM instance section, select one of the followingoptions:

    • To allow matching VMs to automatically consume this reservation, selectUse reservation automatically.

    • To consume this reservation's resources only when you create matchingVMs that specifically target the reservation by name, selectSelect specific reservation.

  8. In theResource details section, do the following:

    • In theNumber of VM instances field, enter the number of VMs thatyou want to reserve.

    • To specify VM configurations by using a reference VM, selectUse existing VM, and then, in the list that appears, select the VM.

  9. In theAuto-delete section, you can enable the auto-delete option to letCompute Engine automatically delete the reservation at a specificdate and time. Automatically deleting reservations can be useful to avoidunnecessary charges when you stop consuming the reservation.

  10. To create the reservation, clickCreate. TheReservations pageappears. Creating the reservation can take up to a minute to complete. Toverify when Compute Engine finishes creating it,view your reservations.

Specify properties directly

To create a shared reservation by specifying properties directly, select one ofthe following options:

Console

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

    Go to Reservations

  2. ClickCreate reservation. TheCreate a reservation page appears.

  3. In theName field, enter a name for your reservation.

  4. In theRegion andZone lists, select where you want to reserveresources.

  5. In theShare type section, do the following:

    1. To share a reservation with other projects, selectShared.

    2. ClickAdd projects, andthen select the projects from the current project's organizationthat you want to share the reservation with. You can select up to100 consumer projects.

  6. Optional: To letcustom training jobs orprediction jobs inVertex AI consume a reservation of GPU VMs, in theGoogle Cloud services section, selectShare reservation.

  7. In theUse with VM instance section, select one of the followingoptions:

    • To allow matching VMs to automatically consume this reservation,selectUse reservation automatically.

    • To consume this reservation's resources only when you creatematching VMs that specifically target the reservation by name,selectSelect specific reservation.

  8. In theResource details section, do the following:

    • In theNumber of VM instances field, enter the number of VMsthat you want to reserve.

    • Specify the machine series and type that you want to reserve.

  9. In theAuto-delete section, you can enable the auto-delete optionto let Compute Engine automatically delete the reservation ata specific date and time. Automatically deleting reservations can beuseful to avoid unnecessary charges when you stop consuming thereservation.

  10. To create the reservation, clickCreate. TheReservations pageappears. Creating the reservation can take up to a minute to complete.To verify when Compute Engine finishes creating it,view your reservations.

gcloud

To create a shared reservation, use thegcloud compute reservations create commandwith the--share-setting=projects and--share-with flags.

To create a shared reservation by specifying properties directly and withoutincluding any optional flags, run the following command:

gcloud compute reservations createRESERVATION_NAME \    --machine-type=MACHINE_TYPE \    --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 tocreate.

  • MACHINE_TYPE: a machine type to use for each VM.

  • CONSUMER_PROJECT_IDS: a comma-separated list ofIDs of projectsthat 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 toconsume 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 in zoneus-central1-a for ten VMsthat each use an N2 predefined machine type with 4 vCPUs, and share thereservation with projectsproject-1 andproject-2, run the followingcommand:

gcloud compute reservations create my-reservation \    --machine-type=n2-standard-4 \    --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 attach GPUs to your reserved N1 VMs, include the--acceleratorflag.

    gcloud compute reservations createRESERVATION_NAME \--accelerator=count=NUMBER_OF_ACCELERATORS,type=ACCELERATOR_TYPE    --machine-type=MACHINE_TYPE \    --share-setting=projects \    --share-with=CONSUMER_PROJECT_IDS \    --vm-count=NUMBER_OF_VMS \    --zone=ZONE

    Replace the following:

  • To attach Local SSD disks to amachine type that doesn't include Local SSD disks by default,include the--local-ssd flag. You can only attach Local SSD disks of375 GB.

    gcloud compute reservations createRESERVATION_NAME \--local-ssd=count=NUMBER_OF_LOCAL_SSD_DISKS,size=375,interface=INTERFACE_TYPE \    --machine-type=MACHINE_TYPE \    --vm-count=NUMBER_OF_VMS \    --zone=ZONE

    Replace the following:

    • NUMBER_OF_LOCAL_SSD_DISKS: the number of LocalSSD disks to attach.

    • INTERFACE_TYPE: the type of disk interface thatyou want each Local SSD disk to use and thatyour specified machine type supports.Specify one of the following values:

      • For the NVME disk interface:nvme

      • For the SCSI disk interface:scsi

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

    gcloud compute reservations createRESERVATION_NAME \    --machine-type=MACHINE_TYPE \--min-cpu-platform="MIN_CPU_PLATFORM" \    --share-setting=projects \    --share-with=CONSUMER_PROJECT_IDS \    --vm-count=NUMBER_OF_VMS \    --zone=ZONE

    ReplaceMIN_CPU_PLATFORM with a minimum CPU platform.To make sure that a CPU platform is available in the zone where you'rereserving resources,view the available CPU platforms by zone.

  • To specify that only VMs that specifically target this reservation canconsume it, include the--require-specific-reservationflag.

    gcloud compute reservations createRESERVATION_NAME \    --machine-type=MACHINE_TYPE \--require-specific-reservation \    --share-setting=projects \    --share-with=CONSUMER_PROJECT_IDS \    --vm-count=NUMBER_OF_VMS \    --zone=ZONE

  • To letcustom training jobsorprediction jobs inVertex AI consume a reservation of GPU VMs, include the--reservation-sharing-policy flag set toALLOW_ALL.

    gcloud compute reservations createRESERVATION_NAME \    --machine-type=MACHINE_TYPE \--reservation-sharing-policy=ALLOW_ALL \    --share-setting=projects \    --share-with=CONSUMER_PROJECT_IDS \    --vm-count=NUMBER_OF_VMS \    --zone=ZONE

  • To enable Compute Engine toautomatically delete the reservation,select one of the following methods:

    Preview — The--delete-at-time and--delete-after-duration flags

    This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

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

      gcloud beta compute reservations createRESERVATION_NAME \--delete-at-time=DELETE_AT_TIME \    --machine-type=MACHINE_TYPE \    --share-setting=projects \    --share-with=CONSUMER_PROJECT_IDS \    --vm-count=NUMBER_OF_VMS \    --zone=ZONE

      ReplaceDELETE_AT_TIME with a date and timeformatted as anRFC 3339 timestamp, whichmust be as follows:

      YYYY-MM-DDTHH:MM:SSOFFSET

      Replace the following:

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

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

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

    • To delete the reservation after a specific duration, use thegcloud beta compute reservations create commandwith the--delete-after-duration flag.

      gcloud beta compute reservations createRESERVATION_NAME \--delete-after-duration=DELETE_AFTER_DURATION \    --machine-type=MACHINE_TYPE \    --share-setting=projects \    --share-with=CONSUMER_PROJECT_IDS \    --vm-count=NUMBER_OF_VMS \    --zone=ZONE

      ReplaceDELETE_AFTER_DURATION with a duration indays, hours, minutes, or seconds. For example, specify30m for 30minutes, or1d2h3m4s for 1 day, 2 hours, 3 minutes, and 4 seconds.

Terraform

To create a reservation, use thegoogle_compute_reservation Terraform resource.To share a reservation with other projects, define theshare_settings block:

  • Set theshare_type field toSPECIFIC_PROJECTS.
  • In theproject_map block, specify theproject IDsof the projects that you want to share this reservation with.

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

REST

To create a shared reservation, make aPOST request to thereservations.insert method.In the request body, include the following:

  • TheprojectMap field.

  • TheshareType field set toSPECIFIC_PROJECTS.

For example, to create a shared reservation without including any optionalfields and share the reservation with two consumer projects, make thefollowingPOST 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 toreserve resources.

  • ZONE: the zone in which to reserve resources.

  • RESERVATION_NAME: the name of the reservation tocreate.

  • CONSUMER_PROJECT_ID_1 andCONSUMER_PROJECT_ID_2: theIDs of projectsthat can consume this reservation. You can include up to 100 consumerprojects. These projects must be in the same organization as the ownerproject. Don't include the owner project. By default, it is alreadyallowed to consume the reservation.

  • NUMBER_OF_VMS: the number of VMs to reserve.

  • MACHINE_TYPE: a machine type to use for each VM.

For example, to create a reservation by specifying a global instancetemplate in zoneus-central1-a, share the reservation with projectsproject-1 andproject-2, and reserve ten VMs that each use an N2predefined machine type with 4 vCPUs, make the followingPOSTrequest:

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 attach GPUs to your reserved N1 VMs, include theguestAcceleratorsfield in the request body.

    For example, to create a reservation shared with two consumer projects,and attach GPUs to any reserved N1 VMs, make a request as follows:

    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": {"guestAccelerators": [        {          "acceleratorCount":NUMBER_OF_ACCELERATORS,          "acceleratorType": "ACCELERATOR_TYPE"        }      ],      "machineType": "MACHINE_TYPE"    }  }}

    Replace the following:

  • To attach Local SSD disks to amachine type that doesn't include Local SSD disks by default,include thelocalSsds field in the request body. You can only attachLocal SSD disks of 375 GB.

    For example, to attach two Local SSD disks to the machine type that youwant to reserve while specifying two consumer projects, make a requestas follows:

    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": {"localSsds": [        {          "diskSizeGb": "375",          "interface": "INTERFACE_TYPE"        },        {          "diskSizeGb": "375",          "interface": "INTERFACE_TYPE"        }      ],      "machineType": "MACHINE_TYPE"    }  }}

    ReplaceINTERFACE_TYPE with the type of diskinterface that you want each Local SSD disk to use and thatyour specified machine type supports.Specify one of the following values:

    • For the NVME disk interface:NVME

    • For the SCSI disk interface:SCSI

  • To have the reserved VMs use a specificminimum CPU platforminstead of the zone's default CPU platform, include theminCpuPlatformfield in the request body.

    For example, to create a shared reservation while specifying a minimumCPU platform and two consumer projects, make a request as follows:

    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","minCpuPlatform": "MIN_CPU_PLATFORM"    }  }}

    ReplaceMIN_CPU_PLATFORM with a minimum CPU platform.To make sure that a CPU platform is available in the zone where you'rereserving resources,view the available CPU platforms by zone.

  • To specify that only VMs thatspecifically target this reservationcan consume it, include thespecificReservationRequired field in therequest body, and set the field totrue.

    For example, to create a specific reservation and share it with twoconsumer projects, make a request as follows:

    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"    }  },"specificReservationRequired": true}

  • To letcustom training jobsorprediction jobs inVertex AI consume a reservation of GPU VMs, include theserviceShareType field and set it toALLOW_ALL.

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations{  "name": "RESERVATION_NAME","reservationSharingPolicy": {    "serviceShareType": "ALLOW_ALL"  },  "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"    }  }}

  • To enable Compute Engine toautomatically delete the reservation,select one of the following methods:

    Preview — ThedeleteAtTime anddeleteAfterDuration fields

    This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

    • To delete the reservation at a specific date and time, make aPOSTrequest to thebeta.reservations.insert method.In the request body, include thedeleteAtTime field.

      For example, to create a reservation while specifying a date andtime to delete a reservation, and share the reservation with twoconsumer projects, make a request as follows:

      POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/reservations{"deleteAtTime": "DELETE_AT_TIME",  "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"    }  }}

      ReplaceDELETE_AT_TIME with a date and timeformatted as anRFC 3339 timestamp, whichmust be as follows:

      YYYY-MM-DDTHH:MM:SSOFFSET

      Replace the following:

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

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

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

    • To delete the reservation after a specific duration, make aPOSTrequest to thebeta.reservations.insert method.In the request body, include thedeleteAfterDuration field.

      For example, to create a reservation that Compute Enginedeletes after a specific duration, and share the reservation withtwo consumer projects, make a request as follows:

      POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/reservations{"deleteAfterDuration": {    "seconds": "DELETE_AFTER_DURATION"  },  "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"    }  }}

      ReplaceDELETE_AFTER_DURATION with a duration inseconds. For example, specify86400 for 86,400 seconds (1 day).

Troubleshooting

Learn how totroubleshoot reservation creation.

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.