Combine reservations with committed use discounts


Committed use discounts (CUDs) provide deeply discounted prices for your Compute Engine resources in exchange for 1-year or 3-year committed-use contracts (also known as commitments). You commit to a minimum amount of resource usage or a minimum amount of spend and receive CUDs on your resource usage costs in return. However, commitments don't reserve zonal capacity for your committed resources. To get zonal resources at discounted prices and also ensure that capacity is reserved for them, you must both purchase commitments and create reservations for those zonal resources.

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

Before you begin

  • Review the basics of reservations along with their requirements and restrictions. For more information, see Reservations of Compute Engine zonal resources.
  • If you haven't already, set up authentication. Authentication is the process by which your identity is verified for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine as follows.

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

    Console

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

    gcloud

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

      gcloud init
    2. Set a default region and zone.

    REST

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

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

      gcloud init

CUDs for your reserved resources

You receive CUDs from active commitments for any eligible resource usage in your projects. If you also have any reservations to hold capacity for resources in that project, CUDs from active commitments can also apply to those reserved resources. For any reserved resources to become eligible to receive 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 active commitments 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 resources in one of the following ways:

  • vCPUs and memory: To receive CUDs for either or both of these resource types, you can purchase resource-based or spend-based commitments that include the required resource types. When VMs in your project consume any reservations whose properties match such active commitments, you automatically receive the applicable CUDs for these types of reserved resources. If you reserved more resources than you committed to, then you don't receive CUDs for those additional resources.

  • GPUs and Local SSD disks: To receive CUDs for either or both of these resource types, you must do the following:

    • Purchase resource-based commitments that include the required resource types.
    • Create reservations for all the committed resources with properties that match your commitment, and attach those reservations to the commitment.

    When VMs in your project consume these attached reservations, you start to receive the applicable CUDs for these types of reserved resources.

Attach reservations to resource-based commitments

You can attach reservations to any resource-based commitment and ensure that capacity is held in specific zones for the committed resources that you plan to use. 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 commitment in one of the following ways:

  • Using existing reservations whose properties match with the commitment
  • Creating new matching reservations while purchasing your commitment

After you purchase a commitment with attached reservations, the reservations remain active as long as the commitment is active. When your commitment expires, Compute Engine automatically deletes any attached reservations. Deleting these reservations has no effect on any running VMs that were consuming those reservations. The running VMs continue to run and you are still charged for those VMs.

Committed resources that don't require attached reservations

Committed vCPUs and memory don't require you to attach matching reservations to your commitments. Nevertheless, when you purchase a commitment that includes vCPUs, memory, or both, you can still choose to attach reservations that specify those resources. To learn how to purchase commitments solely for vCPUs, memory, or both, without attaching reservations, see Purchasing commitments without attached reservations.

Committed resources that require attached reservations

Committed GPUs and Local SSD disks require you to attach matching reservations to your commitments. When you purchase a commitment that includes any GPUs, Local SSD disks, or both, you must also reserve those resources and attach those reservations to your commitment. You can do this using a single reservation or a combination of reservations. When you purchase such a commitment, you can also include vCPUs, memory, or both. However, you don't need to reserve those vCPUs or memory. To learn how to purchase commitments that include either or both GPUs and Local SSD disks, see Purchase commitments with attached reservations in this document.

To view the complete list of machine series that support CUDs for GPUs and Local SSD disks, see the Commitment types section in the resource-based CUDs documentation.

Quantities of resources allowed in attached reservations

For vCPUs and memory, you can have attached reservations specifying more or less amounts of resources than you are committing to. If you commit to more vCPUs or memory than you reserve, then Compute Engine reserves capacity only for these reserved resources. However, you can still use your additional committed resources depending on their availability in your region. If you reserve more vCPUs or memory than you commit to, then you don't receive CUDs for those additional resources that you reserve.

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

  • Not attach any reservations at all.
  • Attach reservations specifying any combination of these resources types; for example, the following:

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

However, if your commitment contains any GPUs, Local SSD disks, or both, you must reserve and attach all those resources. Your attached reservations must specify the exact numbers and types of the GPUs and Local SSD disks that you are committing to. Consequently, you also cannot have any additional number or types of GPUs or Local SSD disks in your attached reservations. For example, suppose you purchase a commitment for 30 GB memory and 4 NVIDIA P100 GPUs. The attached reservation (or combination of attached reservations) can specify any amount of vCPUs or memory, but it must have exactly 4 GPUs that are of NVIDIA P100 type. In this example, you can't attach 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 to your commitment in either of the following ways:

After you purchase a commitment, your commitment becomes active on the following day at 12 AM US and Canadian Pacific Time (UTC-8, or UTC-7 during daylight saving time). Between the time of your commitment purchase and its activation time, the status of your commitment remains as NOT_YET_ACTIVE (or as PENDING on the Google Cloud console). After activation, the status of your commitment changes to ACTIVE. For example, suppose you purchase your commitment on January 20th at 10:00 PM US and Canadian Pacific Time (UTC-8 or UTC-7). Compute Engine creates your commitment immediately with its status as NOT_YET_ACTIVE. However, your commitment becomes ACTIVE only on January 21st at 12:00 AM US and Canadian Pacific Time (UTC-8 or UTC-7).

Requirements

Before you purchase a commitment with attached reservations, review these requirements and make sure that your commitment and reservations meet the following criteria:

  • You must purchase the commitment and create the attached reservations in the same project and region.
  • You must purchase the commitment and create the attached reservations for resources from the same machine family series.
  • You must disable the auto-delete option on the attached reservations.
  • If your commitment has GPUs, then the GPU type specified in the reservation and the commitment must match.
  • For GPUs and Local SSD disks, the number of reserved resources of each resource type must exactly match with the number of committed resources for that resource type. For example, if you want to purchase a commitment for 4 V100 GPUs, then your commitment's attached reservations must specify a total of 4 V100 GPUs. However, the amount of vCPU and memory that you reserve can be more or less than what you commit to.
  • For GPUs, purchase commitments for the specific GPU types that you intend to use. For example, you can purchase commitments for either NVIDIA P100s or NVIDIA V100s, but you cannot use a commitment that was purchased for NVIDIA P100 GPUs to cover NVIDIA V100 GPUs.
  • If your attached reservation is a shared reservation and you want to receive the applicable CUDs when you consume that reservation outside your commitment's project, then you must do both the following:

    • Share your reservations only between projects that belong to the same Cloud Billing account as the commitment.
    • Enable CUD sharing for that Cloud Billing account.

Attach existing reservations

You can purchase a commitment by attaching existing reservations to that commitment by using the Google Cloud CLI or REST.

gcloud

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

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

gcloud compute commitments create COMMITMENT_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=DURATION \
    --type=COMMITMENT_TYPE \
    --existing-reservation=name='RESERVATION_NAME_1',zone='RESERVATION_ZONE_1' \
    --existing-reservation=name='RESERVATION_NAME_2',zone='RESERVATION_ZONE_2'

Replace the following:

  • COMMITMENT_NAME: the name of the commitment.
  • REGION: the region where the commitment is located.
  • PROJECT_ID: the ID of the project where you want to purchase the commitment with the attached reservations.
  • DURATION: the term duration of the commitment, either 12-month or 36-month.
  • COMMITMENT_TYPE: the commitment type. The following commitment types provide options for GPUs, Local SSD disks, or both:

    • accelerator-optimized for machine type resources
    • compute-optimized for C2 machine type resources
    • compute-optimized-c2d for C2D machine type resources
    • compute-optimized-c3 for C3 machine type resources
    • compute-optimized-c3d for C3D machine type resources
    • general-purpose for N1 machine type resources
    • general-purpose-e2 for E2 machine type resources
    • general-purpose-n2 for N2 machine type resources
    • general-purpose-n2d for N2D machine resources
    • general-purpose-t2d for Tau T2D machine type resources
    • graphics-optimized for G2 machine type resources
    • memory-optimized for M1 or M2 machine type resources
    • memory-optimized-m3 for memory-optimized M3 machine type
  • COMMITTED_VCPUS: the number of vCPUs that you want in your commitment. The number must be a positive integer.

  • COMMITTED_MEMORY: the amount, in MB or GB, of memory that you want in your commitment. For example, 10240MB or 10GB. If you don't specify a unit, Compute Engine uses GB as the unit. You can purchase memory in increments of 0.25 GB.

  • COMMITTED_LOCAL_SSD: the amount, in GB, of Local SSD space that you want in your commitment. Each Local SSD disk is 375 GB.

  • COMMITTED_ACCELERATOR_COUNT: the number of GPUs that you want in your commitment.

  • COMMITTED_ACCELERATOR_TYPE: the GPU type that you want in your commitment.

  • RESERVATION_NAME_1 and RESERVATION_NAME_2: The names of the existing reservations that you want to attach to the commitment.

  • RESERVATION_ZONE_1 and RESERVATION_ZONE_2: The zones of the existing reservations that you want to attach to the commitment.

Example: Purchase a commitment by attaching existing reservations

Suppose you have two reservations res-01 and res-02 in the us-central1-a and us-central1-b zones of the project myproject. Suppose that these reservations hold a combined capacity for 4 NVIDIA P100 GPUs and 4 Local SSD disks. To purchase a new commitment in the us-central1 region of this project for these GPUs and Local SSD disks, and use these existing reservations as attached reservations, run the following command. Note that the example commitment also contains vCPUs and memory.

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 \
    --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 a POST request to the regionCommitments.insert method. In your request, include the existingReservations field to specify a comma-separated list of all the existing reservations that you want to attach to your commitment. You can attach any number of existing reservations to your commitment.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/commitments

{
  "name": "COMMITMENT_NAME",
  "plan": "DURATION",
  "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"
    }
  ],
  "existingReservations": "RESERVATION_URLs"
}

Replace the following:

  • COMMITMENT_NAME: the name of the commitment.
  • REGION: the region where the commitment is located.
  • PROJECT_ID: the ID of the project where you want to purchase the commitment with the attached reservations.
  • DURATION: the term duration of the commitment, either TWELVE_MONTH or THIRTY_SIX_MONTH.
  • COMMITMENT_TYPE: the commitment type. The following commitment types provide options for GPUs, Local SSD disks, or both:

    • GENERAL_PURPOSE_E2 for E2 machine type resources
    • GENERAL_PURPOSE_N2 for N2 machine type resources
    • GENERAL_PURPOSE_N2D for N2D machine resources
    • COMPUTE_OPTIMIZED_C3 for C3 machine type resources
    • GENERAL_PURPOSE_C3D for C3D machine type resources
    • GENERAL_PURPOSE_T2D for Tau T2D machine type resources
    • GENERAL_PURPOSE for N1 machine type resources
    • COMPUTE_OPTIMIZED for C2 machine type resources
    • COMPUTE_OPTIMIZED_C2D for C2D machine type resources
    • MEMORY_OPTIMIZED for M1 or M2 machine type resources
    • MEMORY_OPTIMIZED_M3 for memory-optimized M3 machine type
    • ACCELERATOR_OPTIMIZED for machine type resources
    • GRAPHICS_OPTIMIZED for G2 machine type resources
  • COMMITTED_VCPUS: the number of vCPUs that you want in your commitment. The number must be a positive integer.

  • COMMITTED_MEMORY: the amount, in MB, of memory that you want in your commitment. For example, 10240MB. You can purchase memory in increments of 256 MB.

  • COMMITTED_LOCAL_SSD: the amount, in GB, of Local SSD storage that you want in your commitment. Each Local SSD disks is 375 GB.

  • COMMITTED_ACCELERATOR_COUNT: the number of GPUs that you want in your commitment.

  • COMMITTED_ACCELERATOR_TYPE: the GPU type that you want in your commitment.

  • RESERVATION_URLs: a comma-separated list of URLs of the existing reservations that you want to attach to the commitment. For example, to attach two reservations, res-1 and res-2, specify the following:

    "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/reservations/example-res-1",
    "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-c/reservations/example-res-2"
    

Example: Purchase a commitment by attaching existing reservations

Suppose you have two reservations res-01 and res-02 in the us-central1-a and us-central1-b zones of the project myproject. Suppose that these reservations hold a combined capacity for 4 NVIDIA P100 GPUs and 4 Local SSD disks. To purchase a new commitment in the us-central1 region of this project for these GPUs and Local SSD disks and to use these existing reservations as attached reservations, make the following POST request. Note that the example commitment also contains 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-v100",
      "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 by using the Google Cloud console, the Google Cloud CLI, or REST.

Console

Before you purchase a commitment using the Google Cloud console, select the project that you want to use to purchase the commitment. If discount sharing is enabled for a Cloud Billing account, you can purchase the commitment using any project from that Cloud Billing account. After you select the project, do the following:

  1. In the Google Cloud console, go to the Committed use discounts page.

    Go to Committed use discounts

  2. To purchase a new commitment, click Purchase commitment.

  3. Name your commitment, and choose the Region where you want it to apply.

  4. Choose the Commitment type. The following commitment types provide options for GPUs, Local SSD disks, or both:

    • General-Purpose C3 for C3 machine type resources
    • General-Purpose C3D for C3D machine type resources
    • General-Purpose N2 for N2 machine type resources
    • General-Purpose N2D for N2D machine type resources
    • General-Purpose N1 for N1 machine type resources
    • Compute-optimized H3 for H3 machine type resources
    • Compute-optimized C2 for C2 machine type resources
    • Compute-optimized C2D for C2D machine type resources
    • Memory-optimized M1/M2 for M1 and M2 machine type resources
    • Memory-optimized M3 for M3 machine type resources
    • Accelerator-optimized A3 for A3 machine type resources
    • Accelerator-optimized A2 for A2 machine type resources
    • Graphics-optimized G2 for G2 machine type resources
  5. Choose a commitment Duration of 1 or 3 years.

  6. Enter the quantity of Cores and Memory that you want to purchase. If you only want to commit to and reserve GPUs or Local SSD disks without committing to vCPUs and memory, specify 0 for the vCPUs and memory commitment quantities.

  7. Click Add GPUs and select the GPU type and Number of GPUs that you want to commit to.

  8. Click Add Local SSD and specify the number of disks that you want to commit to.

  9. To create a reservation and attach it to the commitment, click Add a Reservation.

    1. In the Name field, enter a name for your reservation.
    2. Choose the Region and Zone where you want to reserve resources.
    3. Choose your preferred Share type:
      • To create a reservation for a single project, select Local.
      • To create a shared reservation among multiple projects, select Shared. To share this reservation with other projects, click Add projects and select the projects that you want from the current project's organization.
    4. In the Use with VM instance field, select one of the following options:

      • To use this reservation's resources only when creating matching VMs that specifically target this reservation by name, select Select specific reservation.
      • To allow matching VM instances to automatically use this reservation, select Use reservation automatically.
    5. In the Number of VM instances field, enter the number of VM instances that you want to reserve.

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

      • If you want to reserve VMs that match an existing instance template, select Use instance template and select an instance template from the list.
      • Otherwise, select Specify machine type and specify the following:
        1. In the Machine family field, select the machine family: General purpose, Compute optimzed, Memory optimized, or GPUs.
        2. In the Series and Machine type fields, select a machine series and machine type.
        3. Optional: Specify a minimum CPU platform and/or GPUs:
          1. Click CPU Platform and GPU to expand the section.
          2. Optional: To specify a minimum CPU platform, in the CPU Plaform list, select an option.
          3. Optional: To add GPUs, click Add GPU. Then, in the GPU type and Number of GPUs fields, select the type and number of GPUs for each VM.
        4. Optional: Add Local SSD disks:
          1. In the Number of disks field, select the number of Local SSD disks for each VM.
          2. In the Interface type field, select the interface for the Local SSD disks.
    7. To finish specifying the properties for this reservation, click Done.

  10. Click the Purchase button to purchase the commitment.

  11. Read the terms of purchase and click Purchase when you are ready to purchase the commitment.

gcloud

To create your attached reservations while purchasing your commitment, run the gcloud compute commitments create command.

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

  • To create and attach a single reservation to your commitment, define the properties of the attached reservation by running the following command:

    gcloud compute commitments create COMMITMENT_NAME \
        --region=REGION \
        --project=PROJECT_ID \
        --plan DURATION \
        --type COMMITMENT_TYPE
        --resources=vcpu=COMMITTED_VCPUS,memory=COMMITTED_MEMORY,local-ssd=COMMITTED_LOCAL_SSD \
        --resources-accelerator=count=COMMITTED_ACCELERATOR_COUNT,type=COMMITTED_ACCELERATOR_TYPE \
        --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, define the reservation's properties using a YAML file and then specify that YAML file in the command that you use to purchase your commitment. Optionally, you can also use this YAML file approach to create and attach a single reservation to your commitment. To create your attached reservations using this approach, do the following:

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

      - reservation: RESERVATION_NAME
        reservation_zone: RESERVATION_ZONE
        require_specific_reservation: REQUIRE_SPECIFIC_RESERVATION_VALUE
        vm_count: NUMBER_OF_RESERVED_VMs
        machine_type: RESERVED_MACHINE_TYPE
        accelerator:
        - count: RESERVED_ACCELERATOR_COUNT
          type: RESERVED_ACCELERATOR_TYPE
        localssd:
        - interface: INTERFACE_1
          size: 375
        - interface: INTERFACE_2
          size: 375
        project: OWNER_PROJECT_ID
        minimum-cpu-platform: MINIMUM_CPU_PLATFORM
        share-setting: SHARE_SETTING
        share-with:
        - CONSUMER_PROJECT_ID_1
        - CONSUMER_PROJECT_ID_2
      
      

      To specify the configuration for multiple reservations, repeat these properties for each reservation that you want to create. You can attach any number of existing reservations that you want to your commitment.

    2. Run the gcloud compute commitments create command and include the --reservation-from-file flag.

      gcloud compute commitments create COMMITMENT_NAME \
          --region REGION \
          --project PROJECT_ID \
          --plan DURATION \
          --type COMMITMENT_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 commitment and the attached reservations:

Commitment

  • COMMITMENT_NAME: the name of the commitment.
  • REGION: the region where the commitment is located.
  • PROJECT_ID: the ID of the project where you want to purchase the commitment with the attached reservations.
  • DURATION: the term duration of the commitment, either 12-month or 36-month.
  • COMMITMENT_TYPE: the commitment type. The following commitment types provide options for GPUs, Local SSD disks, or both:

    • general-purpose-e2 for E2 machine type resources
    • general-purpose-n2 for N2 machine type resources
    • general-purpose-n2d for N2D machine resources
    • compute-optimized-c3 for C3 machine type resources
    • general-purpose-c3d for C3D machine type resources
    • general-purpose-t2d for Tau T2D machine type resources
    • general-purpose for N1 machine type resources
    • compute-optimized for C2 machine type resources
    • compute-optimized-c2d for C2D machine type resources
    • memory-optimized for M1 or M2 machine type resources
    • memory-optimized-m3 for memory-optimized M3 machine type
    • accelerator-optimized for machine type resources
    • graphics-optimized for G2 machine type resources
  • COMMITTED_VCPUS: the number of vCPUs that you want in your commitment. The number must be a positive integer.

  • COMMITTED_MEMORY: the amount, in MB or GB, of memory that you want in your commitment. For example, 10GB or 10240MB. If you don't specify a unit, Compute Engine uses GB as the unit. You can purchase memory in increments of 0.25 GB.

  • COMMITTED_LOCAL_SSD: the amount, in GB, of Local SSD storage that you want in your commitment. Each Local SSD disk is 375 GB.

  • COMMITTED_ACCELERATOR_COUNT: the number of GPUs that you want in your commitment.

  • COMMITTED_ACCELERATOR_TYPE: the GPU type that you want in your commitment.

  • YAML_FILE: The path to the YAML file that contains the configuration of the attached reservations.

Attached reservations

  • RESERVATION_NAME: the name of the attached reservation.
  • RESERVATION_ZONE: the zone of the attached reservation.
  • REQUIRE_SPECIFIC_RESERVATION_VALUE: specifies if the attached reservation is a specifically targeted reservation; either true or false. For more information about specifically targeted reservations, see How reservations work.
  • NUMBER_OF_RESERVED_VMS: the number of VMs that you want to reserve in the attached reservation.
  • RESERVED_MACHINE_TYPE: the machine type that you want for the VMs in your attached reservation.

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

      Replace the following:

      • MACHINE_FAMILY: the family of machine types; for example, specify n2 for N2 VMs.
      • CPUS: the number of vCPUs.
      • MEMORY: the total memory for a reserved VM. Memory must be a multiple of 256 MB and must be supplied in MB; for example, to create an N2 VM with 4 vCPUs and 5 GB of memory, which is 5120 MB, use n2-custom-4-5120.
  • RESERVED_ACCELERATOR_COUNT: the number of GPUs you want to add, per VM, in the attached reservation.

  • RESERVED_ACCELERATOR_TYPE: the type of accelerator you want to add in the attached reservation.

  • INTERFACE_1 and INTERFACE_2: the type of interface you want the Local SSD disks for each reserved VM to use. Valid options are: scsi and nvme. Each Local SSD disk is 375 GB. Repeat the local_ssd parameter for each Local SSD disk that you want to add. You can specify up to 24 Local SSD disks.

  • OWNER_PROJECT_ID: the ID of the project where you want to purchase the commitment with the attached reservation. Specify this field if you want to share your attached reservation across multiple consumer projects.

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

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

  • CONSUMER_PROJECT_ID_1 and CONSUMER_PROJECT_ID_2: the project IDs of the projects that can share this reservation, for example project-1 and 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 ID of the project where you create this reservation, as that project is allowed to consume this reservation by default. Exclude these fields if you want to create a single-project reservation.

Compute Engine creates the commitment and the attached reservations only if there are enough resources of the specified machine type in the target zone, and sufficient quota, at the time of your request. If your purchase 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 a commitment for GPUs, Local SSD disks, or both by creating new reservations to attach to that commitment.

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

Suppose you want to purchase a commitment commitment-01 in the us-central1 region that includes 4 NVIDIA V100 GPUs. You want to create a new reservation reservation-01 as the attached reservation for those GPUs. Suppose you also want to specify Compute Engine to use those reserved GPUs across 2 n1-standard-32 VMs in the us-central1-a zone. To purchase this example commitment with its attached reservation, run the 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 to vCPUs or memory, specify 0 as the value for vCPU and memory quantities. For example, suppose you want to purchase a commitment commitment-02 for a single NVIDIA P4 GPU in the us-west2 region. You also want to create a new reservation as the attached reservation and specify Compute Engine to use the reserved GPU on an n1-standard-2 VM in the us-west2-b zone. To purchase this example commitment with its attached reservation, 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 commitment commitment-03 for 1 NVIDIA V 100 GPU and 2 Local SSD disks in the us-central1 region. You also want to create and attach two reservations in the us-central1-a zone. In the first reservation, res-01, you want to reserve 1 n1-standard-2 VM with 1 GPU. You want to make res-01 a targeted reservation, which means that you must specifically target that reservation by name to use its reserved VMs. In the second reservation, res-02, you want to reserve 1 n1-standard-8 VM with 2 types of attached 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 its attached reservations, run the following command. Note that the example commitment 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 a POST request to the regionCommitments.insert method. In your request, include the reservations field to define a list of all the new reservations that you want to create and attach. You can attach any number of existing reservations that you want to your commitment.

  • To create your new reservation by manually specifying all the VM properties, include the instanceProperties field and exclude the sourceInstanceTemplate field.

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

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/commitments
    
    {
    "name": "COMMITMENT_NAME",
    "plan": "DURATION",
    "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"
      }
    ],
    "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, include the sourceInstanceTemplate field and exclude the instanceProperties field.

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/commitments
    
    {
    "name": "COMMITMENT_NAME",
    "plan": "DURATION",
    "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"
      }
    ],
    "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 commitment and the attached reservations:

Commitment

  • COMMITMENT_NAME: the name of the commitment.
  • REGION: the region where the commitment is located.
  • PROJECT_ID: the ID of the project where you want to purchase the commitment with the attached reservations.
  • DURATION: the term duration of the commitment, either TWELVE_MONTH or THIRTY_SIX_MONTH.