reservations

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

Overview

Name	reservations
Type	Resource
Id	google.compute.reservations

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	The name of the resource, provided by the client when initially creating the resource. The resource 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?)
advancedDeploymentControl	object	Advanced control for cluster management, applicable only to DENSE deployment type reservations. (id: ReservationAdvancedDeploymentControl)
aggregateReservation	object	Reservation for aggregated resources, providing shape flexibility. (id: AllocationAggregateReservation)
commitment	string	[Output Only] Full or partial URL to a parent commitment. This field displays for reservations that are tied to a commitment.
creationTimestamp	string	[Output Only] Creation timestamp in RFC3339 text format.
deleteAfterDuration	object	Duration time relative to reservation creation when Compute Engine will automatically delete this resource. (id: Duration)
deleteAtTime	string	Absolute time in future when the reservation will be auto-deleted by Compute Engine. Timestamp is represented in RFC3339 text format.
deploymentType	string	Specifies the deployment strategy for this reservation.
description	string	An optional description of this resource. Provide this property when you create the resource.
enableEmergentMaintenance	boolean	Indicates whether Compute Engine allows unplanned maintenance for your VMs; for example, to fix hardware errors.
kind	string	[Output Only] Type of the resource. Always compute#reservations for reservations. (default: compute#reservation)
linkedCommitments	array	[Output Only] Full or partial URL to parent commitments. This field displays for reservations that are tied to multiple commitments.
reservationSharingPolicy	object	Specify the reservation sharing policy. If unspecified, the reservation will not be shared with Google Cloud managed services. (id: AllocationReservationSharingPolicy)
resourcePolicies	object	Resource policies to be added to this reservation. The key is defined by user, and the value is resource policy url. This is to define placement policy with reservation.
resourceStatus	object	[Output Only] Status information for Reservation resource. (id: AllocationResourceStatus)
satisfiesPzs	boolean	[Output Only] Reserved for future use.
schedulingType	string	The type of maintenance for the reservation.
selfLink	string	[Output Only] Server-defined fully-qualified URL for this resource.
shareSettings	object	Specify share-settings to create a shared reservation. This property is optional. For more information about the syntax and options for this field and its subfields, see the guide for creating a shared reservation. (id: ShareSettings)
specificReservation	object	Reservation for instances with specific machine shapes. (id: AllocationSpecificSKUReservation)
specificReservationRequired	boolean	Indicates whether the reservation can be consumed by VMs with affinity for "any" reservation. If the field is set, then only VMs that target the reservation by name can consume from this reservation.
status	string	[Output Only] The status of the reservation. - CREATING: Reservation resources are being allocated. - READY: Reservation resources have been allocated, and the reservation is ready for use. - DELETING: Reservation deletion is in progress. - UPDATING: Reservation update is in progress.
zone	string	Zone in which the reservation resides. A zone must be provided if the reservation is created within a commitment.

list

Successful response

Name	Datatype	Description
id	string	[Output Only] The unique identifier for the resource. This identifier is defined by the server.
items	array	[Output Only] A list of Allocation resources.
kind	string	[Output Only] Type of resource.Always compute#reservationsList for listsof reservations (default: compute#reservationList)
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	The name of the resource, provided by the client when initially creating the resource. The resource 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?)
advancedDeploymentControl	object	Advanced control for cluster management, applicable only to DENSE deployment type reservations. (id: ReservationAdvancedDeploymentControl)
aggregateReservation	object	Reservation for aggregated resources, providing shape flexibility. (id: AllocationAggregateReservation)
commitment	string	[Output Only] Full or partial URL to a parent commitment. This field displays for reservations that are tied to a commitment.
creationTimestamp	string	[Output Only] Creation timestamp in RFC3339 text format.
deleteAfterDuration	object	Duration time relative to reservation creation when Compute Engine will automatically delete this resource. (id: Duration)
deleteAtTime	string	Absolute time in future when the reservation will be auto-deleted by Compute Engine. Timestamp is represented in RFC3339 text format.
deploymentType	string	Specifies the deployment strategy for this reservation.
description	string	An optional description of this resource. Provide this property when you create the resource.
enableEmergentMaintenance	boolean	Indicates whether Compute Engine allows unplanned maintenance for your VMs; for example, to fix hardware errors.
kind	string	[Output Only] Type of the resource. Always compute#reservations for reservations. (default: compute#reservation)
linkedCommitments	array	[Output Only] Full or partial URL to parent commitments. This field displays for reservations that are tied to multiple commitments.
reservationSharingPolicy	object	Specify the reservation sharing policy. If unspecified, the reservation will not be shared with Google Cloud managed services. (id: AllocationReservationSharingPolicy)
resourcePolicies	object	Resource policies to be added to this reservation. The key is defined by user, and the value is resource policy url. This is to define placement policy with reservation.
resourceStatus	object	[Output Only] Status information for Reservation resource. (id: AllocationResourceStatus)
satisfiesPzs	boolean	[Output Only] Reserved for future use.
schedulingType	string	The type of maintenance for the reservation.
selfLink	string	[Output Only] Server-defined fully-qualified URL for this resource.
shareSettings	object	Specify share-settings to create a shared reservation. This property is optional. For more information about the syntax and options for this field and its subfields, see the guide for creating a shared reservation. (id: ShareSettings)
specificReservation	object	Reservation for instances with specific machine shapes. (id: AllocationSpecificSKUReservation)
specificReservationRequired	boolean	Indicates whether the reservation can be consumed by VMs with affinity for "any" reservation. If the field is set, then only VMs that target the reservation by name can consume from this reservation.
status	string	[Output Only] The status of the reservation. - CREATING: Reservation resources are being allocated. - READY: Reservation resources have been allocated, and the reservation is ready for use. - DELETING: Reservation deletion is in progress. - UPDATING: Reservation update is in progress.
zone	string	Zone in which the reservation resides. A zone must be provided if the reservation is created within a commitment.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	project, zone, reservation		Retrieves information about the specified reservation.
list	select	project, zone	filter, maxResults, orderBy, pageToken, returnPartialSuccess	A list of all the reservations that have been configured for the specified project in specified zone.
aggregated_list	select	project	filter, includeAllScopes, maxResults, orderBy, pageToken, returnPartialSuccess, serviceProjectNumber	Retrieves an aggregated list of reservations. To prevent failure, Google recommends that you set the returnPartialSuccess parameter to true.
insert	insert	project, zone	requestId	Creates a new reservation. For more information, read Reserving zonal resources.
update	update	project, zone, reservation	paths, requestId, updateMask	Update share settings of the reservation.
delete	delete	project, zone, reservation	requestId	Deletes the specified reservation.
resize	exec	project, zone, reservation	requestId	Resizes the reservation (applicable to standalone reservations only). For more information, read Modifying reservations.
perform_maintenance	exec	project, zone, reservation	requestId	Perform maintenance on an extended reservation

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
project	string
reservation	string
zone	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

Retrieves information about the specified reservation.

SELECT
id,
name,
advancedDeploymentControl,
aggregateReservation,
commitment,
creationTimestamp,
deleteAfterDuration,
deleteAtTime,
deploymentType,
description,
enableEmergentMaintenance,
kind,
linkedCommitments,
reservationSharingPolicy,
resourcePolicies,
resourceStatus,
satisfiesPzs,
schedulingType,
selfLink,
shareSettings,
specificReservation,
specificReservationRequired,
status,
zone
FROM google.compute.reservations
WHERE project = '{{ project }}' -- required
AND zone = '{{ zone }}' -- required
AND reservation = '{{ reservation }}' -- required;

list

A list of all the reservations that have been configured for the specified project in specified zone.

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

aggregated_list

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

SELECT
id,
name,
advancedDeploymentControl,
aggregateReservation,
commitment,
creationTimestamp,
deleteAfterDuration,
deleteAtTime,
deploymentType,
description,
enableEmergentMaintenance,
kind,
linkedCommitments,
reservationSharingPolicy,
resourcePolicies,
resourceStatus,
satisfiesPzs,
schedulingType,
selfLink,
shareSettings,
specificReservation,
specificReservationRequired,
status,
zone
FROM google.compute.reservations
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 new reservation. For more information, read Reserving zonal resources.

INSERT INTO google.compute.reservations (
data__specificReservation,
data__aggregateReservation,
data__deleteAtTime,
data__deleteAfterDuration,
data__kind,
data__id,
data__creationTimestamp,
data__selfLink,
data__zone,
data__description,
data__name,
data__commitment,
data__linkedCommitments,
data__specificReservationRequired,
data__status,
data__shareSettings,
data__satisfiesPzs,
data__resourcePolicies,
data__resourceStatus,
data__reservationSharingPolicy,
data__deploymentType,
data__advancedDeploymentControl,
data__enableEmergentMaintenance,
data__schedulingType,
project,
zone,
requestId
)
SELECT 
'{{ specificReservation }}',
'{{ aggregateReservation }}',
'{{ deleteAtTime }}',
'{{ deleteAfterDuration }}',
'{{ kind }}',
'{{ id }}',
'{{ creationTimestamp }}',
'{{ selfLink }}',
'{{ zone }}',
'{{ description }}',
'{{ name }}',
'{{ commitment }}',
'{{ linkedCommitments }}',
{{ specificReservationRequired }},
'{{ status }}',
'{{ shareSettings }}',
{{ satisfiesPzs }},
'{{ resourcePolicies }}',
'{{ resourceStatus }}',
'{{ reservationSharingPolicy }}',
'{{ deploymentType }}',
'{{ advancedDeploymentControl }}',
{{ enableEmergentMaintenance }},
'{{ schedulingType }}',
'{{ project }}',
'{{ zone }}',
'{{ 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: reservations
  props:
    - name: project
      value: string
      description: Required parameter for the reservations resource.
    - name: zone
      value: string
      description: Required parameter for the reservations resource.
    - name: specificReservation
      value: object
      description: >
        Reservation for instances with specific machine shapes.
        
    - name: aggregateReservation
      value: object
      description: >
        Reservation for aggregated resources, providing shape flexibility.
        
    - name: deleteAtTime
      value: string
      description: >
        Absolute time in future when the reservation will be auto-deleted by Compute Engine. Timestamp is represented in RFC3339 text format.
        
    - name: deleteAfterDuration
      value: object
      description: >
        Duration time relative to reservation creation when Compute Engine will automatically delete this resource.
        
    - name: kind
      value: string
      description: >
        [Output Only] Type of the resource. Always compute#reservations for reservations.
        
      default: compute#reservation
    - 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: selfLink
      value: string
      description: >
        [Output Only] Server-defined fully-qualified URL for this resource.
        
    - name: zone
      value: string
      description: >
        Zone in which the reservation resides. A zone must be provided if the reservation is created within a commitment.
        
    - name: description
      value: string
      description: >
        An optional description of this resource. Provide this property when you create the resource.
        
    - name: name
      value: string
      description: >
        The name of the resource, provided by the client when initially creating the resource. The resource 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: commitment
      value: string
      description: >
        [Output Only] Full or partial URL to a parent commitment. This field displays for reservations that are tied to a commitment.
        
    - name: linkedCommitments
      value: array
      description: >
        [Output Only] Full or partial URL to parent commitments. This field displays for reservations that are tied to multiple commitments.
        
    - name: specificReservationRequired
      value: boolean
      description: >
        Indicates whether the reservation can be consumed by VMs with affinity for "any" reservation. If the field is set, then only VMs that target the reservation by name can consume from this reservation.
        
    - name: status
      value: string
      description: >
        [Output Only] The status of the reservation. - CREATING: Reservation resources are being allocated. - READY: Reservation resources have been allocated, and the reservation is ready for use. - DELETING: Reservation deletion is in progress. - UPDATING: Reservation update is in progress. 
        
      valid_values: ['CREATING', 'DELETING', 'INVALID', 'READY', 'UPDATING']
    - name: shareSettings
      value: object
      description: >
        Specify share-settings to create a shared reservation. This property is optional. For more information about the syntax and options for this field and its subfields, see the guide for creating a shared reservation.
        
    - name: satisfiesPzs
      value: boolean
      description: >
        [Output Only] Reserved for future use.
        
    - name: resourcePolicies
      value: object
      description: >
        Resource policies to be added to this reservation. The key is defined by user, and the value is resource policy url. This is to define placement policy with reservation.
        
    - name: resourceStatus
      value: object
      description: >
        [Output Only] Status information for Reservation resource.
        
    - name: reservationSharingPolicy
      value: object
      description: >
        Specify the reservation sharing policy. If unspecified, the reservation will not be shared with Google Cloud managed services.
        
    - name: deploymentType
      value: string
      description: >
        Specifies the deployment strategy for this reservation.
        
      valid_values: ['DENSE', 'DEPLOYMENT_TYPE_UNSPECIFIED']
    - name: advancedDeploymentControl
      value: object
      description: >
        Advanced control for cluster management, applicable only to DENSE deployment type reservations.
        
    - name: enableEmergentMaintenance
      value: boolean
      description: >
        Indicates whether Compute Engine allows unplanned maintenance for your VMs; for example, to fix hardware errors.
        
    - name: schedulingType
      value: string
      description: >
        The type of maintenance for the reservation.
        
      valid_values: ['GROUPED', 'GROUP_MAINTENANCE_TYPE_UNSPECIFIED', 'INDEPENDENT']
    - name: requestId
      value: string

UPDATE examples

update

Update share settings of the reservation.

UPDATE google.compute.reservations
SET 
data__specificReservation = '{{ specificReservation }}',
data__aggregateReservation = '{{ aggregateReservation }}',
data__deleteAtTime = '{{ deleteAtTime }}',
data__deleteAfterDuration = '{{ deleteAfterDuration }}',
data__kind = '{{ kind }}',
data__id = '{{ id }}',
data__creationTimestamp = '{{ creationTimestamp }}',
data__selfLink = '{{ selfLink }}',
data__zone = '{{ zone }}',
data__description = '{{ description }}',
data__name = '{{ name }}',
data__commitment = '{{ commitment }}',
data__linkedCommitments = '{{ linkedCommitments }}',
data__specificReservationRequired = {{ specificReservationRequired }},
data__status = '{{ status }}',
data__shareSettings = '{{ shareSettings }}',
data__satisfiesPzs = {{ satisfiesPzs }},
data__resourcePolicies = '{{ resourcePolicies }}',
data__resourceStatus = '{{ resourceStatus }}',
data__reservationSharingPolicy = '{{ reservationSharingPolicy }}',
data__deploymentType = '{{ deploymentType }}',
data__advancedDeploymentControl = '{{ advancedDeploymentControl }}',
data__enableEmergentMaintenance = {{ enableEmergentMaintenance }},
data__schedulingType = '{{ schedulingType }}'
WHERE 
project = '{{ project }}' --required
AND zone = '{{ zone }}' --required
AND reservation = '{{ reservation }}' --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;

DELETE examples

delete

Deletes the specified reservation.

DELETE FROM google.compute.reservations
WHERE project = '{{ project }}' --required
AND zone = '{{ zone }}' --required
AND reservation = '{{ reservation }}' --required
AND requestId = '{{ requestId }}';

Lifecycle Methods

resize

Resizes the reservation (applicable to standalone reservations only). For more information, read Modifying reservations.

EXEC google.compute.reservations.resize 
@project='{{ project }}' --required, 
@zone='{{ zone }}' --required, 
@reservation='{{ reservation }}' --required, 
@requestId='{{ requestId }}' 
@@json=
'{
"specificSkuCount": "{{ specificSkuCount }}"
}';

perform_maintenance

Perform maintenance on an extended reservation

EXEC google.compute.reservations.perform_maintenance 
@project='{{ project }}' --required, 
@zone='{{ zone }}' --required, 
@reservation='{{ reservation }}' --required, 
@requestId='{{ requestId }}' 
@@json=
'{
"maintenanceScope": "{{ maintenanceScope }}"
}';