Merge and split commitments


To help you manage the resource requirements for your projects, Compute Engine lets you merge or split your existing commitments and redistribute your resources to match the granularity required for your projects.

This document describes the benefits and process of merging and splitting commitments, along with the limitations and requirements that apply.

Before you begin

  • 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

Merge commitments

You can merge multiple compatible commitments to create a new larger commitment. By merging commitments together, you can track and manage them as a single entity. Merging commitments helps you avoid staggered commitment expiration dates by co-terming the individual commitments to expire at the same time. Merging also lets you gradually ramp up your workloads. For example, you can purchase newer, smaller commitments when the need arises and choose to merge them together or with an existing commitment.

Limitations for merging

  • You can't merge license commitments.
  • At the time of creation of merged commitments, you can't create any new reservations and attach them to those commitments.
  • You can't merge commitments that have expired or are cancelled.
  • By default, when you create merged commitments, the auto-renew setting is disabled on the new commitments even if all the source commitments were set to renew automatically. If you want your merged commitments to renew automatically, you must manually enable the auto-renew setting on those commitments. You can do so either at the time of their creation or after their creation.

How merging works

When you merge individual commitments (source commitments) together, you create a new commitment (merged commitment) with the combined resources from all the source commitments. At 12 AM US and Canadian Pacific Time (UTC-8, or UTC-7 during daylight saving time) on the following day, the merged commitment becomes active and the source commitments get cancelled. This date of activation becomes the start date for the merged commitment and the merge operation ends.

Compute Engine sets the expiration date for the merged commitment to whichever expiration date among the source commitments is furthest in the future. For example, if you have two source commitments and they expire on January 1, 2023 and December 1, 2023 respectively, then the merged commitment expires on December 1, 2023.

If any of the source commitments have reservations attached, then the reservations are preserved during the merge and are attached to the merged commitment after its creation. To learn more about commitments with attached reservations, see Combining reservations with committed use discounts.

Pricing implications for merging

Your commitment fee is the sum of the discounted prices of all your committed resources. When you merge your commitment, the discounted prices of your merged commitment's resources might change on the day your merged commitment becomes active. This new discounted price for each resource stays the same until the end of your merged commitment's term, even if the on-demand prices change. However, if you merge or split this commitment again in the future, the discounted prices of the resources might change again.

Example of a merged commitment

The following table shows the properties of source and merged commitments in a scenario where two commitments (source-commitment-1 and source-commitment-2) are merged into one single commitment (merged-commitment) on March 1, 2022:

First source commitment
(before merge)
Second source commitment
(before merge)
Merged commitment
Name source-commitment-1 source-commitment-2 merged-commitment
Type N2 N2 N2
Region us-central-1 us-central-1 us-central-1
Resources
  • vCPUs: 100
  • Memory: 100 GB
  • vCPUs: 200
  • Memory: 300 GB
  • vCPUs: 300
  • Memory: 400 GB
Term 3 years 3 years 3 years
Start date* January 1, 2020 December 1, 2020 March 2, 2022
(the day after the merge)
End date January 1, 2023 December 1, 2023 December 1, 2023

*All commitments start at 12 AM US and Canadian Pacific Time (UTC-8, or UTC-7) on the specified start date.
All commitments end at 12 AM US and Canadian Pacific Time (UTC-8, or UTC-7) on the specified end date.

Requirements for merging

When you merge individual source commitments to create a new merged commitment, your source and merged commitments must meet the following requirements:

  • The source commitments must have the same project, region, duration (or term), commitment type, and commitment category.
  • The new merged commitment must have the same project, region, duration (or term), commitment type, and commitment category as the source commitments. However, you can choose a new name for your merged commitment.
  • The resource types you specify for your merged commitment must be the exact same resources types that are in the source commitments. Additionally, the amount of resources for each resource type in your new merged commitment must be equal to the sum of the amounts of resources for that resource type in all the source commitments. For example, if the first source commitment has 100 vCPUs and 100 GB memory and the second source commitment has 200 vCPUs and 300 GB memory, then you must create your merged commitment with 300 vCPUs and 400 GB memory.
  • The source and merged commitments must be for hardware resources (vCPUs, memory, GPUs, and Local SSD disks).

Create merged commitments

Create a merged commitment by using the gcloud CLI or the Compute Engine API. Before you merge commitments, review the limitations for merging.

Console

  1. In the Google Cloud console, select the project where you want to merge commitments and go to the Committed use discounts page.

    Go to Committed use discounts

  2. To initiate the merge operation for a set of commitments, in the Hardware commitments tab of the Commitment list page, click Merge.

    Alternatively, you can also select the commitments that you want to merge from the list and then click Merge.

  3. On the Choose commitment tab of the Merge page that opens, do the following:

    1. Under Choose commitments to merge, select the commitments that you want to merge from the list. If you already selected these commitments on the Commitment list page, then verify your selected commitments on this tab.

      Optional: you can also specify the Plan, Region, and Commitment type values that you want for your merged commitment before you select the individual commitments for merging. Doing this filters the commitment list to display only those commitments that you can merge for the specified attributes.

    2. Click Next. The Review tab opens.

  4. On the Review tab of the Merge page, do the following:

    1. Review and confirm the details of the merged commitment. To modify the list of individual commitments that you want to merge, select the Choose commitment tab on the left side of the window and repeat step 3.
    2. In the New commitment name field, enter a name for your merged commitment.
    3. Optional: To enable auto renew on your merged commitment, select the Enable auto renew checkbox.
    4. Read the Terms and conditions.
    5. To finish creating your merged commitment and return to the Commitment list page, click Merge.

gcloud

To merge existing commitments into a single commitment, use the gcloud compute commitments create command with the --merge-source-commitment flag.

gcloud compute commitments create COMMITMENT_NAME \
    --region=REGION \
    --project=PROJECT_ID \
    --plan=DURATION \
    --type=COMMITMENT_TYPE \
    --resources=vcpu=NUMBER_VCPUS,memory=MEMORY \
    --merge-source-commitments=SOURCE_COMMITMENT_URLS

Replace the following:

  • COMMITMENT_NAME: the name of your new merged commitment.
  • NUMBER_VCPUS: the sum of the numbers of vCPUs in the source commitments.
  • COMMITMENT_TYPE: the same commitment type as your source commitments, one of the following:
    • general-purpose for general purpose N1 machine type commitments
    • general-purpose-n2 for general purpose N2 machine type commitments
    • general-purpose-e2 for general purpose E2 machine type commitments
    • general-purpose-n2d for general purpose N2D machine type commitments
    • general-purpose-t2d for general purpose Tau T2D machine type commitments
    • compute-optimized for compute-optimized C2 machine type commitments
    • compute-optimized-c2d for compute-optimized C2D machine type commitments
    • memory-optimized for memory-optimized M1 or M2 machine type commitments
    • accelerator-optimized for accelerator-optimized A2 machine type commitments
    • accelerator-optimized-a3 for accelerator-optimized A3 machine type commitments
    • graphics-optimized for accelerator-optimized G2 machine type commitments
  • REGION: the same region as your source commitments.
  • PROJECT_ID: the project ID of the project for which you want to merge commitments.
  • DURATION: the same duration (or term) as your source commitments, either 12-month or 36-month.
  • MEMORY: the sum of the amounts, in MB or GB, of memory in the source commitments. For example, 1000 MB. If the units are not specified, the default unit used is GB.
  • SOURCE_COMMITMENT_URLS: Specify a list of distinct source commitment URLs, separating each URL with a comma. Do not add a whitespace between the URLs. In the list, you must specify at least two source commitment URLs.

For example, consider two source commitments in the region us-east1 with their resources as (4 N2 vCPUs and 2048 MB) and (3 N2 vCPUs and 2048 MB) respectively. The duration of each of the source commitments is 12 months. The following gcloud CLI command combines the two commitments and creates a new commitment called merged-commitment, with its resources as 7 N2 vCPUs and 4096 MB and its duration as 12 months:

gcloud compute commitments create merged-commitment \
    --plan=12-month \
    --project=myproject \
    --region=us-east1 \
    --type=general-purpose-n2 \
    --resources=vcpu=7,memory=4096MB \
     --merge-source-commitments=projects/myproject/regions/us-central1/commitments/source-commitment-1,projects/myproject/regions/us-central1/commitments/source-commitment-2

API

To merge existing commitments into a single commitment, use the regionCommitments.insert method.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/commitments
{
  "name": COMMITMENT_NAME,
  "plan": DURATION,
  "type": COMMITMENT_TYPE,
  "region": REGION,
  "resources": [
    {
      "type": "vCPUs",
      "amount": NUMBER_VCPUS
    }
    {
      "type": "MEMORY",
      "amount": MEMORY
    }
  ],
  "mergeSourceCommitments": [SOURCE_COMMITMENT_URL ...]
}

Replace the following:

  • PROJECT_ID: the project ID of the project for which you want to merge commitments.
  • REGION: the same region as your source commitments.
  • COMMITMENT_TYPE: the same commitment type as your source commitments, one of the following:
    • GENERAL_PURPOSE for general purpose N1 machine type commitments
    • GENERAL_PURPOSE_N2 for general purpose N2 machine type commitments
    • GENERAL_PURPOSE_E2 for general purpose E2 machine type commitments
    • GENERAL_PURPOSE_N2D for general purpose N2D machine type commitments
    • GENERAL_PURPOSE_T2D for general purpose Tau T2D machine type commitments
    • COMPUTE_OPTIMIZED for compute-optimized C2 machine type commitments
    • COMPUTE_OPTIMIZED_C2D for compute-optimized C2D machine type commitments
    • MEMORY_OPTIMIZED for memory-optimized M1 or M2 machine type commitments
    • ACCELERATOR_OPTIMIZED for accelerator-optimized A2 machine type commitments
    • ACCELERATOR_OPTIMIZED_A3 for accelerator-optimized A3 machine type commitments
    • GRAPHICS_OPTIMIZED for accelerator-optimized G2 machine type commitments
  • DURATION: the same duration (or term) as your source commitments, either TWELVE_MONTH or THIRTY_SIX_MONTH.
  • COMMITMENT_NAME: the name of your new merged commitment.
  • NUMBER_VCPUS: the sum of the numbers of vCPUs in the source commitments.
  • MEMORY: the sum of the amounts, in MB, of memory in the source commitments. For example, 1000 MB. If the units are not specified, the default unit used is MB.
  • SOURCE_COMMITMENT_URL: the URL of the source commitment that you want to merge. You must specify a comma-separated list of distinct source commitment URLs.

For example, consider two source commitments (source-commitment-1 and source-commitment-2) in the region us-east1 with their resources as (4 N2 vCPUs and 2048 MB) and (3 N2 vCPUs and 2048 MB) respectively. The following POST request merges source-commitment-1 and source-commitment-2 into a single commitment called merged-commitment:

POST https://compute.googleapis.com/compute/v1/projects/myproject/regions/us-central1/commitments
{
  "name": "merged-commitment",
  "plan": "TWELVE_MONTH",
  "type": "GENERAL_PURPOSE_N2",
  "region": "us-east1",
   "resources": [
    {
      "type": "VCPU",
      "amount": "7"
    }
    {
      "type": "MEMORY",
      "amount": "4096"
    }
  ],
  "mergeSourceCommitments": [
         "projects/myproject/regions/us-central1/commitments/source-commitment-1",
         "projects/myproject/regions/us-central1/commitments/source-commitment-2",
         ...
    ]
}

Split commitments

You can transfer resources out of an existing commitment and split the commitment into smaller commitments. Splitting lets you closely monitor and manage portions of one large commitment in the form of smaller individual commitments. For example, you can set only a portion of a commitment to renew automatically by splitting it and enabling automatic renewal for only one of the child commitments. With splitting, you can also distribute your committed use discounts at a more granular level by using prioritized attribution for the split commitments.

Limitations for splitting

  • You can't split license commitments.
  • You can't split commitments that have attached reservations. Consequently, you can't split commitments that have GPUs, Local SSD disks, or both, as commitments with these resources always have attached reservations.
  • At the time of creation of split commitments, you can't create any new reservations and attach them to those commitments.
  • You can't split commitments that have expired or are cancelled.
  • By default, when you create split commitments, the auto-renew setting is disabled on the new commitments even if all the source commitments were set to renew automatically. If you want your split commitments to renew automatically, you must manually enable the auto-renew setting on those commitments. You can do so either at the time of their creation or after their creation.
  • You can create only one new split commitment at a time using the Compute Engine API or the gcloud CLI.

How splitting works

When you split an existing commitment (source commitment), you transfer resources out of your source commitment, create one or more new commitments (split commitments), and redistribute the transferred resources among the new split commitments. Both the activation of the new split commitments and the resizing of the source commitment take place at 12 AM US and Canadian Pacific Time (UTC-8, or UTC-7 during daylight saving time) on the following day. Compute Engine sets this date of activation as the start date for the split commitments. At the completion of the split operation you have the following commitments:

  • The resized source commitment with the resources that remain after the split.
  • The newly created split commitments with the redistributed resources.

The source commitment, although resized, retains all of its other attributes, including its start and expiration dates, and continues to operate normally. The expiration date of the split commitments remains the same as the source commitment.

You can create only one new split commitment at a time by using the Compute Engine API and the gcloud CLI. You can create multiple new split commitments in a single operation by using the Google Cloud console.

You can't split a commitment when it has attached reservations. To learn more about commitments with attached reservations, see Combining reservations with committed use discounts.

Pricing implications for splitting

Your commitment fee is the sum of the discounted prices of all your committed resources. Splitting a commitment affects your resource costs in the following way:

  • Resized source commitment: The discounted prices of the resources from your resized source commitment remain the same.
  • Split commitment: The discounted prices of your newly split commitment's resources might change on the day your split commitment becomes active. This new discounted price for each resource stays the same until the end of your new split commitment's term, even if the on-demand prices change.

However, if you merge or split either of these commitments again in the future, the discounted prices might change again.

Example of a split commitment

The following table shows the commitment properties when an existing commitment (source-commitment) gets split into two distinct commitments (resized source-commitment and split-commitment) on March 1, 2022:

Source commitment
(before split)
Split commitment Source commitment
(after split)
Name source-commitment split-commitment source-commitment
Type N2 N2 N2
Region us-central-1 us-central-1 us-central-1
Resources
  • vCPUs: 200
  • Memory: 200 GB
  • vCPUs: 50
  • Memory: 100 GB
  • vCPUs: 150
  • Memory: 100 GB
Term 3 years 3 years 3 years
Start date* January 1, 2020 March 2, 2022
(the day after the split)
January 1, 2020
End date January 1, 2023 January 1, 2023 January 1, 2023

*All commitments start at 12 AM US and Canadian Pacific Time (UTC-8, or UTC-7) on the specified start date.
All commitments end at 12 AM US and Canadian Pacific Time (UTC-8, or UTC-7) on the specified end date.

Requirements for splitting

When you split a source commitment and create one or more split commitments, your source and split commitments must meet the following requirements:

  • The new split commitments must have the same project, commitment type, region and duration (or term) as the source commitment. However, you must choose new names for your split commitments.
  • The resource types you specify for the new split commitments must match some or all of the resource types in the source commitment. Additionally, the combined amount of resources that you specify for the new split commitments must be a portion of the resources in the source commitment. You have to retain a portion of the resources in your source commitment. For example, suppose your source commitment is for 200 vCPUs and 300 GB memory, the following resize and redistribution scenarios are applicable:
    • You can redistribute a portion of the 200 vCPUs and a portion of the 300 GB memory among your new split commitments.
    • You can redistribute all of the 200 vCPUs, but you must retain a portion of the memory in your source commitment.
    • You can redistribute all of the 300 GB memory but you must retain a portion of the vCPUs in your source commitment.
    • You can't redistribute all of the 200 vCPUs and all of the 300 GB memory among your new split commitments
  • The source and split commitments must be for hardware resources that are vCPUs, memory, or a combination of both.

Additionally, to use the Google Cloud CLI to split a source commitment, update the Google Cloud CLI to version 423.0.0 or later. If you attempt to split a source commitment using an earlier gcloud CLI version, your split operation fails and Compute Engine throws an error.

Create split commitments

Create one new split commitment at a time by using the gcloud CLI or the Compute Engine API. Create multiple new split commitments at a time by using the Google Cloud console. Before you split a commitment, review the limitations for splitting.

Console

  1. In the Google Cloud console, select the project where you want to split a commitment and go to the Committed use discounts page.

    Go to Committed use discounts

  2. To initiate the split operation for a commitment, do either of the following in the Hardware commitments tab of the Commitment list page:

    • Select the commitment that you want to split from the list and click Split.
    • In the Name column, click the name of the commitment that you want to split. On the Hardware commitment details page that opens, click Split.
  3. On the Resize tab of the Split commitment page that opens, do the following:

    1. In the vCPUs and Memory fields, specify the number of vCPUs and memory that you want to retain in your original commitment. The remaining resources are available for redistribution to your split commitment. The source commitment can't be empty after you resize it.
    2. Click Next. The Redistribute tab opens.
  4. On the Redistribute tab of the Split commitment page, do the following:

    1. In the Name field, specify a name for your split commitment.
    2. In the vCPUs and Memory fields, specify the number of vCPUs and memory that you want in your split commitment.
      • If you want to create multiple split commitments, specify only a portion of the redistributed resources.
      • Otherwise, specify all of your redistributed resources.
    3. Optional: To enable auto renew on your split commitment, select the Enable auto renew checkbox.
    4. Click Done.
    5. Optional: To create additional split commitments, click Add an item and repeat the preceding steps.
    6. Click Next. The Review tab opens.
  5. On the Review tab of the Split commitment page, do the following:

    1. Review and confirm the details of the resized commitment and the split commitments.
      • To modify the resource allocation from your original commitment, select the Resize tab on the left side of the window and repeat step 3.
      • To modify your resource redistribution among your split commitments, select the Redistribute tab on the left side of the window and repeat step 4.
    2. Read the Terms and conditions.
    3. To finish creating your split commitments and return to the Commitment list page, click Submit.

gcloud

To split an existing commitment into two commitments, use the gcloud compute commitments create command with the --split-source-commitment flag.

gcloud compute commitments create COMMITMENT_NAME \
    --region=REGION \
    --project=PROJECT_ID \
    --plan=DURATION \
    --type=COMMITMENT_TYPE \
    --resources=vcpu=NUMBER_VCPUS,memory=MEMORY \
    --split-source-commitment=SOURCE_COMMITMENT_URL

Replace the following:

  • COMMITMENT_NAME: the name of your new split commitment.
  • COMMITMENT_TYPE: the same commitment type as your source commitment, one of the following:
    • general-purpose for general purpose N1 machine type commitments
    • general-purpose-n2 for general purpose N2 machine type commitments
    • general-purpose-e2 for general purpose E2 machine type commitments
    • general-purpose-n2d for general purpose N2D machine type commitments
    • general-purpose-t2d for general purpose Tau T2D machine type commitments
    • compute-optimized for compute-optimized C2 machine type commitments
    • compute-optimized-c2d for compute-optimized C2D machine type commitments
    • memory-optimized for memory-optimized M1 or M2 machine type commitments
    • accelerator-optimized for accelerator-optimized A2 machine type commitments
    • accelerator-optimized-a3 for accelerator-optimized A3 machine type commitments
    • graphics-optimized for accelerator-optimized G2 machine type commitments
  • REGION: the same region as your source commitment.
  • PROJECT_ID: the project ID of the project for which you want to split the source commitment.
  • DURATION: the same duration (or term) as your source commitment, either 12-month or 36-month.
  • NUMBER_VCPUS: the number of vCPUs you want to transfer out of your source commitment to create your new split commitment. The number must be an integer less than the number of vCPUs in the source commitment.
  • MEMORY: the amount, in MB or GB, of memory that you want to transfer out of your source commitment to create your new split commitment. The amount must be less than the amount of memory in the source commitment. For example, 1000 MB. If the units are not specified, the default unit used is GB. Memory can be purchased in increments of 0.25 GB.
  • SOURCE_COMMITMENT_URL: the URL of the source commitment from which you want to carve out resources.

For example, consider a source commitment (source-commitment) in the region us-east1 with 3 N2 vCPUs and 2048 MB memory. The following gcloud CLI command splits the commitment by doing the following:

  • Taking resources from source-commitment and creating a new commitment split-commitment with 1 N2 vCPU and 1024 MB memory.
  • Resizing source-commitment to the remaining resources.
gcloud compute commitments create split-commitment \
    --plan=12-month \
    --type=general-purpose-n2 \
    --region=us-east1 \
    --project=myproject \
    --resources vcpu=1,memory=1024MB \
    --split-source-commitment=projects/myproject/regions/us-central1/commitments/source-commitment

API

To split an existing commitment into two commitments, use the regionCommitments.insert method.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/commitments
{
  "name": COMMITMENT_NAME,
  "plan": DURATION,
  "type": COMMITMENT_TYPE,
  "region": REGION,
  "resources": [
    {
      "type": "vCPUs",
      "amount": NUMBER_VCPUS
    }
    {
      "type": "MEMORY",
      "amount": MEMORY
    }
  ],
  "splitSourceCommitment": SOURCE_COMMITMENT_URL
}

Replace the following:

  • PROJECT_ID: the project ID of the project for which you want to split the source commitment.
  • REGION: the same region as your source commitment.
  • COMMITMENT_NAME: the name of your new split commitment.
  • COMMITMENT_TYPE: the same commitment type as your source commitment, one of the following:
    • GENERAL_PURPOSE for general purpose N1 machine type commitments
    • GENERAL_PURPOSE_N2 for general purpose N2 machine type commitments
    • GENERAL_PURPOSE_E2 for general purpose E2 machine type commitments
    • GENERAL_PURPOSE_N2D for general purpose N2D machine type commitments
    • GENERAL_PURPOSE_T2D for general purpose Tau T2D machine type commitments
    • COMPUTE_OPTIMIZED for compute-optimized C2 machine type commitments
    • COMPUTE_OPTIMIZED_C2D for compute-optimized C2D machine type commitments
    • MEMORY_OPTIMIZED for memory-optimized M1 or M2 machine type commitments
    • ACCELERATOR_OPTIMIZED for accelerator-optimized A2 machine type commitments
    • ACCELERATOR_OPTIMIZED_A3 for the accelerator-optimized A3 machine type commitments
    • GRAPHICS_OPTIMIZED for accelerator-optimized G2 machine type commitments
  • DURATION: the same duration (or term) as your source commitment, either TWELVE_MONTH or THIRTY_SIX_MONTH.
  • NUMBER_VCPUS: the number of vCPUs you want to transfer out of your source commitment to create your new split commitment. The number must be an integer less than the number of vCPUs in the source commitment.
  • MEMORY: the amount, in MB, of memory that you want to transfer out of your source commitment to create your new split commitment. The amount must be less than the amount of memory in the source commitment. For example, 1000 MB. If the units are not specified, the default unit used is MB. Memory can be purchased in increments of 0.25 GB.
  • SOURCE_COMMITMENT_URL: the URL of the source commitment from which you want to transfer resources.

For example, consider a source commitment (source-commitment) in the region us-east1 with 3 N2 vCPUs and 2048 MB memory. The following POST request splits the commitment by doing the following:

  • Taking resources from source-commitment and creating a new commitment split-commitment with 1 N2 vCPU and 1024 MB memory.
  • Resizing source-commitment to the remaining resources.
POST https://compute.googleapis.com/compute/v1/projects/myproject/regions/us-central1/commitments
{
  "name": "split-commitment",
  "plan": "TWELVE_MONTH",
  "type": "GENERAL_PURPOSE_N2",
  "region": "us-east1",
  "resources": [
    {
      "type": "VCPU",
      "amount": "1"
    }
    {
      "type": "MEMORY",
      "amount": "1024"
    }
  ],
  "splitSourceCommitment": "projects/myproject/regions/us-central1/commitments/source-commitment"
}

What's next