Skip to main content

instances

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

Overview​

Nameinstances
TypeResource
Idgoogle.compute.instances

Fields​

NameDatatypeDescription
idstring[Output Only] The unique identifier for the resource. This identifier is defined by the server.
namestringThe 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.
descriptionstringAn optional description of this resource. Provide this property when you create the resource.
advancedMachineFeaturesobjectSpecifies options for controlling advanced machine features. Options that would traditionally be configured in a BIOS belong here. Features that require operating system support may have corresponding entries in the GuestOsFeatures of an Image (e.g., whether or not the OS in the Image supports nested virtualization being enabled or disabled).
canIpForwardbooleanAllows this instance to send and receive packets with non-matching destination or source IPs. This is required if you plan to use this instance to forward routes. For more information, see Enabling IP Forwarding .
confidentialInstanceConfigobjectA set of Confidential Instance options.
cpuPlatformstring[Output Only] The CPU platform used by this instance.
creationTimestampstring[Output Only] Creation timestamp in RFC3339 text format.
deletionProtectionbooleanWhether the resource should be protected against deletion.
disksarrayArray of disks associated with this instance. Persistent disks must be created before you can assign them.
displayDeviceobjectA set of Display Device options
fingerprintstringSpecifies a fingerprint for this resource, which is essentially a hash of the instance's contents and used for optimistic locking. The fingerprint is initially generated by Compute Engine and changes after every request to modify or update the instance. You must always provide an up-to-date fingerprint hash in order to update the instance. To see the latest fingerprint, make get() request to the instance.
guestAcceleratorsarrayA list of the type and count of accelerator cards attached to the instance.
hostnamestringSpecifies the hostname of the instance. The specified hostname must be RFC1035 compliant. If hostname is not specified, the default hostname is [INSTANCE_NAME].c.[PROJECT_ID].internal when using the global DNS, and [INSTANCE_NAME].[ZONE].c.[PROJECT_ID].internal when using zonal DNS.
instanceEncryptionKeyobject
keyRevocationActionTypestringKeyRevocationActionType of the instance. Supported options are "STOP" and "NONE". The default value is "NONE" if it is not specified.
kindstring[Output Only] Type of the resource. Always compute#instance for instances.
labelFingerprintstringA fingerprint for this request, which is essentially a hash of the label's contents and used for optimistic locking. The fingerprint is initially generated by Compute Engine and changes after every request to modify or update labels. You must always provide an up-to-date fingerprint hash in order to update or change labels. To see the latest fingerprint, make get() request to the instance.
labelsobjectLabels to apply to this instance. These can be later modified by the setLabels method.
lastStartTimestampstring[Output Only] Last start timestamp in RFC3339 text format.
lastStopTimestampstring[Output Only] Last stop timestamp in RFC3339 text format.
lastSuspendedTimestampstring[Output Only] Last suspended timestamp in RFC3339 text format.
machineTypestringFull or partial URL of the machine type resource to use for this instance, in the format: zones/zone/machineTypes/machine-type. This is provided by the client when the instance is created. For example, the following is a valid partial url to a predefined machine type: zones/us-central1-f/machineTypes/n1-standard-1 To create a custom machine type, provide a URL to a machine type in the following format, where CPUS is 1 or an even number up to 32 (2, 4, 6, ... 24, etc), and MEMORY is the total memory for this instance. Memory must be a multiple of 256 MB and must be supplied in MB (e.g. 5 GB of memory is 5120 MB): zones/zone/machineTypes/custom-CPUS-MEMORY For example: zones/us-central1-f/machineTypes/custom-4-5120 For a full list of restrictions, read the Specifications for custom machine types.
metadataobjectA metadata key/value entry.
minCpuPlatformstringSpecifies a minimum CPU platform for the VM instance. Applicable values are the friendly names of CPU platforms, such as minCpuPlatform: "Intel Haswell" or minCpuPlatform: "Intel Sandy Bridge".
networkInterfacesarrayAn array of network configurations for this instance. These specify how interfaces are configured to interact with other network services, such as connecting to the internet. Multiple interfaces are supported per instance.
networkPerformanceConfigobject
paramsobjectAdditional instance params.
privateIpv6GoogleAccessstringThe private IPv6 google access type for the VM. If not specified, use INHERIT_FROM_SUBNETWORK as default.
reservationAffinityobjectSpecifies the reservations that this instance can consume from.
resourcePoliciesarrayResource policies applied to this instance.
resourceStatusobjectContains output only fields. Use this sub-message for actual values set on Instance attributes as compared to the value requested by the user (intent) in their instance CRUD calls.
satisfiesPziboolean[Output Only] Reserved for future use.
satisfiesPzsboolean[Output Only] Reserved for future use.
schedulingobjectSets the scheduling options for an Instance.
selfLinkstring[Output Only] Server-defined URL for this resource.
serviceAccountsarrayA list of service accounts, with their specified scopes, authorized for this instance. Only one service account per VM instance is supported. Service accounts generate access tokens that can be accessed through the metadata server and used to authenticate applications on the instance. See Service Accounts for more information.
shieldedInstanceConfigobjectA set of Shielded Instance options.
shieldedInstanceIntegrityPolicyobjectThe policy describes the baseline against which Instance boot integrity is measured.
sourceMachineImagestringSource machine image
sourceMachineImageEncryptionKeyobject
startRestrictedboolean[Output Only] Whether a VM has been restricted for start because Compute Engine has detected suspicious activity.
statusstring[Output Only] The status of the instance. One of the following values: PROVISIONING, STAGING, RUNNING, STOPPING, SUSPENDING, SUSPENDED, REPAIRING, and TERMINATED. For more information about the status of the instance, see Instance life cycle.
statusMessagestring[Output Only] An optional, human-readable explanation of the status.
tagsobjectA set of instance tags.
zonestring[Output Only] URL of the zone where the instance resides. You must specify this field as part of the HTTP request URL. It is not settable as a field in the request body.

Methods​

NameAccessible byRequired ParamsDescription
aggregated_listSELECTprojectRetrieves an aggregated list of all of the instances in your project across all regions and zones. The performance of this method degrades when a filter is specified on a project that has a very large number of instances. To prevent failure, Google recommends that you set the returnPartialSuccess parameter to true.
getSELECTinstance, project, zoneReturns the specified Instance resource.
listSELECTproject, zoneRetrieves the list of instances contained within the specified zone.
bulk_insertINSERTproject, zoneCreates multiple instances. Count specifies the number of instances to create. For more information, see About bulk creation of VMs.
insertINSERTproject, zoneCreates an instance resource in the specified project using the data included in the request.
deleteDELETEinstance, project, zoneDeletes the specified Instance resource. For more information, see Deleting an instance.
updateREPLACEinstance, project, zoneUpdates an instance only if the necessary resources are available. This method can update only a specific set of instance properties. See Updating a running instance for a list of updatable instance properties.
attach_diskEXECinstance, project, zoneAttaches an existing Disk resource to an instance. You must first create the disk before you can attach it. It is not possible to create and attach a disk at the same time. For more information, read Adding a persistent disk to your instance.
detach_diskEXECdeviceName, instance, project, zoneDetaches a disk from an instance.
perform_maintenanceEXECinstance, project, zonePerform a manual maintenance on the instance.
resetEXECinstance, project, zonePerforms a reset on the instance. This is a hard reset. The VM does not do a graceful shutdown. For more information, see Resetting an instance.
resumeEXECinstance, project, zoneResumes an instance that was suspended using the instances().suspend method.
send_diagnostic_interruptEXECinstance, project, zoneSends diagnostic interrupt to the instance.
set_deletion_protectionEXECproject, resource, zoneSets deletion protection on the instance.
set_disk_auto_deleteEXECautoDelete, deviceName, instance, project, zoneSets the auto-delete flag for a disk attached to an instance.
set_labelsEXECinstance, project, zoneSets labels on an instance. To learn more about labels, read the Labeling Resources documentation.
set_machine_resourcesEXECinstance, project, zoneChanges the number and/or type of accelerator for a stopped instance to the values specified in the request.
set_machine_typeEXECinstance, project, zoneChanges the machine type for a stopped instance to the machine type specified in the request.
set_metadataEXECinstance, project, zoneSets metadata for the specified instance to the data included in the request.
set_min_cpu_platformEXECinstance, project, zoneChanges the minimum CPU platform that this instance should use. This method can only be called on a stopped instance. For more information, read Specifying a Minimum CPU Platform.
set_nameEXECinstance, project, zoneSets name of an instance.
set_schedulingEXECinstance, project, zoneSets an instance's scheduling options. You can only call this method on a stopped instance, that is, a VM instance that is in a TERMINATED state. See Instance Life Cycle for more information on the possible instance states. For more information about setting scheduling options for a VM, see Set VM host maintenance policy.
set_security_policyEXECinstance, project, zoneSets the Google Cloud Armor security policy for the specified instance. For more information, see Google Cloud Armor Overview
set_service_accountEXECinstance, project, zoneSets the service account on the instance. For more information, read Changing the service account and access scopes for an instance.
set_shielded_instance_integrity_policyEXECinstance, project, zoneSets the Shielded Instance integrity policy for an instance. You can only use this method on a running instance. This method supports PATCH semantics and uses the JSON merge patch format and processing rules.
set_tagsEXECinstance, project, zoneSets network tags for the specified instance to the data included in the request.
simulate_maintenance_eventEXECinstance, project, zoneSimulates a host maintenance event on a VM. For more information, see Simulate a host maintenance event.
startEXECinstance, project, zoneStarts an instance that was stopped using the instances().stop method. For more information, see Restart an instance.
start_with_encryption_keyEXECinstance, project, zoneStarts an instance that was stopped using the instances().stop method. For more information, see Restart an instance.
stopEXECinstance, project, zoneStops a running instance, shutting it down cleanly, and allows you to restart the instance at a later time. Stopped instances do not incur VM usage charges while they are stopped. However, resources that the VM is using, such as persistent disks and static IP addresses, will continue to be charged until they are deleted. For more information, see Stopping an instance.
suspendEXECinstance, project, zoneThis method suspends a running instance, saving its state to persistent storage, and allows you to resume the instance at a later time. Suspended instances have no compute costs (cores or RAM), and incur only storage charges for the saved VM memory and localSSD data. Any charged resources the virtual machine was using, such as persistent disks and static IP addresses, will continue to be charged while the instance is suspended. For more information, see Suspending and resuming an instance.

SELECT examples​

Retrieves an aggregated list of all of the instances in your project across all regions and zones. The performance of this method degrades when a filter is specified on a project that has a very large number of instances. To prevent failure, Google recommends that you set the returnPartialSuccess parameter to true.

SELECT
id,
name,
description,
advancedMachineFeatures,
canIpForward,
confidentialInstanceConfig,
cpuPlatform,
creationTimestamp,
deletionProtection,
disks,
displayDevice,
fingerprint,
guestAccelerators,
hostname,
instanceEncryptionKey,
keyRevocationActionType,
kind,
labelFingerprint,
labels,
lastStartTimestamp,
lastStopTimestamp,
lastSuspendedTimestamp,
machineType,
metadata,
minCpuPlatform,
networkInterfaces,
networkPerformanceConfig,
params,
privateIpv6GoogleAccess,
reservationAffinity,
resourcePolicies,
resourceStatus,
satisfiesPzi,
satisfiesPzs,
scheduling,
selfLink,
serviceAccounts,
shieldedInstanceConfig,
shieldedInstanceIntegrityPolicy,
sourceMachineImage,
sourceMachineImageEncryptionKey,
startRestricted,
status,
statusMessage,
tags,
zone
FROM google.compute.instances
WHERE project = '{{ project }}';

INSERT example​

Use the following StackQL query and manifest file to create a new instances resource.

/*+ create */
INSERT INTO google.compute.instances (
project,
zone,
count,
minCount,
namePattern,
perInstanceProperties,
sourceInstanceTemplate,
instanceProperties,
locationPolicy
)
SELECT 
'{{ project }}',
'{{ zone }}',
'{{ count }}',
'{{ minCount }}',
'{{ namePattern }}',
'{{ perInstanceProperties }}',
'{{ sourceInstanceTemplate }}',
'{{ instanceProperties }}',
'{{ locationPolicy }}'
;

REPLACE example​

Replaces all fields in the specified instances resource.

/*+ update */
REPLACE google.compute.instances
SET 
name = '{{ name }}',
description = '{{ description }}',
tags = '{{ tags }}',
machineType = '{{ machineType }}',
status = '{{ status }}',
statusMessage = '{{ statusMessage }}',
zone = '{{ zone }}',
canIpForward = true|false,
networkInterfaces = '{{ networkInterfaces }}',
disks = '{{ disks }}',
metadata = '{{ metadata }}',
serviceAccounts = '{{ serviceAccounts }}',
scheduling = '{{ scheduling }}',
cpuPlatform = '{{ cpuPlatform }}',
labels = '{{ labels }}',
params = '{{ params }}',
labelFingerprint = '{{ labelFingerprint }}',
instanceEncryptionKey = '{{ instanceEncryptionKey }}',
minCpuPlatform = '{{ minCpuPlatform }}',
guestAccelerators = '{{ guestAccelerators }}',
startRestricted = true|false,
deletionProtection = true|false,
resourcePolicies = '{{ resourcePolicies }}',
sourceMachineImage = '{{ sourceMachineImage }}',
reservationAffinity = '{{ reservationAffinity }}',
hostname = '{{ hostname }}',
displayDevice = '{{ displayDevice }}',
shieldedInstanceConfig = '{{ shieldedInstanceConfig }}',
shieldedInstanceIntegrityPolicy = '{{ shieldedInstanceIntegrityPolicy }}',
sourceMachineImageEncryptionKey = '{{ sourceMachineImageEncryptionKey }}',
confidentialInstanceConfig = '{{ confidentialInstanceConfig }}',
fingerprint = '{{ fingerprint }}',
privateIpv6GoogleAccess = '{{ privateIpv6GoogleAccess }}',
advancedMachineFeatures = '{{ advancedMachineFeatures }}',
lastStartTimestamp = '{{ lastStartTimestamp }}',
lastStopTimestamp = '{{ lastStopTimestamp }}',
lastSuspendedTimestamp = '{{ lastSuspendedTimestamp }}',
satisfiesPzs = true|false,
satisfiesPzi = true|false,
resourceStatus = '{{ resourceStatus }}',
networkPerformanceConfig = '{{ networkPerformanceConfig }}',
keyRevocationActionType = '{{ keyRevocationActionType }}'
WHERE 
instance = '{{ instance }}'
AND project = '{{ project }}'
AND zone = '{{ zone }}';

DELETE example​

Deletes the specified instances resource.

/*+ delete */
DELETE FROM google.compute.instances
WHERE instance = '{{ instance }}'
AND project = '{{ project }}'
AND zone = '{{ zone }}';