REST Resource: instances

Resource: Instance

Represents an Instance resource.

An instance is a virtual machine that is hosted on Trusted Cloud Platform. For more information, read Virtual Machine Instances.

JSON representation 
{
  "kind": string,
  "id": string,
  "creationTimestamp": string,
  "name": string,
  "description": string,
  "tags": {
    object (Tags)
  },
  "machineType": string,
  "status": enum (Status),
  "statusMessage": string,
  "zone": string,
  "canIpForward": boolean,
  "networkInterfaces": [
    {
      object (NetworkInterface)
    }
  ],
  "disks": [
    {
      object (AttachedDisk)
    }
  ],
  "metadata": {
    object (Metadata)
  },
  "serviceAccounts": [
    {
      object (ServiceAccount)
    }
  ],
  "selfLink": string,
  "scheduling": {
    object (Scheduling)
  },
  "cpuPlatform": string,
  "labels": {
    string: string,
    ...
  },
  "params": {
    object (InstanceParams)
  },
  "labelFingerprint": string,
  "instanceEncryptionKey": {
    object (CustomerEncryptionKey)
  },
  "minCpuPlatform": string,
  "guestAccelerators": [
    {
      object (AcceleratorConfig)
    }
  ],
  "startRestricted": boolean,
  "deletionProtection": boolean,
  "resourcePolicies": [
    string
  ],
  "sourceMachineImage": string,
  "reservationAffinity": {
    object (ReservationAffinity)
  },
  "hostname": string,
  "displayDevice": {
    object (DisplayDevice)
  },
  "shieldedInstanceConfig": {
    object (ShieldedInstanceConfig)
  },
  "shieldedInstanceIntegrityPolicy": {
    object (ShieldedInstanceIntegrityPolicy)
  },
  "sourceMachineImageEncryptionKey": {
    object (CustomerEncryptionKey)
  },
  "confidentialInstanceConfig": {
    object (ConfidentialInstanceConfig)
  },
  "fingerprint": string,
  "privateIpv6GoogleAccess": enum (InstancePrivateIpv6GoogleAccess),
  "advancedMachineFeatures": {
    object (AdvancedMachineFeatures)
  },
  "lastStartTimestamp": string,
  "lastStopTimestamp": string,
  "lastSuspendedTimestamp": string,
  "satisfiesPzs": boolean,
  "satisfiesPzi": boolean,
  "resourceStatus": {
    object (ResourceStatus)
  },
  "networkPerformanceConfig": {
    object (NetworkPerformanceConfig)
  },
  "keyRevocationActionType": enum (KeyRevocationActionType)
}
Fields
kind

string

[Output Only] Type of the resource. Always

compute#instance

for instances.
id

string (uint64 format)

[Output Only] The unique identifier for the resource. This identifier is defined by the server.
creationTimestamp

string

[Output Only] Creation timestamp in RFC3339 text format.
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.
description

string

An optional description of this resource. Provide this property when you create the resource.
tags

object (Tags)

Tags to apply to this instance. Tags are used to identify valid sources or targets for network firewalls and are specified by the client during instance creation. The tags can be later modified by the setTags method. Each tag within the list must comply with RFC1035. Multiple tags can be specified via the 'tags.items' field.
machineType

string

Full 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.
status

enum (Status)

[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.
statusMessage

string

[Output Only] An optional, human-readable explanation of the status.
zone

string

[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.
canIpForward

boolean

Allows 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.
networkInterfaces[]

object (NetworkInterface)

An 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.
disks[]

object (AttachedDisk)

Array of disks associated with this instance. Persistent disks must be created before you can assign them.
metadata

object (Metadata)

The metadata key/value pairs assigned to this instance. This includes metadata keys that were explicitly defined for the instance.
serviceAccounts[]

object (ServiceAccount)

A 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.
scheduling

object (Scheduling)

Sets the scheduling options for this instance.
cpuPlatform

string

[Output Only] The CPU platform used by this instance.
labels

map (key: string, value: string)

Labels to apply to this instance. These can be later modified by the

setLabels

method.
params

object (InstanceParams)

Input only. [Input Only] Additional params passed with the request, but not persisted as part of resource payload.
labelFingerprint

string (bytes format)

A 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.

A base64-encoded string.
instanceEncryptionKey

object (CustomerEncryptionKey)

Encrypts suspended data for an instance with a customer-managed encryption key.

If you are creating a new instance, this field will encrypt the local SSD and in-memory contents of the instance during the suspend operation.

If you do not provide an encryption key when creating the instance, then the local SSD and in-memory contents will be encrypted using an automatically generated key during the suspend operation.
minCpuPlatform

string

Specifies 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"

.
guestAccelerators[]

object (AcceleratorConfig)

A list of the type and count of accelerator cards attached to the instance.
startRestricted

boolean

[Output Only] Whether a VM has been restricted for start because Compute Engine has detected suspicious activity.
deletionProtection

boolean

Whether the resource should be protected against deletion.
resourcePolicies[]

string

Resource policies applied to this instance.
sourceMachineImage

string

Source machine image
reservationAffinity

object (ReservationAffinity)

Specifies the reservations that this instance can consume from.
hostname

string

Specifies 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.
displayDevice

object (DisplayDevice)

Enables display device for the instance.
shieldedInstanceConfig

object (ShieldedInstanceConfig)
shieldedInstanceIntegrityPolicy

object (ShieldedInstanceIntegrityPolicy)
sourceMachineImageEncryptionKey

object (CustomerEncryptionKey)

Source machine image encryption key when creating an instance from a machine image.
confidentialInstanceConfig

object (ConfidentialInstanceConfig)
fingerprint

string (bytes format)

Specifies 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.

A base64-encoded string.
privateIpv6GoogleAccess

enum (InstancePrivateIpv6GoogleAccess)

The private IPv6 Google access type for the VM. If not specified, use

INHERIT_FROM_SUBNETWORK

as default.
advancedMachineFeatures

object (AdvancedMachineFeatures)

Controls for advanced machine-related behavior features.
lastStartTimestamp

string

[Output Only] Last start timestamp in RFC3339 text format.
lastStopTimestamp

string

[Output Only] Last stop timestamp in RFC3339 text format.
lastSuspendedTimestamp

string

[Output Only] Last suspended timestamp in RFC3339 text format.
satisfiesPzs

boolean

[Output Only] Reserved for future use.
satisfiesPzi

boolean

[Output Only] Reserved for future use.
resourceStatus

object (ResourceStatus)

[Output Only] Specifies values set for instance attributes as compared to the values requested by user in the corresponding input only field.
networkPerformanceConfig

object (NetworkPerformanceConfig)
keyRevocationActionType

enum (KeyRevocationActionType)

KeyRevocationActionType of the instance. Supported options are "STOP" and "NONE". The default value is "NONE" if it is not specified.

Status

Enums
PROVISIONING Resources are being allocated for the instance.
STAGING All required resources have been allocated and the instance is being started.
RUNNING The instance is running.
STOPPING The instance is currently stopping (either being deleted or killed).
STOPPED The instance has stopped successfully.
TERMINATED The instance has stopped (either by explicit action or underlying failure).
SUSPENDING The instance is suspending.
SUSPENDED The instance has suspended.
REPAIRING The instance is in repair.
DEPROVISIONING The instance is halted and we are performing tear down tasks like network deprogramming, releasing quota, IP, tearing down disks etc.
PENDING For Flex instances.start provisioning instance is waiting for available capacity from Dynamic Workload Scheduler (DWS).

InstanceParams

Additional instance params.

JSON representation 
{
  "resourceManagerTags": {
    string: string,
    ...
  },
  "requestValidForDuration": {
    object (Duration)
  }
}
Fields
resourceManagerTags

map (key: string, value: string)

Resource manager tags to be bound to the instance. Tag keys and values have the same definition as resource manager tags. Keys must be in the format tagKeys/{tag_key_id}, and values are in the format tagValues/456. The field is ignored (both PUT & PATCH) when empty.
requestValidForDuration

object (Duration)

Relative deadline for waiting for capacity. Relevant only for Instances.Insert API.

DisplayDevice

A set of Display Device options

JSON representation 
{
  "enableDisplay": boolean
}
Fields
enableDisplay

boolean

Defines whether the instance has Display enabled.

ShieldedInstanceIntegrityPolicy

The policy describes the baseline against which Instance boot integrity is measured.

JSON representation 
{

  // Union field policy can be only one of the following:
  "updateAutoLearnPolicy": boolean
  // End of list of possible types for union field policy.
}
Fields

Union field policy.

policy can be only one of the following:
updateAutoLearnPolicy

boolean

Updates the integrity policy baseline using the measurements from the VM instance's most recent boot.

ResourceStatus

Contains 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.

JSON representation 
{
  "effectiveInstanceMetadata": {
    object (EffectiveInstanceMetadata)
  },
  "scheduling": {
    object (Scheduling)
  },
  "upcomingMaintenance": {
    object (UpcomingMaintenance)
  },
  "physicalHost": string,
  "physicalHostTopology": {
    object (PhysicalHostTopology)
  }
}
Fields
effectiveInstanceMetadata

object (EffectiveInstanceMetadata)

[Output Only] Effective metadata is a field that consolidates project, zonal instance settings, and instance-level predefined metadata keys to provide the overridden value for those metadata keys at the instance level.
scheduling

object (Scheduling)
upcomingMaintenance

object (UpcomingMaintenance)
physicalHost

string

[Output Only] The precise location of your instance within the zone's data center, including the block, sub-block, and host. The field is formatted as follows: blockId/subBlockId/hostId.
physicalHostTopology

object (PhysicalHostTopology)

[Output Only] A series of fields containing the global name of the Compute Engine cluster, as well as the ID of the block, sub-block, and host on which the running instance is located.

EffectiveInstanceMetadata

Effective values of predefined metadata keys for an instance.

JSON representation 
{
  "vmDnsSettingMetadataValue": string,
  "enableOsloginMetadataValue": boolean,
  "enableOsconfigMetadataValue": boolean,
  "enableOsInventoryMetadataValue": boolean,
  "enableGuestAttributesMetadataValue": boolean,
  "blockProjectSshKeysMetadataValue": boolean,
  "serialPortEnableMetadataValue": boolean,
  "serialPortLoggingEnableMetadataValue": boolean
}
Fields
vmDnsSettingMetadataValue

string

Effective VM DNS setting at Instance level.
enableOsloginMetadataValue

boolean

Effective enable-oslogin value at Instance level.
enableOsconfigMetadataValue

boolean

Effective enable-osconfig value at Instance level.
enableOsInventoryMetadataValue

boolean

Effective enable-os-inventory value at Instance level.
enableGuestAttributesMetadataValue

boolean

Effective enable-guest-attributes value at Instance level.
blockProjectSshKeysMetadataValue

boolean

Effective block-project-ssh-keys value at Instance level.
serialPortEnableMetadataValue

boolean

Effective serial-port-enable value at Instance level.
serialPortLoggingEnableMetadataValue

boolean

Effective serial-port-logging-enable value at Instance level.

Scheduling

JSON representation 
{
  "availabilityDomain": integer
}
Fields
availabilityDomain

integer

Specifies the availability domain to place the instance in. The value must be a number between 1 and the number of availability domains specified in the spread placement policy attached to the instance.

PhysicalHostTopology

Represents the physical host topology of the host on which the VM is running.

JSON representation 
{
  "cluster": string,
  "block": string,
  "subblock": string,
  "host": string
}
Fields
cluster

string

[Output Only] The global name of the Compute Engine cluster where the running instance is located.
block

string

[Output Only] The ID of the block in which the running instance is located. Instances within the same block experience low network latency.
subblock

string

[Output Only] The ID of the sub-block in which the running instance is located. Instances in the same sub-block experience lower network latency than instances in the same block.
host

string

[Output Only] The ID of the host on which the running instance is located. Instances on the same host experience the lowest possible network latency.

Methods

addAccessConfig

 Adds an access config to an instance's network interface.

addResourcePolicies

 Adds existing resource policies to an instance.

aggregatedList

 Retrieves an aggregated list of all of the instances in your project across all regions and zones.

attachDisk

 Attaches an existing Disk resource to an instance.

bulkInsert

 Creates multiple instances.

delete

 Deletes the specified Instance resource.

deleteAccessConfig

 Deletes an access config from an instance's network interface.

detachDisk

 Detaches a disk from an instance.

get

 Returns the specified Instance resource.

getEffectiveFirewalls

 Returns effective firewalls applied to an interface of the instance.

getGuestAttributes

 Returns the specified guest attributes entry.

getScreenshot

 Returns the screenshot from the specified instance.

getSerialPortOutput

 Returns the last 1 MB of serial port output from the specified instance.

getShieldedInstanceIdentity

 Returns the Shielded Instance Identity of an instance

insert

 Creates an instance resource in the specified project using the data included in the request.

list

 Retrieves the list of instances contained within the specified zone.

listReferrers

 Retrieves a list of resources that refer to the VM instance specified in the request.

removeResourcePolicies

 Removes resource policies from an instance.

reset

 Performs a reset on the instance.

setDeletionProtection

 Sets deletion protection on the instance.

setDiskAutoDelete

 Sets the auto-delete flag for a disk attached to an instance.

setLabels

 Sets labels on an instance.

setMachineResources

 Changes the number and/or type of accelerator for a stopped instance to the values specified in the request.

setMachineType

 Changes the machine type for a stopped instance to the machine type specified in the request.

setMetadata

 Sets metadata for the specified instance to the data included in the request.

setMinCpuPlatform

 Changes the minimum CPU platform that this instance should use.

setScheduling

 Sets an instance's scheduling options.

setServiceAccount

 Sets the service account on the instance.

setShieldedInstanceIntegrityPolicy

 Sets the Shielded Instance integrity policy for an instance.

setTags

 Sets network tags for the specified instance to the data included in the request.

simulateMaintenanceEvent

 Simulates a host maintenance event on a VM.

start

Starts an instance that was stopped using the instances().stop method.

startWithEncryptionKey

Starts an instance that was stopped using the instances().stop method.

stop

 Stops a running instance, shutting it down cleanly, and allows you to restart the instance at a later time.

update

 Updates an instance only if the necessary resources are available.

updateAccessConfig

 Updates the specified access config from an instance's network interface with the data included in the request.

updateDisplayDevice

 Updates the Display config for a VM instance.

updateNetworkInterface

 Updates an instance's network interface.

updateShieldedInstanceConfig

 Updates the Shielded Instance config for an instance.

addNetworkInterface

 The method compute.v1.InstancesService.AddNetworkInterface is not available in Trusted Cloud by S3NS.

deleteNetworkInterface

 The method compute.v1.InstancesService.DeleteNetworkInterface is not available in Trusted Cloud by S3NS.

getIamPolicy

 The method compute.v1.InstancesService.GetPolicy is not available in Trusted Cloud by S3NS.

performMaintenance

 The method compute.v1.InstancesService.PerformMaintenance is not available in Trusted Cloud by S3NS.

reportHostAsFaulty

 The method compute.v1.InstancesService.ReportHostAsFaulty is not available in Trusted Cloud by S3NS.

resume

 The method compute.v1.InstancesService.Resume is not available in Trusted Cloud by S3NS.

sendDiagnosticInterrupt

 The method compute.v1.InstancesService.SendDiagnosticInterrupt is not available in Trusted Cloud by S3NS.

setIamPolicy

 The method compute.v1.InstancesService.SetPolicy is not available in Trusted Cloud by S3NS.

setName

 The method compute.v1.InstancesService.SetName is not available in Trusted Cloud by S3NS.

setSecurityPolicy

 The method compute.v1.InstancesService.SetSecurityPolicy is not available in Trusted Cloud by S3NS.

suspend

 The method compute.v1.InstancesService.Suspend is not available in Trusted Cloud by S3NS.

testIamPermissions

 The method compute.v1.InstancesService.TestPermissions is not available in Trusted Cloud by S3NS.