Merge and split commitments

Stay organized with collections Save and categorize content based on your preferences.

To help you manage the resource requirements for your projects, Compute Engine allows you to 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.

Limitations

  • You can't merge commitments using the Google Cloud console.
  • You can't merge or split license commitments.
  • You can't split commitments when they have attached reservations.
  • You can't split commitments for GPUs and/or local SSDs as these resources must have reservations attached to them at all times.
  • At the time of creation of merged or split commitments, you can't create any new reservations and attach them to those commitments.
  • You can't merge or split commitments that have expired or are cancelled.
  • By default, when you create merged or 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 merged or 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 Google Cloud console or the gcloud CLI.

Merging 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 allows you to 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.

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) 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. The expiration date for the merged commitment is set to whichever expiration date among the source commitments is furthest in the future. For example, if you have two source commitments and they expire in January 2023 and December 2023 respectively, then the merged commitment expires in December 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.

The following table shows an example where two existing commitments (source-commitment-1 and source-commitment-2) are merged into a single commitment (merged-commitment) on March 1, 2022:

First source commitment Second source commitment 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

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 SSDs).

Create merged commitments

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

gcloud

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

gcloud alpha compute commitments create COMMITMENT_NAME \
    --region=REGION \
    --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 the memory-optimized M1 or M2 machine type commitments
    • accelerator-optimized for the accelerator-optimized machine type commitments
  • REGION: the same region as your source 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 with their resources as (4 vCPUs and 2048 MB) and (3 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 merged commitment with its resources as 7 vCPUs and 4096 MB and its duration as 12 months:

gcloud alpha compute commitments create merged-commitment \
    --plan=12-month \
    --resources=vcpu=7,memory=4096 \
     --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/alpha/projects/PROJECT_ID/regions/REGION/commitments
{
  "name": COMMITMENT_NAME,
  "plan": DURATION,
  "type" COMMITMENT_TYPE,
  "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 that you want to merge the commitments for.
  • 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
    • cCOMPUTE_OPTIMIZED_C2D for compute-optimized C2D machine type commitments
    • MEMORY_OPTIMIZED for the memory-optimized M1 or M2 machine type commitments
    • ACCELERATOR_OPTIMIZED for the accelerator-optimized 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 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_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) with their resources as (4 vCPUs and 2048 MB) and (3 vCPUs and 2048 MB) respectively. The following Compute Engine API request merges source-commitment-1 and source-commitment-2 into a single commitment (merged-commitment):

POST https://compute.googleapis.com/compute/alpha/projects/myproject/regions/us-central1/commitments
{
  "name": "merged-commitment",
  "plan": "TWELVE_MONTH",
   "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",
         ...
    ]
}

Splitting commitments

You can transfer resources out of an existing commitment and split the commitment into smaller commitments. Splitting allows you to 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. You can also use the splitting functionality in conjunction with prioritized attribution of commitments to decide how you want to distribute your committed use discounts at a more granular level.

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-7 or UTC-8) on the following day. This date of activation gets set as the start date for the split commitments. At this point, the split operation ends and 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 will be the same as the source commitment.

You can create only one new split commitment at a time by using the Google Cloud console 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.

The following table shows an example where an existing commitment (source-commitment) get split into two distinct commitments (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

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 (vCPUs, memory, GPUs, and local SSDs).

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.

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 from the list and click Split.
    • Click on the commitment's name and then, on the Hardware commitment details page, click Split.
  3. On the Resize tab of the Split commitment page, 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.
  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.
  5. On the Review tab of the Split commitment page, do the following:

    • Review the 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.
    • Read the Terms and conditions.
    • 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 \
    --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 the memory-optimized M1 or M2 machine type commitments
    • accelerator-optimized for the accelerator-optimized machine type commitments
  • REGION: the same region as your 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 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) with 3 vCPUs and 2048 MB memory. The following gcloud CLI command takes resources from source-commitment, creates a split commitment (split-commitment) with 1vCPU and 1024 MB memory, and resizes source-commitment to the remaining resources.

gcloud compute commitments create split-commitment \
    --plan=12-month\
    --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,
  "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 that you want to split the source commitment for.
  • 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 the memory-optimized M1 or M2 machine type commitments
    • ACCELERATOR_OPTIMIZED for the accelerator-optimized 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 or GB, of memory 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 transfer resources.

For example, consider a source commitment (source-commitment) with 3 vCPUs and 2048 MB memory. The following Compute Engine API request takes resources from source-commitment, creates a split commitment (split-commitment) with 1vCPU and 1024 MB memory, and resizes 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",
  "resources": [
    {
      "type": "VCPU",
      "amount": "1"
    }
    {
      "type": "MEMORY",
      "amount": "1024"
    }
  ],
  "splitSourceCommitment": "projects/myproject/regions/us-central1/commitments/source-commitment"
}