Combine reservations with committed use discounts

Committed use discounts (CUDs)provide deeply discounted prices for your Compute Engine resources in exchangefor 1-year or 3-year committed-use contracts (also known as commitments). Youcommit to a minimum amount of resource usage or a minimum amount of spend andreceive CUDs on your resource usage costs in return. However, commitments don'treserve zonal capacity for your committed resources. To get zonal resources atdiscounted prices and also ensure that capacity is reservedfor them, you must both purchase commitments and create reservations for thosezonal resources.

This document explains how you can receive CUDs for your reserved resources andhow to attach reservations toresource-based commitments.

Before you begin

CUDs for your reserved resources

You receive CUDs from active commitments for anyeligible resource usagein your projects. If you also have any reservations to hold capacity forresources in that project, CUDs from active commitments can also apply tothose reserved resources. For any reserved resources to become eligible toreceive CUDs, the following requirements apply:

  • You aren't receiving any other form of discount for your resource usage.
  • Your VMs must be consuming the reservations while the commitments are active.

  • At a minimum, the following properties must match between your activecommitments and the reservations that your VMs consume:

    • Project and region where they apply
    • Machine family series

Depending on the resource type, you can receive CUDs for your reserved resourcesin one of the following ways:

Attach reservations to resource-based commitments

You can attach reservations to any resource-based commitment and ensure thatcapacity is held in specific zones for the committed resources that you plan touse. You can attach multiple reservations to a single commitment; however,a reservation can only be attached to a single commitment.When you purchase a commitment, you can attach reservations to that commitmentin one of the following ways:

Caution: If you have a shared reservation in a project and want usagefrom the shared projects to be eligible for the current project's CUDs, thenyou must ensure the following:
  1. Enable CUD sharing on the current project's Cloud Billing account.
  2. Share your reservation only with projects that are linked to the same Cloud Billing account.

If you don't meet these conditions, then usage from those projects won't be eligible for the shared CUDs and you might be charged the on-demand rates.

After you purchase a commitment with attached reservations, the reservationsremain active as long as the commitment is active. When your commitment expires,Compute Engine automatically deletes any attached reservations. Deletingthese reservations has no effect on any running VMs that were consumingthose reservations. The running VMs continue to run and you are still chargedfor those VMs.

Important: For the duration of your commitment's term, you cannot delete orresize any attached reservations that specify GPUs, Local SSD disks, or both.However, you can replace the commitment's existing attached reservations withnew ones. For more information on what can and cannot be changed for yourattached reservations, seeAllowed changesin this document.

Committed resources that don't require attached reservations

Committed vCPUs and memory don't require you to attach matching reservations toyour commitments. Nevertheless, when you purchase a commitment that includesvCPUs, memory, or both, you can still choose to attach reservations that specifythose resources. To learn how to purchase commitments solely for vCPUs, memory,or both, without attaching reservations, seePurchasing commitments without attached reservations.

Committed resources that require attached reservations

Committed GPUs and Local SSD disks (with the exception of local Titanium SSDdisks for C4A, C4D, H4D, or Z3 instances) require you to attach matchingreservations to your commitments. When you purchase a commitment that includesany GPUs, Local SSD disks, or both, you must also reserve thoseresources and attach those reservations to your commitment. You cando this using a single reservation or a combination of reservations.When you purchase such a commitment, you can also include vCPUs, memory, orboth. However, you don't need to reserve those vCPUs or memory.

To learn how to purchase commitments for GPUs, see one of the following:

To learn how to purchase commitments for Local SSD disks, seePurchase commitments with attached reservationsin this document.

To view the complete list of machine series that support CUDs for GPUs andLocal SSD disks, see theHardware commitment typessection in the resource-based CUDs documentation.

Quantities of resources allowed in attached reservations

ForvCPUs and memory, you can have attached reservations specifying more orless amounts of resources than you are committing to. If you commit to morevCPUs or memory than you reserve, then Compute Engine reserves capacityonly for these reserved resources. However, you can still use your additionalcommitted resources depending on their availability in your region. If youreserve more vCPUs or memory than you commit to, then you don't receive CUDsfor those additional resources that you reserve.

For example, when youpurchase a commitment for 4 vCPUs and 30 GB memory, you can choose to doeither of the following:

  • Not attach any reservations at all.

  • Attach reservations specifying any combination of these resources types; forexample, the following:

    • 4 vCPUs and 30 GB memory
    • 2 vCPUs and 50 GB memory
    • 10 vCPUs and 10 GB memory

However, if your commitment containsany GPUs, Local SSD disks, or both, youmust reserve and attach all those resources. Your attached reservations mustspecify the exact numbers and types of the GPUs and Local SSD disks that you arecommitting to. Consequently, you also cannot have any additional number or typesof GPUs or Local SSD disks in your attached reservations.

Note: If you're committing to purchasing local Titanium SSD disks foruse with C4A, C4D, H4D, or Z3 instances, then you don't need attachedreservations for those disks.

For example, suppose you purchase a commitment for 30 GBmemory and 4 NVIDIA P100 GPUs. The attached reservation (or combinationof attached reservations) can specify any amount of vCPUs or memory, but it musthave exactly 4 GPUs that are of NVIDIA P100 type. In this example, you can'tattach reservations specifying any of the following combination of resources:

  • 6 NVIDIA P100 GPUs
  • 2 NVIDIA P100 GPUs
  • 4 NVIDIA P100 GPUs and 2 NVIDIA V100 GPUs
  • 4 NVIDIA P100 GPUs and 4 Local SSD disks

Purchase commitments with attached reservations

When you purchase a new commitment, you can attach reservations toyour commitment in either of the following ways:

After you purchase a commitment, your commitment becomes active on thefollowing day at 12 AM US and Canadian Pacific Time (UTC-8, or UTC-7 duringdaylight saving time).Between the time of your commitment purchase and its activation time, thestatus of your commitment remains asNOT_YET_ACTIVE (or asPENDING on theGoogle Cloud console). After activation, the status of your commitment changes toACTIVE.For example, suppose you purchase your commitment on January 20, 2024, at 10:00 PMUS and Canadian Pacific Time (UTC-8 or UTC-7). Compute Engine creates yourcommitment immediately with its status asNOT_YET_ACTIVE. Yourcommitment becomesACTIVE on January 21, 2024, at 12:00 AM USand Canadian Pacific Time (UTC-8 or UTC-7).

Requirements

Before you purchase a commitment with attached reservations, review theserequirements and make sure that your commitment and reservations meet thefollowing criteria:

  • You must purchase the commitment and create the attached reservations in thesame project and region.
  • You must purchase the commitment and create the attached reservations forresources from the same machine family series.
  • You must disable theauto-delete optionon the attached reservations.
  • If your commitment has GPUs, then the GPU type specified in the reservationand the commitment must match.

  • For GPUs and Local SSD disks, the number of reserved resources of eachresource type must exactly match with the number of committed resourcesfor that resource type. However, this requirement isn't applicable whenyou're purchasing a commitment for local Titanium SSD disks for usewith C4A, C4D, H4D, or Z3 machine types.

    For example, if you want to purchase a commitment for 4 V100 GPUs and 2Local SSD disks, then your commitment's attached reservations must specify atotal of 4 V100 GPUs and 2 Local SSDs. The amount of vCPU and memory thatyou reserve can be more or less than what you commit to. However, if youpurchase a commitment for 4 C4A vCPUs and 2 local Titanium SSD disks,then you don't have to attach any reservations to the commitment.

  • For GPUs, purchase commitments for the specific GPU types that youintend to use. For example, you can purchase commitments for either NVIDIAP100s or NVIDIA V100s, but you cannot use a commitment that was purchasedfor NVIDIA P100 GPUs to cover NVIDIA V100 GPUs.

  • If your attached reservation is a shared reservation and you want to receivethe applicable CUDs when you consume that reservation outside yourcommitment's project, then you must do both the following:

    • Share your reservations only between projects that belong to the sameCloud Billing account as the commitment.
    • Enable CUD sharingfor that Cloud Billing account.

Attach existing reservations

You can attach existing reservations while purchasing your commitment by usingthe Google Cloud console, the Google Cloud CLI, or REST.

Permissions required for this task

To perform this task, you must have the followingpermissions:

  • To create a commitment:compute.commitments.create on the project
  • To create reservations:compute.reservations.create on the project

Console

Before you purchase a commitment using the Google Cloud console,select the project that you want to use to purchase the commitment. IfCUD sharingis enabled for a Cloud Billing account, you canpurchase the commitment using any project from that Cloud Billingaccount. After you select the project, do the following:

  1. In the Google Cloud console, go to theCommitted use discountspage.

    Go to Committed use discounts

  2. To purchase a commitment, clickPurchase commitment. ThePurchase a committed use discount pageopens and displays theHardware tab.

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

  4. In theRegion field, select the region where you want to commit toCompute Engine resources.

  5. In theCommitment type field, select the machine family series foryour committed resources.The following commitment types provideoptions for GPUs, Local SSD disks, or both:

  6. ForDuration, do the following:

    1. To specify your commitment's plan, select either1 year or3 years. The plan determines the CUD rate and the preset termduration of your commitment.
    2. Optional. To specify a custom term duration for your commitment,click theExtend end date toggle and then, in theDate field,specify a custom end date. For more information,seeExtend commitment terms.

  7. In theCores field, enter the number of vCPUs that youwant to commit to purchasing.

  8. In theMemory field, enter the amount, in GB, of memorythat you want to commit to purchasing.

    You can specify memory only in increments of 0.25 GB. To specify acustom memory value for your commitment, use gcloud CLIor REST instead.

  9. To commit to GPUs, in theGPUs section, clickAdd GPU and then do the following:

    1. In theGPU type field, select the type of GPU.
    2. In theNumber of GPUs field, enter the number of GPUs.
    3. Optional: If your GPU model supportsNVIDIA RTX Virtual Workstations (vWS) for graphics workloads,and you plan to run graphics-intensive workloads, select theEnable Virtual Workstation (NVIDIA GRID) checkbox.

  10. To commit to Local SSD disks, in theLocal SSDs section, clickAdd SSD and then, in theNumber of SSDs field, specify thenumber of disks.

    Note: If you're committing to purchasing any local Titanium SSDdisks for use with C4A, C4D, H4D, or Z3 machine types, thenyou don't need to create and attach reservations forthose disks.

  11. To attach one or more existing reservations to the commitment,in theReservations field, selectAttach existing reservations.

    The Google Cloud console displays a list of all the reservations inyour project whose region, machine type, and GPU type match with thecommitment. Then, do the following:

    1. Optional. To view reservations with specific properties, in theFilter menu, add or remove filters for the properties thatyou want.
    2. Select all the reservations that you want to attach to thecommitment.
    Important: The types and total number of GPUs and Local SSD disksspecified across all your attached reservations must match with what youspecified in your commitment. Otherwise, you won't be able to purchasethe commitment. If you're committing to purchasing any localTitanium SSD disks for use with C4A, C4D, H4D, or Z3 instances,then you don't need attached reservations for those disks.

  12. To finish purchasing your commitment with the attached reservations,do the following:

    1. ClickPurchase.
    2. In thePurchase a committed use discount dialog, if you agreewith theservice specific terms,clickPurchase again.

gcloud

To purchase a commitment by attaching existing reservations, run thegcloud compute commitments create command.In your command, include the--existing-reservation flag to specify anexisting reservation that you want to attach to your commitment. Include anew instance of this flag for every existing reservation that you want toattach. You can attach any number of existing reservations to yourcommitment.

For example, to purchase a commitment by attaching two reservations to it,run the following command:

gcloud compute commitments createCOMMITMENT_NAME \    --region=REGION \    --project=PROJECT_ID \    --resources=vcpu=COMMITTED_VCPUS,memory=COMMITTED_MEMORY,local-ssd=COMMITTED_LOCAL_SSD \    --resources-accelerator=count=COMMITTED_ACCELERATOR_COUNT,type=COMMITTED_ACCELERATOR_TYPE \    --plan=PLAN \    --type=COMMITMENT_TYPE \    --custom-end-time=CUSTOM_END_DATE \    --existing-reservation=name='RESERVATION_NAME_1',zone='RESERVATION_ZONE_1' \    --existing-reservation=name='RESERVATION_NAME_2',zone='RESERVATION_ZONE_2'

Replace the following:

Example: Purchase a commitment by attaching existing reservations

Suppose you have two reservationsres-01 andres-02 in theus-central1-a andus-central1-b zones of the projectmyproject.Suppose that these reservations hold a combined capacity for 4 NVIDIA P100GPUs and 4 Local SSD disks. To purchase a new commitment in theus-central1 region of this project for these GPUs and Local SSD disks,and use these existing reservations as attached reservations, run thefollowing command. Note that the example commitment also contains vCPUs andmemory.

gcloud compute commitments create commitment-01 \    --region=us-central1 \    --project=myproject \    --resources=vcpu=96,memory=624GB,local-ssd=1500 \    --resources-accelerator=type=nvidia-tesla-p100,count=4 \    --plan 12-month \--existing-reservation=name=res-01,zone=us-central1-a \    --existing-reservation=name=res-02,zone=us-central1-b

REST

To purchase a commitment by attaching existing reservations, make aPOSTrequest to theregionCommitments.insert method.In your request, include theexistingReservations field to specify acomma-separated list of all the existing reservations that you want toattach to your commitment. You can attach any number of existingreservations to your commitment.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/commitments{  "name": "COMMITMENT_NAME",  "plan": "PLAN",  "type":COMMITMENT_TYPE,  "resources":  [    {      "amount": "COMMITTED_VCPUS",      "type": "VCPU"    },    {      "amount": "COMMITTED_MEMORY",      "type": "MEMORY"    },    {      "acceleratorType": "COMMITTED_ACCELERATOR_TYPE",      "amount": "COMMITTED_ACCELERATOR_COUNT",      "type": "ACCELERATOR"    }    {      "amount": "COMMITTED_LOCAL_SSD",      "type": "LOCAL_SSD"    }  ],  "customEndTimestamp": "CUSTOM_END_DATETEND_TIMEZ",  "existingReservations": "RESERVATION_URLs"}

Replace the following:

Example: Purchase a commitment by attaching existing reservations

Suppose you have two reservationsres-01 andres-02 in theus-central1-a andus-central1-b zones of the projectmyproject.Suppose that these reservations hold a combined capacity for 4 NVIDIA P100GPUs and 4 Local SSD disks. To purchase a new commitment in theus-central1 region of this project for these GPUs and Local SSD disks andto use these existing reservations as attached reservations,make the followingPOST request. Note that the example commitment alsocontains vCPUs and memory.

POST https://compute.googleapis.com/compute/v1/projects/my-project/regions/us-central1/commitments{  "name": "commitment-01",  "plan": "TWELVE_MONTH",  "type": "GENERAL_PURPOSE"  "resources":  [    {      "amount": "96",      "type": "VCPU"    },    {      "amount": "638976",      "type": "MEMORY"    },    {      "acceleratorType": "nvidia-tesla-p100",      "amount": "4",      "type": "ACCELERATOR"    },    {      "amount": "1536000",      "type": "LOCAL_SSD"    }  ],  "existingReservations":  [    "https://www.googleapis.com/compute/v1/projects/my-project/zone/us-central1-a/reservations/res-01",    "https://www.googleapis.com/compute/v1/projects/my-project/zone/us-central1-b/reservations/res-02"  ]}

Create new reservations to attach

You can create your attached reservations while purchasing your commitment byusing the Google Cloud console, the Google Cloud CLI, or REST.

Permissions required for this task

To perform this task, you must have the followingpermissions:

  • To create a commitment:compute.commitments.create on the project
  • To create reservations:compute.reservations.create on the project

Console

Before you purchase a commitment using the Google Cloud console,select the project that you want to use to purchase the commitment. IfCUD sharingis enabled for a Cloud Billing account, you canpurchase the commitment using any project from that Cloud Billingaccount. After you select the project, do the following:

  1. In the Google Cloud console, go to theCommitted use discountspage.

    Go to Committed use discounts

  2. To purchase a commitment, clickPurchase commitment. ThePurchase a committed use discount pageopens and displays theHardware tab.

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

  4. In theRegion field, select the region where you want to commit toCompute Engine resources.

  5. In theCommitment type field, select the machine family series foryour committed resources.The following commitment types provideoptions for GPUs, Local SSD disks, or both:

  6. ForDuration, do the following:

    1. To specify your commitment's plan, select either1 year or3 years. The plan determines the CUD rate and the preset termduration of your commitment.
    2. Optional. To specify a custom term duration for your commitment,click theExtend end date toggle and then, in theDatefield, specify a custom end date. For more information,seeExtend commitment terms.

  7. In theCores field, enter the number of vCPUs that youwant to commit to.

  8. In theMemory field, enter the amount, in GB, of memorythat you want to commit to.

  9. To commit to GPUs, in theGPUs section, clickAdd GPU and then do the following:

    1. In theGPU type field, select the type of GPU.
    2. In theNumber of GPUs field, enter the number of GPUs.
    3. Optional: If your GPU model supportsNVIDIA RTX Virtual Workstations (vWS) for graphics workloads,and you plan to run graphics-intensive workloads, select theEnable Virtual Workstation (NVIDIA GRID) checkbox.

  10. To commit to Local SSD disks, in theLocal SSDs section, clickAdd SSD and then, in theNumber of SSDs field, specify thenumber of disks.

  11. To create a new reservation and attach it to the commitment, in theReservations field, selectCreate reservations and then do thefollowing. Repeat this step for every new reservation that you want tocreate and attach.

    1. ClickAdd a reservation. TheNew reservation section appears.
    2. In theName field, enter a name for your attached reservation.
    3. In theRegion field, select the same region as your commitment.
    4. In theZone field, select the zone where you want to reserveyour resources.

    5. In theShare type section, specify how you want to share thisreservation in one of the following ways:

      • To create a single-project reservation, selectLocal.
      • To create a reservation that is shared with multiple projects,selectShared. Then, to specify the projects to share thethis reservation with, clickAdd projects, andthen select the projects that you want from the currentproject's organization.

    6. In theUse with VM instance field, select how you want VMs toconsume your reservation in one of the following ways:

      • To allow VMs with matching properties to automatically consumethis reservation, clickUse reservation automatically(default).
      • To consume this reservation's resources only when creating VMswith matching properties that specifically target thisreservation by name, click selectSelect specific reservation.

    7. In theResource details section, do the following:

      1. In theNumber of VM instances field, enter the number of VMinstances that you want to reserve.

      2. In theMachine configuration section, specify the propertiesof your reserved VMs in one of the following ways:

        1. To specify your the properties of your VMs using an existinginstance template,selectUse instance template.

          In theInstance template field, select an instancetemplate that specifies the same machine family series asyour commitment. If you select a regional instance template,the region of that instance template must also match withthe region specified in your commitment.

        2. To manually specify the properties of your VMs, selectSelect machine type and then do the following:

          1. Select the machine family that applies to themachine series that you specified for the commitment:

            • General purpose for general-purpose machine series
            • Compute optimized for compute-optimized machineseries
            • Memory optimized for memory-optimized machineseries
            • GPUs for accelerator-optimized machine series

          2. In the table that hasSeries column, select thesame machine series that you specified for thecommitment.

          3. In theMachine type field, specify a predefinedor custom machine type in one of the following ways:

            1. To choose a predefined machine type, selectPresetand then select the machine type that you want.
            2. To choose a custom machine type, selectCustomand then specifyCores andMemory that youwant.

          4. To specify a minimum CPU platform, GPUs, or both,expand theCPU Platform and GPU menu and do the following:

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

            2. Optional: To reserve GPUs, clickAdd GPU.Then, in theGPU type andNumber of GPUsfields, select the type and number of GPUs for eachVM.

              Important: The types and total number of GPUsspecified across all your attached reservations mustmatch with what you specified in your commitment.Otherwise, you won't be able to purchase thecommitment.

          5. To reserve Local SSD disks, do the following:

            1. In theNumber of disks field, select the numberof Local SSD disks that you want for each VM.
            2. In theInterface type field, select theinterface for the Local SSD disks.
            Important: The total number of Local SSD disks specifiedacross all your attached reservations must must matchwith what you specified in your commitment. Otherwise,you won't be able to purchase the commitment.

    8. To finish specifying the properties for this reservation, clickDone.

  12. To finish purchasing your commitment with the attached reservations,do the following:

    1. ClickPurchase.
    2. In thePurchase a committed use discount dialog, if you agreewith theservice specific terms,clickPurchase again.

gcloud

To create your attached reservations while purchasing your commitment, runthegcloud compute commitments create command.

Note: You can't use the Google Cloud CLI to create your attached reservationsusing instance templates. Instead, you must manually specify the VMproperties for your reservations.

Depending on whether you want to attach a single reservation or multiplereservations, run the command in one of the following ways:

  • To create and attach a single reservation to your commitment, definethe properties of the attached reservation by running the followingcommand:

    gcloud compute commitments createCOMMITMENT_NAME \    --region=REGION \    --project=PROJECT_ID \    --planPLAN \    --typeCOMMITMENT_TYPE    --resources=vcpu=COMMITTED_VCPUS,memory=COMMITTED_MEMORY,local-ssd=COMMITTED_LOCAL_SSD \    --resources-accelerator=count=COMMITTED_ACCELERATOR_COUNT,type=COMMITTED_ACCELERATOR_TYPE \    --custom-end-time=CUSTOM_END_DATE \    --reservation=RESERVATION_NAME \    --reservation-zone=RESERVATION_ZONE \    --machine-type=RESERVED_MACHINE_TYPE \    --require-specific-reservation=REQUIRE_SPECIFIC_RESERVATION_VALUE \    --vm-count=NUMBER_OF_RESERVED_VMs \    --accelerator=type=RESERVED_ACCELERATOR_TYPE,count=RESERVED_ACCELERATOR_COUNT \    --local-ssd=interface=INTERFACE_1,size=375 \    --local-ssd=interface=INTERFACE_2,size=375 \    --minimum-cpu-platform=MINIMUM_CPU_PLATFORM \    --share-setting=SHARE_SETTING \    --share-with=CONSUMER_PROJECT_ID_1,CONSUMER_PROJECT_ID_2

  • To create and attach multiple reservations to your commitment, definethe reservation's properties using a YAML file and then specify thatYAML file in the command that you use to purchase your commitment.Optionally, you can also use this YAML file approach to create andattach a single reservation to your commitment. To create your attachedreservations using this approach, do the following:

    1. Create the YAML file in the current directory and specify theconfiguration that you want for each attached reservation. Forexample, to specify the configuration of a shared reservationshared with two projects that specifies GPUs, two Local SSD disks,and a minimum CPU platform, include the following text in your YAMLfile:

      -reservation:RESERVATION_NAMEreservation_zone:RESERVATION_ZONErequire_specific_reservation:REQUIRE_SPECIFIC_RESERVATION_VALUEvm_count:NUMBER_OF_RESERVED_VMsmachine_type:RESERVED_MACHINE_TYPEaccelerator:-count:RESERVED_ACCELERATOR_COUNTtype:RESERVED_ACCELERATOR_TYPElocalssd:-interface:INTERFACE_1size:375-interface:INTERFACE_2size:375project:OWNER_PROJECT_IDminimum-cpu-platform:MINIMUM_CPU_PLATFORMshare-setting:SHARE_SETTINGshare-with:-CONSUMER_PROJECT_ID_1-CONSUMER_PROJECT_ID_2

      To specify the configuration for multiple reservations, repeat theseproperties for each reservation that you want to create. You canattach any number of existing reservations that you want to yourcommitment.

    2. Run thegcloud compute commitments create command and includethe--reservation-from-file flag.

      gcloud compute commitments createCOMMITMENT_NAME \    --regionREGION \    --projectPROJECT_ID \    --planPLAN \    --typeCOMMITMENT_TYPE \    --resources=vcpu=COMMITTED_VCPUS,memory=COMMITTED_MEMORY,local-ssd=COMMITTED_LOCAL_SSD \    --resources-accelerator=count=COMMITTED_ACCELERATOR_COUNT,type=COMMITTED_ACCELERATOR_TYPE \    --reservations-from-file=YAML_FILE

Replace the following with the corresponding properties of the commitmentand the attached reservations:

Commitment

Attached reservations

  • RESERVATION_NAME: the name of the attachedreservation.
  • RESERVATION_ZONE: the zone of the attachedreservation.
  • REQUIRE_SPECIFIC_RESERVATION_VALUE: specifiesif the attached reservation is a specifically targeted reservation;eithertrue orfalse. For more information about specificallytargeted reservations, seeHow reservations work.
  • NUMBER_OF_RESERVED_VMS: the number of VMsthat you want to reserve in the attached reservation.

  • RESERVED_MACHINE_TYPE: themachine type that you want for theVMs in your attached reservation.

    • Forpredefined machine types, use the formatMACHINE_FAMILY-standard-CPUS;for example,n2-standard-4.

    • Forcustom machine types, use the formatMACHINE_FAMILY-custom-CPUS-MEMORY;for examplen2-custom-4-5120. For a full list of restrictions,read thespecificationsfor custom machine types.

      Replace the following:

      • MACHINE_FAMILY: the family of machinetypes; for example, specifyn2 for N2 VMs.
      • CPUS: the number ofvCPUs.
      • MEMORY: the total memory for areserved VM. Memory must be a multiple of 256 MBand must be supplied in MB; for example, to create an N2 VMwith 4 vCPUs and 5 GB of memory, which is 5120 MB,usen2-custom-4-5120.

  • RESERVED_ACCELERATOR_COUNT: the number ofGPUs you want to add, per VM, in the attached reservation.

  • RESERVED_ACCELERATOR_TYPE:thetype of accelerator you want to add inthe attached reservation.

  • INTERFACE_1 andINTERFACE_2: the type of interface youwant theLocal SSD disks for eachreserved VM to use. Valid options are:scsi andnvme. Each LocalSSD disk is 375 GB. Repeat thelocal_ssd parameter for eachLocal SSD disk that you want to add. You can specify up to 24 LocalSSD disks.

  • OWNER_PROJECT_ID: the ID of the projectwhere you want to purchase the commitment with the attachedreservation. Specify this field if you want to share your attachedreservation across multiple consumer projects.

  • MINIMUM_CPU_PLATFORM: the minimumCPU platform that you want to specify for the attached reservation.

  • SHARE_SETTING: the type of sharing for theattached reservation. Specify this field with the value asprojectsif you want to share your attached reservation across multipleconsumer projects. Exclude this field if you want create asingle-project reservation.

  • CONSUMER_PROJECT_ID_1 andCONSUMER_PROJECT_ID_2:theproject IDsof the projects that can share this reservation, for exampleproject-1 andproject-2. You can include up to 100 consumerprojects. These projects must be in the same organization as theowner project. Don't include the ID of the project where you createthis reservation, as that project is allowed to consume thisreservation by default. Exclude these fields if you want to createa single-project reservation.

Compute Engine creates the commitment and the attached reservationsonly if there are enough resources of the specified machine type in thetarget zone, and sufficient quota, at the time of your request. If yourpurchase was successful, you see a success message similar to the following:

Created[https://www.googleapis.com/compute/v1/projects/your-project/regions/your-region/commitments/your-commitment-name]

Examples for purchasing commitments by creating new reservations to attach

The following example scenarios and commands show how you can purchase acommitment for GPUs, Local SSD disks, or both by creating new reservationsto attach to that commitment.

Example 1: Purchase a commitment for GPUs by attaching a single new reservation

Suppose you want to purchase a commitmentcommitment-01 in theus-central1 region that includes 4 NVIDIA V100 GPUs. You want to create anew reservationreservation-01 as the attached reservation forthose GPUs. Suppose you also want to specify Compute Engine to usethose reserved GPUs across 2n1-standard-32 VMs in theus-central1-azone. To purchase this example commitment with its attached reservation, runthe following command:

gcloud compute commitments create commitment-01 \    --region=us-central1 \    --project=myproject \    --resources=vcpu=96,memory=624GB \    --resources-accelerator=type=nvidia-tesla-v100,count=4 \    --plan 12-month \--reservation=reservation-01 \    --reservation-zone=us-central1-a \    --machine-type=n1-standard-32 \    --accelerator=type=nvidia-tesla-v100,count=2 \    --vm-count=2

Example 2: Purchase a commitment for GPUs without committing to vCPUs or memory

To commit to and reserve GPUs and Local SSD disks without committing tovCPUs or memory, specify0 as the value for vCPU and memory quantities.For example, suppose you want to purchase a commitmentcommitment-02 for asingle NVIDIA P4 GPU in theus-west2 region. You also want to create a newreservation as the attached reservation and specifyCompute Engine to use the reserved GPU on ann1-standard-2 VM in theus-west2-b zone. To purchase this example commitment with its attachedreservation, run the following command:

gcloud compute commitments create commitment-02 \    --region=us-west2 \    --project=myproject \--resources=vcpu=0,memory=0 \    --resources-accelerator=type=nvidia-tesla-p4,count=1 \    --plan 12-month \    --reservation=reservation-01 \    --reservation-zone=us-west2-b \    --machine-type=n1-standard-2 \    --accelerator=type=nvidia-tesla-p4,count=1 \    --vm-count=1

Example 3: Purchase a commitment for GPUs and Local SSD disks by attaching multiple new reservations

Suppose you want to purchase a commitmentcommitment-03 for 1NVIDIA V100 GPU and 2 Local SSD disks in theus-central1 region. You alsowant to create and attach two reservations in theus-central1-a zone. In the first reservation,res-01, you want toreserve 1n1-standard-2 VM with 1 GPU. You want to makeres-01 atargeted reservation, which means that you must specifically target thatreservation by name to use its reserved VMs. In the second reservation,res-02, you want to reserve 1n1-standard-8 VM with 2 types ofattached Local SSD disks.

To purchase this example commitment with the attached reservations,first create the YAML file with the properties of both reservations.

- reservation: res-01  reservation_zone: us-central1-a  require_specific_reservation: true  vm_count: 1  machine_type: n1-standard-2  accelerator:  - count: 1    type: nvidia-tesla-v100- reservation: res-02  reservation_zone: us-central1-a  vm_count: 1  machine_type: n1-standard-8  local_ssd:  - interface: scsi    size: 375  - interface: nvme    size: 375

After you create the YAML file, to finish purchasing the commitment with itsattached reservations, run the following command. Note that the examplecommitment also contains vCPU and memory resources.

gcloud compute commitments create commitment-03 \    --region=us-central1 \    --project=myproject \    --resources=vcpu=96,memory=624,local-ssd=750 \    --resources-accelerator=type=nvidia-tesla-v100,count=1 \    --plan 12-month \--reservations-from-file=YAML_FILE

REST

To create your attached reservations while purchasing your commitment,make aPOST request to theregionCommitments.insert method.In your request, include thereservations field to define a list of allthe new reservations that you want to create and attach. You can attach anynumber of existing reservations that you want to your commitment.

  • To create your new reservation by manually specifying all the VMproperties, include theinstanceProperties field and exclude thesourceInstanceTemplate field.

    For example, to manually specify the configuration of a shared reservationshared with two projects that specifies GPUs, two Local SSD disks, and aminimum CPU platform, make the following request:

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/commitments{"name": "COMMITMENT_NAME","plan": "PLAN","type":COMMITMENT_TYPE,"resources":[  {    "amount": "COMMITTED_VCPUS",    "type": "VCPU"  },  {    "amount": "COMMITTED_MEMORY",    "type": "MEMORY"  },  {    "acceleratorType": "COMMITTED_ACCELERATOR_TYPE",    "amount": "COMMITTED_ACCELERATOR_COUNT",    "type": "ACCELERATOR"  }  {    "amount": "COMMITTED_LOCAL_SSD",    "type": "LOCAL_SSD"  }],"customEndTimestamp": "CUSTOM_END_DATETEND_TIMEZ","reservations":[  {    "name": "RESERVATION_NAME",    "specificReservation":    {      "count": "NUMBER_OF_RESERVED_VMS",      "instanceProperties":      {        "guestAccelerators":        [          {            "acceleratorCount": "RESERVED_ACCELERATOR_COUNT",            "acceleratorType": "RESERVED_ACCELERATOR_TYPE"          }        ],        "localSsds":        [          {            "diskSizeGb": "375",            "interface": "RESERVED_INTERFACE_1"          },          {            "diskSizeGb": "375",            "interface": "RESERVED_INTERFACE_2"          }        ],        "machineType": "RESERVED_MACHINE_TYPE",        "minCpuPlatform": "MINIMUM_CPU_PLATFORM"      }    },    "specificReservationRequired":REQUIRE_SPECIFIC_RESERVATION_VALUE",    "zone": "RESERVED_ZONE",    "shareSettings":    {      "shareType": "SPECIFIC_PROJECTS",      "projectMap":      {        "CONSUMER_PROJECT_ID_1":        {          "projectId": "CONSUMER_PROJECT_ID_1"        },        "CONSUMER_PROJECT_ID_2":        {          "projectId": "CONSUMER_PROJECT_ID_2"        }      }    }  }]}

  • To create your new reservation by specifying an instance template, includethesourceInstanceTemplate field and exclude theinstancePropertiesfield.

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/commitments{"name": "COMMITMENT_NAME","plan": "PLAN","type":COMMITMENT_TYPE,"resources":[  {    "amount": "COMMITTED_VCPUS",    "type": "VCPU"  },  {    "amount": "COMMITTED_MEMORY",    "type": "MEMORY"  },  {    "acceleratorType": "COMMITTED_ACCELERATOR_TYPE",    "amount": "COMMITTED_ACCELERATOR_COUNT",    "type": "ACCELERATOR"  }  {    "amount": "COMMITTED_LOCAL_SSD",    "type": "LOCAL_SSD"  }],"customEndTimestamp": "CUSTOM_END_DATETEND_TIMEZ","reservations":[  {    "name": "RESERVATION_NAME",    "specificReservation":    {      "count": "NUMBER_OF_RESERVED_VMS",      "sourceInstanceTemplate": "projects/PROJECT_ID/LOCATION/instanceTemplates/INSTANCE_TEMPLATE_NAME"    },    "specificReservationRequired":REQUIRE_SPECIFIC_RESERVATION_VALUE",    "zone": "RESERVED_ZONE",    "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 with the corresponding properties of the commitmentand the attached reservations:

Commitment

Attached reservations

  • RESERVATION_NAME: the name of the attachedreservation.
  • RESERVATION_ZONE: the zone of the attachedreservation.
  • REQUIRE_SPECIFIC_RESERVATION_VALUE: specifiesif the attached reservation is a specifically targeted reservation;eithertrue orfalse. For more information about specificallytargeted reservations, seeHow reservations work.
  • NUMBER_OF_RESERVED_VMS: the number of VMsthat you want to reserve in the attached reservation.

  • RESERVED_MACHINE_TYPE: themachine type that you want for theVMs in your attached reservation.

    • Forpredefined machine types, use the formatMACHINE_FAMILY-standard-CPUS;for example,n2-standard-4.

    • Forcustom machine types, use the formatMACHINE_FAMILY-custom-CPUS-MEMORY;for examplen2-custom-4-5120. For a full list of restrictions,read thespecificationsfor custom machine types.

      Replace the following:

      • MACHINE_FAMILY: the family of machinetypes; for example, specifyn2 for N2 VMs.
      • CPUS: the number ofvCPUs.
      • MEMORY: the total memory for a reservedVM. Memory must be a multiple of 256 MB and mustbe supplied in MB; for example, to create an N2 VM with 4 vCPUsand 5 GB of memory, which is 5120 MB, usen2-custom-4-5120.

  • RESERVED_ACCELERATOR_COUNT: the number ofGPUs you want to add, per VM, in the attached reservation.

  • RESERVED_ACCELERATOR_TYPE:thetype of accelerator you want to add inthe attached reservation.

  • INTERFACE_1 andINTERFACE_2: the type of interface you wanttheLocal SSD disks for each reservedVM to use. Valid options are:scsi andnvme. Each Local SSD diskis 375 GB. Repeat thelocalSsds parameter for each Local SSDdisk that you want to add. You can specify up to 24 Local SSD disks.

  • MINIMUM_CPU_PLATFORM: the minimumCPU platform that you want to specify for the attached reservation.

  • INSTANCE_TEMPLATE_NAME: the name of theinstance template that you want to use to create your attachedreservation.

  • SHARE_SETTING: the type of sharing for theattached reservation. Specify this field with the value asSPECIFIC_PROJECTS if you want to share your attached reservationacross multiple consumer projects. Exclude this field if you wantcreate a single-project reservation.

  • CONSUMER_PROJECT_ID_1 andCONSUMER_PROJECT_ID_2:theproject IDsof the projects that can share this reservation; for example,project-1 andproject-2. You can include up to 100 consumerprojects. These projects must be in the same organization as theowner project. Don't include the ID of the project where you createthis reservation, as that project is allowed to consume thisreservation by default. Exclude these fields if you want to create asingle-project reservation.

Compute Engine creates the commitment and the attached reservations onlyif there are enough resources of the specified machine type in the targetzone, and sufficient quota, at the time of your request. If your purchasewas successful, Compute Engine returns a200 status for yourREST API request.

Examples for purchasing commitments by creating new reservations to attach

The following example scenarios and commands show how you can purchase acommitment for GPUs, Local SSD disks, or both by creating new reservationsto attach to that commitment.

Example 1: Purchase a commitment for GPUs by attaching a single new reservation

Suppose you want to purchase a commitmentcommitment-01 in theus-central1 region that includes 4 NVIDIA V100 GPUs. You want tocreate a new reservationreservation-01 as the attachedreservation for those GPUs. Suppose you also want to specifyCompute Engine to use those reserved GPUs across 2n1-standard-8VMs in theus-central1-a zone. To purchase this example commitmentwith its attached reservation, make the followingPOST request:

POST https://compute.googleapis.com/compute/v1/projects/my-project/regions/us-central1/commitments{  "name": "commitment-01",  "plan": "TWELVE_MONTH",  "type": "GENERAL_PURPOSE"  "resources":  [    {      "amount": "96",      "type": "VCPU"    },    {      "amount": "638976",      "type": "MEMORY"    },    {      "acceleratorType": "nvidia-tesla-v100",      "amount": "4",      "type": "ACCELERATOR"    }  ],  "reservations":  [    {      "name": "reservation-01",      "specificReservation":      {        "count": "2",        "instanceProperties":        {          "guestAccelerators":          [            {              "acceleratorCount": 2,              "acceleratorType": "nvidia-tesla-v100"            }          ],          "machineType": "n1-standard-8"        }      },      "specificReservationRequired": false,      "zone": "us-central1-a"    }  ]}

Example 2: Purchase a commitment for GPUs without committing to vCPUs or memory

To commit to and reserve GPUs and Local SSD disks without committing tovCPUs or memory, specify0 as the value for vCPU and memory quantities.For example, suppose you want to purchase a commitmentcommitment-02 fora single NVIDIA P4 GPU in theus-west2 region. You also want to createa new reservation as the attached reservation and specifyCompute Engine to use the reserved GPU on ann1-standard-2 VM intheus-west2-b zone. To purchase this example commitment with its attachedreservation, make the followingPOST request:

POST https://compute.googleapis.com/compute/v1/projects/my-project/regions/us-west2/commitments{  "name": "commitment-02",  "plan": "TWELVE_MONTH",  "type": "GENERAL_PURPOSE",  "resources":  [    {      "amount": "0",      "type": "VCPU"    },    {      "amount": "0",      "type": "MEMORY"    },    {      "acceleratorType": "nvidia-tesla-p4",      "amount": "4",      "type": "ACCELERATOR"    }  ],  "reservations":  [    {      "name": "reservation-01",      "specificReservation":      {        "count": "1",        "instanceProperties":        {          "guestAccelerators":          [            {              "acceleratorCount": 4,              "acceleratorType": "nvidia-tesla-p4"            }          ],          "machineType": "n1-standard-2"        }      },      "specificReservationRequired": false,      "zone": "us-west2-b"    }  ]}

Example 3: Purchase a commitment for GPUs and Local SSD disks by attaching multiple new reservations

Suppose you want to purchase a commitmentcommitment-03 for 1NVIDIA V100 GPU and 2 Local SSD disks in theus-central1 region. You alsowant to create and attach two reservations in theus-central1-a zone. In the first reservation,res-01, you want toreserve 1n1-standard-2 VM with 1 GPU. You want to makeres-01 atargeted reservation, which means that you must specifically target thatreservation by name to use its reserved VMs. In the second reservation,res-02, you want to reserve 1n1-standard-8 VM with 2 types ofattached Local SSD disks. To purchase this example commitment with theattached reservations, make the followingPOST request. Note that theexample commitment also contains vCPU and memory resources.

POST https://compute.googleapis.com/compute/v1/projects/my-project/regions/us-central1/commitments{  "name": "commitment-03",  "plan": "TWELVE_MONTH",  "type": "GENERAL_PURPOSE",  "resources":  [    {      "amount": "96",      "type": "VCPU"    },    {      "amount": "638976",      "type": "MEMORY"    },    {      "acceleratorType": "nvidia-tesla-v100",      "amount": "1",      "type": "ACCELERATOR"    },    {      "amount": "768000",      "type": "LOCAL_SSD"    }  ],"reservations":  [    {      "name": "res-01",      "specificReservation":      {        "count": "1",        "instanceProperties":        {          "guestAccelerators":          [            {              "acceleratorCount": 1,              "acceleratorType": "nvidia-tesla-v100"            }          ],          "machineType": "n1-standard-2"        }      },      "specificReservationRequired": true,      "zone": "us-central1-a"    },    {      "name": "res-02",      "specificReservation":      {        "count": "1",        "instanceProperties":        {          "localSsds":          [            {              "diskSizeGb": "375",              "interface": "SCSI"            },            {              "diskSizeGb": "375",              "interface": "NVME"            }          ]          "machineType": "n1-standard-8"        }      },      "specificReservationRequired": false,      "zone": "us-central1-a"    }  ]}

Replace reservations that are attached to commitments

Replace your commitment's existing attached reservation with a newreservation if you want to modify the types and numbers of VMs that use yourcommitted resources.

The replacement reservation will always be a newly created reservation.To replace an attached reservation, you must specify the properties of thereservation that you want use as a replacement. Compute Engine thenautomatically creates a new reservation with these properties and uses it toreplace your attached reservation. You can't use an existing reservationto replace your attached reservation.

Allowed changes

When you replace a commitment's existing attached reservation with a newreservation, you can request any of the following changes:

  • You can reserve VMs from a different machine type. However, you must stillreserve VMs from the same machine series in order to continue receivingCUDs for your reserved resources.
  • You can change the number of VMs that you want to reserve.
  • You can change the quantity of GPUs and Local SSD disks that is attached perVM as long as the total quantity of reserved GPUs and Local SSD disksremain the same.
  • You can specify your replaced reservations to be either single-project(also calledlocal on the Google Cloud console) or shared reservations.

Requirements

When you replace your commitment's attached reservation with a new one, yourrequest must meet all of the following requirements:

  • You can replace only one attached reservation at a time with exactly onenew attached reservation. To replace an attached reservation, simultaneouslyremove an existing attached reservation by setting its VM count to 0and define a new attached reservation that you want to replace it.
  • The new reservation must exist in the same project as the commitment.
  • The new reservation must be located in the same zone as the removedreservation.
  • The amount and types of GPUs specified in the new reservation must match theremoved reservation.
  • The numbers and types of Local SSD disks specified in the new reservationmust match the removed reservation.
  • You can only change up to 100 VMs per request. To make a change thatinvolves more than 100 VMs, divide the change into multiple smallerrequests or reach out to Google Cloud Support.

Your request to replace a reservation also depends on the capacity availabilityat that time. If the capacity for a request is unavailable, the request failsand returns a resource availability error, which you can try to resolve bymodifying or postponing the request.For more information, see the documentation fortroubleshooting resource availability.

If your request to replace an attached reservation fails, then the attachedreservation and your existing reserved resources remain unaffected. To preserveyour capacity, wait to make any corresponding changes to your VMsuntil after your request to replace a reservation is successful.

Steps to replace an attached reservation

You can replace a commitment's reservations using the Google Cloud CLI orREST.

gcloud

To replace reservations that are attached to commitments, do the following:

  1. Create a YAML file in the current directory with the configurationsof the following attached reservations:

    • The current reservation that you want to replace.

      To retrieve the details of this reservation, seeView details of a reservation.

    • The new replacement reservation.

    The contents of the YAML file are similar to the following:

    -reservation:CURRENT_RESERVATION_NAMEreservation_zone:CURRENT_RESERVATION_ZONEvm_count:0machine_type:CURRENT_RESERVATION_MACHINE_TYPEaccelerator:-count:CURRENT_RESERVATION_NUMBER_OF_ACCELERATORStype:CURRENT_RESERVATION_ACCELERATOR_TYPElocal_ssd:-interface:CURRENT_RESERVATION_INTERFACE_1size:375-interface:CURRENT_RESERVATION_INTERFACE_2size:375project:CURRENT_RESERVATION_PROJECT_IDshare_setting:CURRENT_RESERVATION_SHARE_SETTINGshare_with:-CURRENT_RESERVATION_CONSUMER_PROJECT_ID_1-CURRENT_RESERVATION_CONSUMER_PROJECT_ID_2-reservation:REPLACEMENT_RESERVATION_NAMEreservation_zone:REPLACEMENT_RESERVATION_ZONEvm_count:REPLACEMENT_RESERVATION_NUMBER_OF_VMsmachine_type:REPLACEMENT_RESERVATION_MACHINE_TYPEaccelerator:-count:REPLACEMENT_RESERVATION_ACCELERATOR_COUNTtype:REPLACEMENT_RESERVATION_ACCELERATOR_TYPElocal_ssd:-interface:REPLACEMENT_RESERVATION_INTERFACE_1size:375-interface:REPLACEMENT_RESERVATION_INTERFACE_2size:375project:REPLACEMENT_RESERVATION_PROJECT_IDshare_setting:REPLACEMENT_RESERVATION_SHARE_SETTINGshare_with:-REPLACEMENT_RESERVATION_CONSUMER_PROJECT_ID_1-REPLACEMENT_RESERVATION_CONSUMER_PROJECT_ID_2

    Replace the following with the corresponding properties of the currentand replacement reservations:

    Current reservation

    For the current reservation, all of the following properties must beexactly the same as when you viewed the reservation. Omit the fieldsfor any properties that the current reservation does not already have.

    • CURRENT_RESERVATION_NAME: the name of thecurrent attached reservation.
    • CURRENT_RESERVATION_ZONE: the zone of thecurrent attached reservation.
    • CURRENT_RESERVATION_MACHINE_TYPE: themachine type of the current attachedreservation.
    • CURRENT_RESERVATION_NUMBER_OF_ACCELERATORS:the number of GPUs reserved in the current attached reservation.
    • CURRENT_RESERVATION_ACCELERATOR_TYPE: thetype of accelerator reserved in the currentattached reservation.
    • CURRENT_RESERVATION_INTERFACE_1 andCURRENT_RESERVATION_INTERFACE_2: the typeof interface that theLocal SSD diskfor each reserved VM use in the current attached reservation.Valid options are:scsi andnvme. Each Local SSD disk is375 GB. Repeat thelocal_ssd parameter for all the reservedLocal SSD disks.
    • CURRENT_RESERVATION_PROJECT_ID:the project ID of the current project that has thecommitment and the attached reservation. Specify this fieldif your current attached reservation is shared across multipleconsumer projects.
    • CURRENT_RESERVATION_SHARE_SETTING:The type of sharing for the current reservation. Specify this fieldwith the value asprojects if your current attached reservation isshared across multiple consumer projects.
    • CURRENT_RESERVATION_CONSUMER_PROJECT_ID_1andCURRENT_RESERVATION_CONSUMER_PROJECT_ID_2:theproject IDsof the projects that you share the current attached reservation with,for exampleproject-1 andproject-2.

    Replacement reservation

    For the replacement reservation, set the following properties asrequired. Ensure that you meet all therequirementswhen you specify these properties. Omit any additional fields thatyou don't want to use.

    • REPLACEMENT_RESERVATION_NAME: the name ofthe new replacement reservation.
    • REPLACEMENT_RESERVATION_ZONE: the zone ofthe new replacement reservation.
    • REPLACEMENT_RESERVATION_NUMBER_OF_VMS: thenumber of VMs that you want to reserve in the new replacementreservation.

    • REPLACEMENT_RESERVATION_MACHINE_TYPE: themachine type that you want for theVMs in your new replacement reservation.

      • Forpredefined machine types, use the formatMACHINE_FAMILY-standard-CPUS;for example,n2-standard-4.
      • Forcustom machine types, use the formatMACHINE_FAMILY-custom-CPUS-MEMORY;for examplen2-custom-4-5120. For a full list of restrictions,read thespecificationsfor custom machine types.

      Replace the following:

      • MACHINE_FAMILY: the family of machinetypes; for example, specifyn2 for N2 VMs.
      • CPUS: the number ofvCPUs.
      • MEMORY: the total memory for areserved VM. Memory must be a multiple of 256 MB and mustbe supplied in MB; for example, to create an N2 VM with 4vCPUs and 5 GB of memory, which is 5120 MB, usen2-custom-4-5120.

    • REPLACEMENT_RESERVATION_NUMBER_OF_ACCELERATORS:the number of GPUs you want to add, per VM, in thereplacement reservation.

    • REPLACEMENT_RESERVATION_ACCELERATOR_TYPE:thetype of accelerator you want to add inthe replacement reservation.

    • REPLACEMENT_RESERVATION_INTERFACE_1 andREPLACEMENT_RESERVATION_INTERFACE_2: thetype of interface you want theLocal SSD disksfor each reserved VM to use. Valid options are:scsi andnvme.Each Local SSD disk is 375 GB. Repeat thelocal_ssd parameterfor each Local SSD disk that you want to add. You can specify up to24 Local SSD disks.

    • REPLACEMENT_RESERVATION_PROJECT_ID:the project ID of the current project that has thecommitment and the attached reservation. Specify this fieldif you want to share your replacement reservation across multipleconsumer projects.

    • REPLACEMENT_RESERVATION_SHARE_SETTING:the type of sharing for the replacement reservation.Specify this field with the value asprojects if you want to shareyour replacement reservation across multiple consumer projects.

    • REPLACEMENT_RESERVATION_CONSUMER_PROJECT_ID_1andREPLACEMENT_RESERVATION_CONSUMER_PROJECT_ID_2:theproject IDsof the projects that can share this reservation, for exampleproject-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 theREPLACEMENT_RESERVATION_PROJECT_ID,which is already allowed to consume this reservation by default.

  2. Run thegcloud beta compute commitments update-reservationscommand and specify the path to the YAML file using the--reservations-from-file flag.

    gcloud beta compute commitments update-reservationsCOMMITMENT_NAME \    --project=PROJECT_ID \    --region=REGION \    --reservations-from-file=YAML_FILE

    Replace the following:

    • COMMITMENT_NAME: the name of thecommitment with the attached reservation.
    • PROJECT_ID: the project ID of thecommitment with the attached reservation.
    • REGION: The region where the commitment islocated.
    • YAML_FILE: The path to the YAML file thatcontains the configuration of the current and replacementreservations.

Example for replacing a reservation that is attached to a commitment

To demonstrate this, this section shows anexample commitment with an attached reservationand how toreplace the example attached reservation.

Example commitment with an attached reservation

For example, suppose that you want to update the attached reservationsfor themy-commitment-with-reservations commitment,that was purchased using the following command:

  gcloud beta compute commitments create my-commitment-with-reservations \      --region=asia-east1 \      --resources=vcpu=16,memory=60GB,local-ssd=3000 \      --resources-accelerator=type=nvidia-tesla-p100,count=4 \      --plan=12-month \      --type=general-purpose \      --reservations-from-file=one-reservation.yaml

For this example, suppose that when this command was run,one-reservation.yaml was a file in the current directory with thefollowing contents, that define an attached reservation namedres-1.

-reservation:res-1reservation_zone:asia-east1-avm_count:4machine_type:n1-standard-4accelerator:-count:1type:nvidia-tesla-p100local_ssd:-interface:scsisize:375-interface:scsisize:375

Thismy-commitment-with-reservations commitment and the attachedreservationres-1 resulted in the following committed and reservedresources:

Resource typeResources in commitment
(my-commitment-with-reservations)		Resources in current attached reservation
(res-1)
vCPUs and memory16 vCPUs and 60 GB16 vCPUs and 60 GB
(4 reservedn1-standard-4 VMs)*
GPUs4 P100 GPUs4 P100 GPUs
(1 P100 GPU per VM, for 4 VMs)*
Local SSD disks3000 GB or 8 Local SSD disks3000 GB or 8 Local SSD disks
(750 GB or 2 Local SSD disks per VM, for 4 VMs)*

*Specifically, the exampleattached reservation,res-1, reserves 4n1-standard-4VMs, each with 1 P100 GPU and 2 Local SSD disks ofscsiinterface type. Then1-standard-4machine typeuses 4 vCPUs and 15 GB for each VM.

Replace the example attached reservation

Suppose you want to replace the attached reservationres-1 for thewith a new attached reservationres-2 and change the reserved resourcesto the following:

Resource typeResources in commitment
(my-commitment-with-reservations)		Resources in current attached reservation
(res-1)		Resources in replacement attached reservation
(res-2)
vCPUs and memory16 vCPUs and 60 GB16 vCPUs and 60 GB
(4 reservedn1-standard-4 VMs)*		16 vCPUs and 60 GB
(2 reserved and sharedn1-standard-8 VMs)†
GPUs4 P100 GPUs4 P100 GPUs
(1 P100 GPU per VM, for 4 VMs)*		4 P100 GPUs
(2 P100 GPUs per VM, for 2 VMs)†
Local SSD disks3000 GB or 8 Local SSD disks3000 GB or 8 Local SSD disks
(750 GB or 2 Local SSD disks per VM, for 4 VMs)*		3000 GB or 8 Local SSD disks
(1500 GB or 4 Local SSD disks per VM, for 2 VMs)*

*Specifically, the exampleattached reservation,res-1, reserves 4n1-standard-4VMs, each with 1 P100 GPU and 2 Local SSD disks ofscsiinterface type. Then1-standard-4machine typeuses 4 vCPUs and 15 GB for each VM.

†Specifically, the replacementattached reservation definesres-2, which reserves 2n1-standard-8 VMs, each with 1 P100 GPU and 4 Local SSD disksofscsi interface type. Additionally,res-2 isshared with 2 other projects,project-1 andproject-2 and owned by the current project,my-project. Then1-standard-8 machinetype uses 8 vCPUs and 30 GB for each VM.

To replace the attached reservationres-1 withres-2for themy-commitment-with-reservations commitment, do the following:

  1. Create a file namedtwo-reservations.yaml in the current directorythat file contains the following contents:

    -reservation:res-1reservation_zone:asia-east1-avm_count:0machine_type:n1-standard-4accelerator:-count:1type:nvidia-tesla-p100local_ssd:-interface:scsisize:375-interface:scsisize:375-reservation:res-2reservation_zone:asia-east1-avm_count:2machine_type:n1-standard-8accelerator:-count:2type:nvidia-tesla-p100project:my-projectshare_setting:projectsshare_with:-project-1-project-2local_ssd:-interface:scsisize:375-interface:scsisize:375-interface:scsisize:375-interface:scsisize:375

  2. Run the following command:

    gcloud beta compute commitments update-reservations my-commitment-with-reservations \    --region=asia-east1 \    --reservations-from-file=two-reservations.yaml

REST

To replace reservations that are attached to commitments, make aPOSTrequest using theregionCommitments.updateReservationsmethod.

POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/regions/COMMITMENT_ZONE/commitments/COMMITMENT_NAME/updateReservations{  "reservations":  [    {      "name": "REPLACEMENT_RESERVATION_NAME",      "specificReservation":      {        "count": "REPLACEMENT_RESERVATION_NUMBER_OF_VMS",        "instanceProperties":        {          "guestAccelerators":          [            {              "acceleratorCount": "REPLACEMENT_RESERVATION_NUMBER_OF_ACCELERATORS",              "acceleratorType": "REPLACEMENT_RESERVATION_ACCELERATOR_TYPE"            }          ],          "localSsds":          [            {              "diskSizeGb": "375",              "interface": "REPLACEMENT_RESERVATION_INTERFACE_1"            },            {              "diskSizeGb": "375",              "interface": "REPLACEMENT_RESERVATION_INTERFACE_2"            }          ],          "machineType": "REPLACEMENT_RESERVATION_MACHINE_TYPE"        }      },      "zone": "REPLACEMENT_RESERVATION_ZONE",      "shareSettings":      {        "shareType": "SPECIFIC_PROJECTS",        "projectMap":        {          "REPLACEMENT_RESERVATION_CONSUMER_PROJECT_ID_1":          {            "projectId": "REPLACEMENT_RESERVATION_CONSUMER_PROJECT_ID_1"          },          "REPLACEMENT_RESERVATION_CONSUMER_PROJECT_ID_2":          {            "projectId": "REPLACEMENT_RESERVATION_CONSUMER_PROJECT_ID_2"          }         }      }    },    {      "name": "CURRENT_RESERVATION_NAME",      "specificReservation":      {        "count": "0",        "instanceProperties":        {          "guestAccelerators":          [            {              "acceleratorCount": "CURRENT_RESERVATION_NUMBER_OF_ACCELERATORS",              "acceleratorType": "CURRENT_RESERVATION_ACCELERATOR_TYPE"            }          ],          "localSsds":          [            {              "diskSizeGb": "375",              "interface": "CURRENT_RESERVATION_INTERFACE_1"            },            {              "diskSizeGb": "375",              "interface": "CURRENT_RESERVATION_INTERFACE_2"            }          ],          "machineType": "CURRENT_RESERVATION_MACHINE_TYPE"        }      },      "zone": "CURRENT_RESERVATION_ZONE",      "shareSettings":      {        "shareType": "SPECIFIC_PROJECTS",        "projectMap":        {          "CURRENT_RESERVATION_CONSUMER_PROJECT_ID_1":          {            "projectId": "CURRENT_RESERVATION_CONSUMER_PROJECT_ID_1"          },          "CURRENT_RESERVATION_CONSUMER_PROJECT_ID_2":          {            "projectId": "CURRENT_RESERVATION_CONSUMER_PROJECT_ID_2"          }         }      }    }  ]}

Replace the following with the corresponding properties of the commitment,the current reservation, and the replacement reservation:

Commitment

  • COMMITMENT_NAME: the name of the commitmentwith the attached reservation.
  • PROJECT_ID: the project ID of the commitmentwith the attached reservation. This is also the project ID for thecurrent and attached reservations.
  • COMMITMENT_ZONE: the zone of the commitmentwith the attached reservation.

Current reservation

For the current reservation, all of the following properties must beexactly the same as when you viewed the reservation. Omit the fieldsfor any properties that the current reservation does not already specify.

  • CURRENT_RESERVATION_NAME: the name of thecurrent attached reservation.
  • CURRENT_RESERVATION_ZONE: the zone of thecurrent attached reservation.
  • CURRENT_RESERVATION_MACHINE_TYPE: themachine type of the current attachedreservation.
  • CURRENT_RESERVATION_NUMBER_OF_ACCELERATORS: thenumber of GPUs reserved in the current attached reservation.
  • CURRENT_RESERVATION_ACCELERATOR_TYPE: thetype of accelerator reserved in the currentattached reservation.
  • CURRENT_RESERVATION_INTERFACE_1 andCURRENT_RESERVATION_INTERFACE_2: the typeof interface that theLocal SSD disksfor each reserved VM use in the current attached reservation.Valid options are:scsi andnvme. Each Local SSD disk is 375 GB.Repeat thelocalSsds parameter for all the reserved Local SSD disks.
  • CURRENT_RESERVATION_SHARE_SETTING:The type of sharing for the current reservation. Specify this parameterwith the value asprojects if your current attached reservation isshared across multiple consumer projects.
  • CURRENT_RESERVATION_CONSUMER_PROJECT_ID_1 andCURRENT_RESERVATION_CONSUMER_PROJECT_ID_2:theproject IDsof the projects that you share the current attached reservation with,for exampleproject-1 andproject-2.

Replacement reservation

For the replacement reservation, set the following properties asrequired. Ensure that you meet all therequirementswhen you specify these properties. Omit any additional fields thatyou don't want to use.

  • REPLACEMENT_RESERVATION_NAME: the name of thenew replacement reservation.
  • REPLACEMENT_RESERVATION_ZONE: the zone of thenew replacement reservation.
  • REPLACEMENT_RESERVATION_NUMBER_OF_VMS: thenumber of VMs that you want to reserve in the new replacement reservation.

  • REPLACEMENT_RESERVATION_MACHINE_TYPE: themachine type that you want for the VMsin your new replacement reservation.

    • Forpredefined machine types, use the formatMACHINE_FAMILY-standard-CPUS;for example,n2-standard-4.
    • Forcustom machine types, use the formatMACHINE_FAMILY-custom-CPUS-MEMORY;for examplen2-custom-4-5120. For a full list of restrictions,read thespecificationsfor custom machine types.

    Replace the following:

    • MACHINE_FAMILY: the family of machine types;for example, specifyn2 for N2 VMs.
    • CPUS: the number ofvCPUs.
    • MEMORY: the total memory for a reserved VM.Memory must be a multiple of 256 MB and must besupplied in MB; for example, to create an N2 VM with 4 vCPUs and5 GB of memory,which is 5120 MB, usen2-custom-4-5120.

  • REPLACEMENT_RESERVATION_NUMBER_OF_ACCELERATORS:the number of GPUs you want to add, per VM, in thereplacement reservation.

  • REPLACEMENT_RESERVATION_ACCELERATOR_TYPE: thetype of accelerator you want to add in thereplacement reservation.

  • REPLACEMENT_RESERVATION_INTERFACE_1 andREPLACEMENT_RESERVATION_INTERFACE_2: the typeof interface you want theLocal SSD disksfor each reserved VM to use. Valid options are:scsi andnvme.Each Local SSD disk is 375 GB. Repeat thelocalSsds parameter foreach Local SSD disks that you want to add. You can specify up to 24Local SSD disks.

  • REPLACEMENT_RESERVATION_SHARE_SETTING:The type of sharing for the replacement reservation. Specify thisparameter with the value asprojects if you want to share yourreplacement reservation across multiple consumer projects.

  • REPLACEMENT_RESERVATION_CONSUMER_PROJECT_ID_1andREPLACEMENT_RESERVATION_CONSUMER_PROJECT_ID_2:theproject IDsof the projects that can share this reservation, for exampleproject-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 thePROJECT_ID,which is already allowed to consume this reservation by default.

Example for replacing a reservation that is attached to a commitment

To demonstrate this, this section shows anexample commitment with an attached reservationand how toreplace the example attached reservation.

Example commitment with an attached reservation

For example, suppose that you want to replace the attached reservationres-1 for themy-commitment-with-reservations commitment, that waspurchased by making the followingPOST request:

  POST https://compute.googleapis.com/compute/beta/projects/my-project/regions/asia-east1/commitments  {    "name": "my-commitment-with-reservations",    "plan": "TWELVE_MONTH",    "reservations":    [      {        "name": "res-1",        "specificReservation":        {          "count": "4",          "instanceProperties":          {            "guestAccelerators":            [              {                "acceleratorCount": "1",                "acceleratorType": "nvidia-tesla-p100"              }            ],            "localSsds":            [              {                "diskSizeGb": "375",                "interface": "scsi"              },              {                "diskSizeGb": "375",                "interface": "scsi"              }            ],            "machineType": "n1-standard-4"          }        },        "zone": "asia-east1-a"      }    ],    "resources":    [      {        "amount": "16",        "type": "VCPU"      },      {        "amount": "61440",        "type": "MEMORY"      },      {        "acceleratorType": "nvidia-tesla-p100",        "amount": "4",        "type": "ACCELERATOR"      }      {        "amount": "3072000",        "type": "LOCAL_SSD"      }    ],    "type": "GENERAL_PURPOSE"  }

Thismy-commitment-with-reservations commitment and the attachedreservationres-1 resulted in the following committed and reservedresources:

Resource typeResources in commitment
(my-commitment-with-reservations)		Resources in current attached reservation
(res-1)
vCPUs and memory16 vCPUs and 60 GB16 vCPUs and 60 GB
(4 reservedn1-standard-4 VMs)*
GPUs4 P100 GPUs4 P100 GPUs
(1 P100 GPU per VM, for 4 VMs)*
Local SSD disks3000 GB or 8 Local SSD disks3000 GB or 8 Local SSD disks
(750 GB or 2 Local SSD disks per VM, for 4 VMs)*

*Specifically, the exampleattached reservation,res-1, reserves 4n1-standard-4VMs, each with 1 P100 GPU and 2 Local SSD disks ofscsi interfacetype. Then1-standard-4machine typeuses 4 vCPUs and 15 GB for each VM.

Replace the example attached reservation

Suppose you want to replace the attached reservationres-1 for thewith a new attached reservationres-2 and change the reserved resourcesto the following:

Resource typeResources in commitment
(my-commitment-with-reservations)		Resources in current attached reservation
(res-1)		Resources in replacement attached reservation
(res-2)
vCPUs and memory16 vCPUs and 60 GB16 vCPUs and 60 GB
(4 reservedn1-standard-4 VMs)*		16 vCPUs and 60 GB
(2 reserved and sharedn1-standard-8 VMs)†
GPUs4 P100 GPUs4 P100 GPUs
(1 P100 GPU per VM, for 4 VMs)*		4 P100 GPUs
(2 P100 GPUs per VM, for 2 VMs)†
Local SSD disks3000 GB or 8 Local SSD disks3000 GB or 8 Local SSD disks
(750 GB or 2 Local SSD disks per VM, for 4 VMs)*		3000 GB or 8 Local SSD disks
(1500 GB or 4 Local SSD disks per VM, for 2 VMs)*

*Specifically, the exampleattached reservation,res-1, reserves 4n1-standard-4VMs, each with 1 P100 GPU and 2 Local SSD disks ofscsiinterface type. Then1-standard-4machine typeuses 4 vCPUs and 15 GB for each VM.

†Specifically, the replacementattached reservation definesres-2, which reserves 2n1-standard-8 VMs, each with 1 P100 GPU and 4 Local SSD disksofscsi interface type. Additionally,res-2 isshared with 2 other projects,project-1 andproject-2 and owned by the current project,my-project. Then1-standard-8 machine type uses8 vCPUs and 30 GB for each VM.

To replace the attached reservationres-1 withres-2for themy-commitment-with-reservations commitment, make the followingPOST request by using theregionCommitments.updateReservationsmethod:

  POST https://compute.googleapis.com/compute/beta/projects/my-project/regions/asia-east1/commitments/my-commitment-with-reservations/updateReservations  {    "reservations":    [      {        "name": "res-2",        "specificReservation":        {          "count": "2",          "instanceProperties":          {            "guestAccelerators":            [              {                "acceleratorCount": 2,                "acceleratorType": "nvidia-tesla-p100"              }            ],            "localSsds":            [              {                "diskSizeGb": "375",                "interface": "scsi"              },              {                "diskSizeGb": "375",                "interface": "scsi"              },              {                "diskSizeGb": "375",                "interface": "scsi"              },              {                "diskSizeGb": "375",                "interface": "scsi"              }            ],            "machineType": "n1-standard-8"          }        },        "zone": "asia-east1-a"      },      {        "name": "res-1",        "specificReservation":        {          "count": "0",          "instanceProperties":          {            "guestAccelerators":            [              {                "acceleratorCount": 1,                "acceleratorType": "nvidia-tesla-p100"              }            ],            "localSsds":            [              {                "diskSizeGb": "375",                "interface": "scsi"              },              {                "diskSizeGb": "375",                "interface": "scsi"              }            ],            "machineType": "n1-standard-4"          }        },        "zone": "asia-east1-a"      }    ]  }

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.