commitments

Creates, updates, deletes, gets or lists a commitments resource.

Overview

Name	commitments
Type	Resource
Id	google.compute.commitments

Fields

The following fields are returned by SELECT queries:

get

Successful response

Name	Datatype	Description
id	string (uint64)	[Output Only] The unique identifier for the resource. This identifier is defined by the server.
name	string	Name of the commitment. You must specify a name when you purchase the commitment. The name must be 1-63 characters long, and comply with RFC1035. Specifically, the name must be 1-63 characters long and match the regular expression [a-z]([-a-z0-9]*[a-z0-9])? which means the first character must be a lowercase letter, and all following characters must be a dash, lowercase letter, or digit, except the last character, which cannot be a dash. (pattern: a-z?)
autoRenew	boolean	Specifies whether to automatically renew the commitment at the end of its current term. The default value is false. If you set the field to true, each time your commitment reaches the end of its term, Compute Engine automatically renews it for another term. You can update this field anytime before the commitment expires. For example, if the commitment is set to expire at 12 AM UTC-8 on January 3, 2027, you can update this field until 11:59 PM UTC-8 on January 2, 2027.
category	string	The category of the commitment; specifies whether the commitment is for hardware or software resources. Category MACHINE specifies that you are committing to hardware machine resources such as VCPU or MEMORY, listed in resources. Category LICENSE specifies that you are committing to software licenses, listed in licenseResources. Note that if you specify MACHINE commitments, then you must also specify a type to indicate the machine series of the hardware resource that you are committing to.
creationTimestamp	string	[Output Only] Creation timestamp in RFC3339 text format.
customEndTimestamp	string	[Input Only] Optional, specifies the requested commitment end time in RFC3339 text format. Use this option when the desired commitment's end date is later than the start date + term duration.
description	string	An optional description of the commitment. You can provide this property when you create the resource.
endTimestamp	string	[Output Only] Commitment end time in RFC3339 text format.
existingReservations	array
kind	string	[Output Only] Type of the resource. Always compute#commitment for commitments. (default: compute#commitment)
licenseResource	object	The license specification required as part of a license commitment. (id: LicenseResourceCommitment)
mergeSourceCommitments	array	The list of source commitments that you are merging to create the new merged commitment. For more information, see Merging commitments.
plan	string	The minimum time duration that you commit to purchasing resources. The plan that you choose determines the preset term length of the commitment (which is 1 year or 3 years) and affects the discount rate that you receive for your resources. Committing to a longer time duration typically gives you a higher discount rate. The supported values for this field are TWELVE_MONTH (1 year), and THIRTY_SIX_MONTH (3 years).
region	string	[Output Only] URL of the region where the commitment and committed resources are located.
reservations	array	The list of new reservations that you want to create and attach to this commitment. You must attach reservations to your commitment if your commitment specifies any GPUs or Local SSD disks. For more information, see Attach reservations to resource-based commitments. Specify this property only if you want to create new reservations to attach. To attach existing reservations, specify the existingReservations property instead.
resourceStatus	object	[Output Only] Status information for Commitment resource. (id: CommitmentResourceStatus)
resources	array	The list of all the hardware resources, with their types and amounts, that you want to commit to. Specify as a separate entry in the list for each individual resource type.
selfLink	string	[Output Only] Server-defined URL for the resource.
splitSourceCommitment	string	The source commitment from which you are transferring resources to create the new split commitment. For more information, see Split commitments.
startTimestamp	string	[Output Only] Commitment start time in RFC3339 text format.
status	string	[Output Only] Status of the commitment with regards to eventual expiration (each commitment has an end date defined). Status can be one of the following values: NOT_YET_ACTIVE, ACTIVE, or EXPIRED.
statusMessage	string	[Output Only] An optional, human-readable explanation of the status.
type	string	The type of commitment; specifies the machine series for which you want to commit to purchasing resources. The choice of machine series affects the discount rate and the eligible resource types. The type must be one of the following: ACCELERATOR_OPTIMIZED, ACCELERATOR_OPTIMIZED_A3, ACCELERATOR_OPTIMIZED_A3_MEGA, COMPUTE_OPTIMIZED, COMPUTE_OPTIMIZED_C2D, COMPUTE_OPTIMIZED_C3, COMPUTE_OPTIMIZED_C3D, COMPUTE_OPTIMIZED_H3, GENERAL_PURPOSE, GENERAL_PURPOSE_C4, GENERAL_PURPOSE_E2, GENERAL_PURPOSE_N2, GENERAL_PURPOSE_N2D, GENERAL_PURPOSE_N4, GENERAL_PURPOSE_T2D, GRAPHICS_OPTIMIZED, MEMORY_OPTIMIZED, MEMORY_OPTIMIZED_M3, MEMORY_OPTIMIZED_X4, STORAGE_OPTIMIZED_Z3. For example, type MEMORY_OPTIMIZED specifies a commitment that applies only to eligible resources of memory optimized M1 and M2 machine series. Type GENERAL_PURPOSE specifies a commitment that applies only to eligible resources of general purpose N1 machine series.

list

Successful response

Name	Datatype	Description
id	string	[Output Only] Unique identifier for the resource; defined by the server.
items	array	A list of Commitment resources.
kind	string	[Output Only] Type of resource. Always compute#commitmentList for lists of commitments. (default: compute#commitmentList)
nextPageToken	string	[Output Only] This token allows you to get the next page of results for list requests. If the number of results is larger than maxResults, use the nextPageToken as a value for the query parameter pageToken in the next list request. Subsequent list requests will have their own nextPageToken to continue paging through the results.
selfLink	string	[Output Only] Server-defined URL for this resource.
warning	object	[Output Only] Informational warning message.

aggregated_list

Successful response

Name	Datatype	Description
id	string (uint64)	[Output Only] The unique identifier for the resource. This identifier is defined by the server.
name	string	Name of the commitment. You must specify a name when you purchase the commitment. The name must be 1-63 characters long, and comply with RFC1035. Specifically, the name must be 1-63 characters long and match the regular expression [a-z]([-a-z0-9]*[a-z0-9])? which means the first character must be a lowercase letter, and all following characters must be a dash, lowercase letter, or digit, except the last character, which cannot be a dash. (pattern: a-z?)
autoRenew	boolean	Specifies whether to automatically renew the commitment at the end of its current term. The default value is false. If you set the field to true, each time your commitment reaches the end of its term, Compute Engine automatically renews it for another term. You can update this field anytime before the commitment expires. For example, if the commitment is set to expire at 12 AM UTC-8 on January 3, 2027, you can update this field until 11:59 PM UTC-8 on January 2, 2027.
category	string	The category of the commitment; specifies whether the commitment is for hardware or software resources. Category MACHINE specifies that you are committing to hardware machine resources such as VCPU or MEMORY, listed in resources. Category LICENSE specifies that you are committing to software licenses, listed in licenseResources. Note that if you specify MACHINE commitments, then you must also specify a type to indicate the machine series of the hardware resource that you are committing to.
creationTimestamp	string	[Output Only] Creation timestamp in RFC3339 text format.
customEndTimestamp	string	[Input Only] Optional, specifies the requested commitment end time in RFC3339 text format. Use this option when the desired commitment's end date is later than the start date + term duration.
description	string	An optional description of the commitment. You can provide this property when you create the resource.
endTimestamp	string	[Output Only] Commitment end time in RFC3339 text format.
existingReservations	array
kind	string	[Output Only] Type of the resource. Always compute#commitment for commitments. (default: compute#commitment)
licenseResource	object	The license specification required as part of a license commitment. (id: LicenseResourceCommitment)
mergeSourceCommitments	array	The list of source commitments that you are merging to create the new merged commitment. For more information, see Merging commitments.
plan	string	The minimum time duration that you commit to purchasing resources. The plan that you choose determines the preset term length of the commitment (which is 1 year or 3 years) and affects the discount rate that you receive for your resources. Committing to a longer time duration typically gives you a higher discount rate. The supported values for this field are TWELVE_MONTH (1 year), and THIRTY_SIX_MONTH (3 years).
region	string	[Output Only] URL of the region where the commitment and committed resources are located.
reservations	array	The list of new reservations that you want to create and attach to this commitment. You must attach reservations to your commitment if your commitment specifies any GPUs or Local SSD disks. For more information, see Attach reservations to resource-based commitments. Specify this property only if you want to create new reservations to attach. To attach existing reservations, specify the existingReservations property instead.
resourceStatus	object	[Output Only] Status information for Commitment resource. (id: CommitmentResourceStatus)
resources	array	The list of all the hardware resources, with their types and amounts, that you want to commit to. Specify as a separate entry in the list for each individual resource type.
selfLink	string	[Output Only] Server-defined URL for the resource.
splitSourceCommitment	string	The source commitment from which you are transferring resources to create the new split commitment. For more information, see Split commitments.
startTimestamp	string	[Output Only] Commitment start time in RFC3339 text format.
status	string	[Output Only] Status of the commitment with regards to eventual expiration (each commitment has an end date defined). Status can be one of the following values: NOT_YET_ACTIVE, ACTIVE, or EXPIRED.
statusMessage	string	[Output Only] An optional, human-readable explanation of the status.
type	string	The type of commitment; specifies the machine series for which you want to commit to purchasing resources. The choice of machine series affects the discount rate and the eligible resource types. The type must be one of the following: ACCELERATOR_OPTIMIZED, ACCELERATOR_OPTIMIZED_A3, ACCELERATOR_OPTIMIZED_A3_MEGA, COMPUTE_OPTIMIZED, COMPUTE_OPTIMIZED_C2D, COMPUTE_OPTIMIZED_C3, COMPUTE_OPTIMIZED_C3D, COMPUTE_OPTIMIZED_H3, GENERAL_PURPOSE, GENERAL_PURPOSE_C4, GENERAL_PURPOSE_E2, GENERAL_PURPOSE_N2, GENERAL_PURPOSE_N2D, GENERAL_PURPOSE_N4, GENERAL_PURPOSE_T2D, GRAPHICS_OPTIMIZED, MEMORY_OPTIMIZED, MEMORY_OPTIMIZED_M3, MEMORY_OPTIMIZED_X4, STORAGE_OPTIMIZED_Z3. For example, type MEMORY_OPTIMIZED specifies a commitment that applies only to eligible resources of memory optimized M1 and M2 machine series. Type GENERAL_PURPOSE specifies a commitment that applies only to eligible resources of general purpose N1 machine series.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	project, region, commitment		Returns the specified commitment resource.
list	select	project, region	filter, maxResults, orderBy, pageToken, returnPartialSuccess	Retrieves a list of commitments contained within the specified region.
aggregated_list	select	project	filter, includeAllScopes, maxResults, orderBy, pageToken, returnPartialSuccess, serviceProjectNumber	Retrieves an aggregated list of commitments by region. To prevent failure, Google recommends that you set the returnPartialSuccess parameter to true.
insert	insert	project, region	requestId	Creates a commitment in the specified project using the data included in the request.
update	update	project, region, commitment	paths, requestId, updateMask	Updates the specified commitment with the data included in the request. Update is performed only on selected fields included as part of update-mask. Only the following fields can be updated: auto_renew and plan.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
commitment	string
project	string
region	string
filter	string
includeAllScopes	boolean
maxResults	integer (uint32)
orderBy	string
pageToken	string
paths	string
requestId	string
returnPartialSuccess	boolean
serviceProjectNumber	string (int64)
updateMask	string (google-fieldmask)

SELECT examples

get

Returns the specified commitment resource.

SELECT
id,
name,
autoRenew,
category,
creationTimestamp,
customEndTimestamp,
description,
endTimestamp,
existingReservations,
kind,
licenseResource,
mergeSourceCommitments,
plan,
region,
reservations,
resourceStatus,
resources,
selfLink,
splitSourceCommitment,
startTimestamp,
status,
statusMessage,
type
FROM google.compute.commitments
WHERE project = '{{ project }}' -- required
AND region = '{{ region }}' -- required
AND commitment = '{{ commitment }}' -- required;

list

Retrieves a list of commitments contained within the specified region.

SELECT
id,
items,
kind,
nextPageToken,
selfLink,
warning
FROM google.compute.commitments
WHERE project = '{{ project }}' -- required
AND region = '{{ region }}' -- required
AND filter = '{{ filter }}'
AND maxResults = '{{ maxResults }}'
AND orderBy = '{{ orderBy }}'
AND pageToken = '{{ pageToken }}'
AND returnPartialSuccess = '{{ returnPartialSuccess }}';

aggregated_list

Retrieves an aggregated list of commitments by region. To prevent failure, Google recommends that you set the returnPartialSuccess parameter to true.

SELECT
id,
name,
autoRenew,
category,
creationTimestamp,
customEndTimestamp,
description,
endTimestamp,
existingReservations,
kind,
licenseResource,
mergeSourceCommitments,
plan,
region,
reservations,
resourceStatus,
resources,
selfLink,
splitSourceCommitment,
startTimestamp,
status,
statusMessage,
type
FROM google.compute.commitments
WHERE project = '{{ project }}' -- required
AND filter = '{{ filter }}'
AND includeAllScopes = '{{ includeAllScopes }}'
AND maxResults = '{{ maxResults }}'
AND orderBy = '{{ orderBy }}'
AND pageToken = '{{ pageToken }}'
AND returnPartialSuccess = '{{ returnPartialSuccess }}'
AND serviceProjectNumber = '{{ serviceProjectNumber }}';

INSERT examples

insert

Creates a commitment in the specified project using the data included in the request.

INSERT INTO google.compute.commitments (
data__kind,
data__id,
data__creationTimestamp,
data__name,
data__description,
data__region,
data__selfLink,
data__status,
data__statusMessage,
data__plan,
data__startTimestamp,
data__endTimestamp,
data__category,
data__resources,
data__type,
data__reservations,
data__licenseResource,
data__autoRenew,
data__mergeSourceCommitments,
data__splitSourceCommitment,
data__resourceStatus,
data__existingReservations,
data__customEndTimestamp,
project,
region,
requestId
)
SELECT 
'{{ kind }}',
'{{ id }}',
'{{ creationTimestamp }}',
'{{ name }}',
'{{ description }}',
'{{ region }}',
'{{ selfLink }}',
'{{ status }}',
'{{ statusMessage }}',
'{{ plan }}',
'{{ startTimestamp }}',
'{{ endTimestamp }}',
'{{ category }}',
'{{ resources }}',
'{{ type }}',
'{{ reservations }}',
'{{ licenseResource }}',
{{ autoRenew }},
'{{ mergeSourceCommitments }}',
'{{ splitSourceCommitment }}',
'{{ resourceStatus }}',
'{{ existingReservations }}',
'{{ customEndTimestamp }}',
'{{ project }}',
'{{ region }}',
'{{ requestId }}'
RETURNING
id,
name,
clientOperationId,
creationTimestamp,
description,
endTime,
error,
httpErrorMessage,
httpErrorStatusCode,
insertTime,
instancesBulkInsertOperationMetadata,
kind,
operationGroupId,
operationType,
progress,
region,
selfLink,
setCommonInstanceMetadataOperationMetadata,
startTime,
status,
statusMessage,
targetId,
targetLink,
user,
warnings,
zone
;

Manifest

# Description fields are for documentation purposes
- name: commitments
  props:
    - name: project
      value: string
      description: Required parameter for the commitments resource.
    - name: region
      value: string
      description: Required parameter for the commitments resource.
    - name: kind
      value: string
      description: >
        [Output Only] Type of the resource. Always compute#commitment for commitments.
        
      default: compute#commitment
    - name: id
      value: string
      description: >
        [Output Only] The unique identifier for the resource. This identifier is defined by the server.
        
    - name: creationTimestamp
      value: string
      description: >
        [Output Only] Creation timestamp in RFC3339 text format.
        
    - name: name
      value: string
      description: >
        Name of the commitment. You must specify a name when you purchase the commitment. The name must be 1-63 characters long, and comply with RFC1035. Specifically, the name must be 1-63 characters long and match the regular expression `[a-z]([-a-z0-9]*[a-z0-9])?` which means the first character must be a lowercase letter, and all following characters must be a dash, lowercase letter, or digit, except the last character, which cannot be a dash.
        
    - name: description
      value: string
      description: >
        An optional description of the commitment. You can provide this property when you create the resource.
        
    - name: region
      value: string
      description: >
        [Output Only] URL of the region where the commitment and committed resources are located.
        
    - name: selfLink
      value: string
      description: >
        [Output Only] Server-defined URL for the resource.
        
    - name: status
      value: string
      description: >
        [Output Only] Status of the commitment with regards to eventual expiration (each commitment has an end date defined). Status can be one of the following values: NOT_YET_ACTIVE, ACTIVE, or EXPIRED.
        
      valid_values: ['ACTIVE', 'CANCELLED', 'CREATING', 'EXPIRED', 'NOT_YET_ACTIVE']
    - name: statusMessage
      value: string
      description: >
        [Output Only] An optional, human-readable explanation of the status.
        
    - name: plan
      value: string
      description: >
        The minimum time duration that you commit to purchasing resources. The plan that you choose determines the preset term length of the commitment (which is 1 year or 3 years) and affects the discount rate that you receive for your resources. Committing to a longer time duration typically gives you a higher discount rate. The supported values for this field are TWELVE_MONTH (1 year), and THIRTY_SIX_MONTH (3 years).
        
      valid_values: ['INVALID', 'THIRTY_SIX_MONTH', 'TWELVE_MONTH']
    - name: startTimestamp
      value: string
      description: >
        [Output Only] Commitment start time in RFC3339 text format.
        
    - name: endTimestamp
      value: string
      description: >
        [Output Only] Commitment end time in RFC3339 text format.
        
    - name: category
      value: string
      description: >
        The category of the commitment; specifies whether the commitment is for hardware or software resources. Category MACHINE specifies that you are committing to hardware machine resources such as VCPU or MEMORY, listed in resources. Category LICENSE specifies that you are committing to software licenses, listed in licenseResources. Note that if you specify MACHINE commitments, then you must also specify a type to indicate the machine series of the hardware resource that you are committing to.
        
      valid_values: ['CATEGORY_UNSPECIFIED', 'LICENSE', 'MACHINE']
    - name: resources
      value: array
      description: >
        The list of all the hardware resources, with their types and amounts, that you want to commit to. Specify as a separate entry in the list for each individual resource type.
        
    - name: type
      value: string
      description: >
        The type of commitment; specifies the machine series for which you want to commit to purchasing resources. The choice of machine series affects the discount rate and the eligible resource types. The type must be one of the following: ACCELERATOR_OPTIMIZED, ACCELERATOR_OPTIMIZED_A3, ACCELERATOR_OPTIMIZED_A3_MEGA, COMPUTE_OPTIMIZED, COMPUTE_OPTIMIZED_C2D, COMPUTE_OPTIMIZED_C3, COMPUTE_OPTIMIZED_C3D, COMPUTE_OPTIMIZED_H3, GENERAL_PURPOSE, GENERAL_PURPOSE_C4, GENERAL_PURPOSE_E2, GENERAL_PURPOSE_N2, GENERAL_PURPOSE_N2D, GENERAL_PURPOSE_N4, GENERAL_PURPOSE_T2D, GRAPHICS_OPTIMIZED, MEMORY_OPTIMIZED, MEMORY_OPTIMIZED_M3, MEMORY_OPTIMIZED_X4, STORAGE_OPTIMIZED_Z3. For example, type MEMORY_OPTIMIZED specifies a commitment that applies only to eligible resources of memory optimized M1 and M2 machine series. Type GENERAL_PURPOSE specifies a commitment that applies only to eligible resources of general purpose N1 machine series.
        
      valid_values: ['ACCELERATOR_OPTIMIZED', 'ACCELERATOR_OPTIMIZED_A3', 'ACCELERATOR_OPTIMIZED_A3_MEGA', 'ACCELERATOR_OPTIMIZED_A3_ULTRA', 'ACCELERATOR_OPTIMIZED_A4', 'COMPUTE_OPTIMIZED', 'COMPUTE_OPTIMIZED_C2D', 'COMPUTE_OPTIMIZED_C3', 'COMPUTE_OPTIMIZED_C3D', 'COMPUTE_OPTIMIZED_H3', 'COMPUTE_OPTIMIZED_H4D', 'GENERAL_PURPOSE', 'GENERAL_PURPOSE_C4', 'GENERAL_PURPOSE_C4A', 'GENERAL_PURPOSE_C4D', 'GENERAL_PURPOSE_E2', 'GENERAL_PURPOSE_N2', 'GENERAL_PURPOSE_N2D', 'GENERAL_PURPOSE_N4', 'GENERAL_PURPOSE_T2D', 'GRAPHICS_OPTIMIZED', 'MEMORY_OPTIMIZED', 'MEMORY_OPTIMIZED_M3', 'MEMORY_OPTIMIZED_M4', 'MEMORY_OPTIMIZED_M4_6TB', 'MEMORY_OPTIMIZED_X4_16TB', 'MEMORY_OPTIMIZED_X4_24TB', 'MEMORY_OPTIMIZED_X4_32TB', 'STORAGE_OPTIMIZED_Z3', 'TYPE_UNSPECIFIED']
    - name: reservations
      value: array
      description: >
        The list of new reservations that you want to create and attach to this commitment. You must attach reservations to your commitment if your commitment specifies any GPUs or Local SSD disks. For more information, see Attach reservations to resource-based commitments. Specify this property only if you want to create new reservations to attach. To attach existing reservations, specify the existingReservations property instead.
        
    - name: licenseResource
      value: object
      description: >
        The license specification required as part of a license commitment.
        
    - name: autoRenew
      value: boolean
      description: >
        Specifies whether to automatically renew the commitment at the end of its current term. The default value is false. If you set the field to true, each time your commitment reaches the end of its term, Compute Engine automatically renews it for another term. You can update this field anytime before the commitment expires. For example, if the commitment is set to expire at 12 AM UTC-8 on January 3, 2027, you can update this field until 11:59 PM UTC-8 on January 2, 2027.
        
    - name: mergeSourceCommitments
      value: array
      description: >
        The list of source commitments that you are merging to create the new merged commitment. For more information, see Merging commitments.
        
    - name: splitSourceCommitment
      value: string
      description: >
        The source commitment from which you are transferring resources to create the new split commitment. For more information, see Split commitments.
        
    - name: resourceStatus
      value: object
      description: >
        [Output Only] Status information for Commitment resource.
        
    - name: existingReservations
      value: array
    - name: customEndTimestamp
      value: string
      description: >
        [Input Only] Optional, specifies the requested commitment end time in RFC3339 text format. Use this option when the desired commitment's end date is later than the start date + term duration.
        
    - name: requestId
      value: string

UPDATE examples

update

Updates the specified commitment with the data included in the request. Update is performed only on selected fields included as part of update-mask. Only the following fields can be updated: auto_renew and plan.

UPDATE google.compute.commitments
SET 
data__kind = '{{ kind }}',
data__id = '{{ id }}',
data__creationTimestamp = '{{ creationTimestamp }}',
data__name = '{{ name }}',
data__description = '{{ description }}',
data__region = '{{ region }}',
data__selfLink = '{{ selfLink }}',
data__status = '{{ status }}',
data__statusMessage = '{{ statusMessage }}',
data__plan = '{{ plan }}',
data__startTimestamp = '{{ startTimestamp }}',
data__endTimestamp = '{{ endTimestamp }}',
data__category = '{{ category }}',
data__resources = '{{ resources }}',
data__type = '{{ type }}',
data__reservations = '{{ reservations }}',
data__licenseResource = '{{ licenseResource }}',
data__autoRenew = {{ autoRenew }},
data__mergeSourceCommitments = '{{ mergeSourceCommitments }}',
data__splitSourceCommitment = '{{ splitSourceCommitment }}',
data__resourceStatus = '{{ resourceStatus }}',
data__existingReservations = '{{ existingReservations }}',
data__customEndTimestamp = '{{ customEndTimestamp }}'
WHERE 
project = '{{ project }}' --required
AND region = '{{ region }}' --required
AND commitment = '{{ commitment }}' --required
AND paths = '{{ paths}}'
AND requestId = '{{ requestId}}'
AND updateMask = '{{ updateMask}}'
RETURNING
id,
name,
clientOperationId,
creationTimestamp,
description,
endTime,
error,
httpErrorMessage,
httpErrorStatusCode,
insertTime,
instancesBulkInsertOperationMetadata,
kind,
operationGroupId,
operationType,
progress,
region,
selfLink,
setCommonInstanceMetadataOperationMetadata,
startTime,
status,
statusMessage,
targetId,
targetLink,
user,
warnings,
zone;