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,
  "shieldedVmConfig": {
    object (ShieldedVmConfig)
  },
  "shieldedVmIntegrityPolicy": {
    object (ShieldedVmIntegrityPolicy)
  },
  "reservationAffinity": {
    object (ReservationAffinity)
  },
  "hostname": string,
  "displayDevice": {
    object (DisplayDevice)
  },
  "shieldedInstanceConfig": {
    object (ShieldedInstanceConfig)
  },
  "shieldedInstanceIntegrityPolicy": {
    object (ShieldedInstanceIntegrityPolicy)
  },
  "sourceMachineImageEncryptionKey": {
    object (CustomerEncryptionKey)
  },
  "eraseWindowsVssSignature": boolean,
  "postKeyRevocationActionType": enum (PostKeyRevocationActionType),
  "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),
  "partnerMetadata": {
    string: {
      object (StructuredEntries)
    },
    ...
  }
}
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

shieldedVmConfig

object (ShieldedVmConfig)

Deprecating, please use shieldedInstanceConfig.

shieldedVmIntegrityPolicy

object (ShieldedVmIntegrityPolicy)

Deprecating, please use shieldedInstanceIntegrityPolicy.

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.

eraseWindowsVssSignature

boolean

Specifies whether the disks restored from source snapshots or source machine image should erase Windows specific VSS signature.

postKeyRevocationActionType

enum (PostKeyRevocationActionType)

PostKeyRevocationActionType of the instance.

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.

partnerMetadata

map (key: string, value: object (StructuredEntries))

Partner Metadata assigned to the instance. A map from a subdomain (namespace) to entries map.

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_STOP The instance is gracefully shutting down.

InstanceParams

Additional instance params.

JSON representation
{
  "resourceManagerTags": {
    string: string,
    ...
  }
}
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.

ShieldedVmIntegrityPolicy

The policy describes the baseline against which VM 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.

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.

PostKeyRevocationActionType

Specifies whether this instance will be shut down on key revocation.

Enums
POST_KEY_REVOCATION_ACTION_TYPE_UNSPECIFIED Default value. This value is unused.
NOOP Indicates user chose no operation.
SHUTDOWN Indicates user chose to opt for VM shutdown on key revocation.

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
{
  "scheduling": {
    object (Scheduling)
  },
  "upcomingMaintenance": {
    object (UpcomingMaintenance)
  },
  "physicalHost": string,
  "physicalHostTopology": {
    object (PhysicalHostTopology)
  },
  "shutdownDetails": {
    object (ShutdownDetails)
  }
}
Fields
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.

shutdownDetails

object (ShutdownDetails)

[Output Only] Details about the instance stopping state.

Scheduling

JSON representation
{
  "availabilityDomain": integer,
  "terminationTimestamp": string
}
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.

terminationTimestamp

string

Time in future when the instance will be terminated in RFC3339 text format.

ResizeState

Enum defines supported resize states. Applicable only for EK machine family. Internal only enum.

Enums
RESIZE_STATE_UNSPECIFIED
RESIZE_STATE_AT_INTENT AT_INTENT: last resize request was fully successful.
RESIZE_STATE_IN_PROGRESS IN_PROGRESS: there is ongoing resize operation.
RESIZE_STATE_GUEST_AGENT_ERROR GUEST_AGENT_ERROR: last resize request failed with Guest Agent error. The state of Guest OS is unclear.
RESIZE_STATE_GUEST_AGENT_TIMEOUT GUEST_AGENT_TIMEOUT: last resize request failed with Guest Agent timeout. The state of Guest OS is unclear.
RESIZE_STATE_INTERNAL_ERROR There was an internal error when resizing, unclear state.

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.

ShutdownDetails

JSON representation
{
  "stopState": enum (StopState),
  "targetState": enum (TargetState),
  "requestTimestamp": string,
  "maxDuration": {
    object (Duration)
  }
}
Fields
stopState

enum (StopState)

targetState

enum (TargetState)

requestTimestamp

string

maxDuration

object (Duration)

StopState

Enums
STOPPING
PENDING_STOP

TargetState

Enums
STOPPED
DELETED

Methods

addAccessConfig

The method compute.beta.InstancesService.AddAccessConfig is not available in Trusted Cloud by S3NS.

addNetworkInterface

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

addResourcePolicies

The method compute.beta.InstancesService.AddResourcePolicies is not available in Trusted Cloud by S3NS.

aggregatedList

The method compute.beta.InstancesService.AggregatedList is not available in Trusted Cloud by S3NS.

attachDisk

The method compute.beta.InstancesService.AttachDisk is not available in Trusted Cloud by S3NS.

bulkInsert

The method compute.beta.InstancesService.BulkInsert is not available in Trusted Cloud by S3NS.

delete

The method compute.beta.InstancesService.Delete is not available in Trusted Cloud by S3NS.

deleteAccessConfig

The method compute.beta.InstancesService.DeleteAccessConfig is not available in Trusted Cloud by S3NS.

deleteNetworkInterface

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

detachDisk

The method compute.beta.InstancesService.DetachDisk is not available in Trusted Cloud by S3NS.

get

The method compute.beta.InstancesService.Get is not available in Trusted Cloud by S3NS.

getEffectiveFirewalls

The method compute.beta.InstancesService.GetEffectiveFirewalls is not available in Trusted Cloud by S3NS.

getGuestAttributes

The method compute.beta.InstancesService.GetGuestAttributes is not available in Trusted Cloud by S3NS.

getIamPolicy

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

getPartnerMetadata

The method compute.beta.InstancesService.GetPartnerMetadata is not available in Trusted Cloud by S3NS.

getScreenshot

The method compute.beta.InstancesService.GetScreenshot is not available in Trusted Cloud by S3NS.

getSerialPortOutput

The method compute.beta.InstancesService.GetSerialPortOutput is not available in Trusted Cloud by S3NS.

getShieldedInstanceIdentity

The method compute.beta.InstancesService.GetShieldedInstanceIdentity is not available in Trusted Cloud by S3NS.

getShieldedVmIdentity

The method compute.beta.InstancesService.GetShieldedVmIdentity is not available in Trusted Cloud by S3NS.

insert

The method compute.beta.InstancesService.Insert is not available in Trusted Cloud by S3NS.

list

The method compute.beta.InstancesService.List is not available in Trusted Cloud by S3NS.

listReferrers

The method compute.beta.InstancesService.ListReferrers is not available in Trusted Cloud by S3NS.

patchPartnerMetadata

The method compute.beta.InstancesService.PatchPartnerMetadata is not available in Trusted Cloud by S3NS.

performMaintenance

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

removeResourcePolicies

The method compute.beta.InstancesService.RemoveResourcePolicies is not available in Trusted Cloud by S3NS.

reportHostAsFaulty

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

reset

The method compute.beta.InstancesService.Reset is not available in Trusted Cloud by S3NS.

resume

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

sendDiagnosticInterrupt

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

setDeletionProtection

The method compute.beta.InstancesService.SetDeletionProtection is not available in Trusted Cloud by S3NS.

setDiskAutoDelete

The method compute.beta.InstancesService.SetDiskAutoDelete is not available in Trusted Cloud by S3NS.

setIamPolicy

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

setLabels

The method compute.beta.InstancesService.SetLabels is not available in Trusted Cloud by S3NS.

setMachineResources

The method compute.beta.InstancesService.SetMachineResources is not available in Trusted Cloud by S3NS.

setMachineType

The method compute.beta.InstancesService.SetMachineType is not available in Trusted Cloud by S3NS.

setMetadata

The method compute.beta.InstancesService.SetMetadata is not available in Trusted Cloud by S3NS.

setMinCpuPlatform

The method compute.beta.InstancesService.SetMinCpuPlatform is not available in Trusted Cloud by S3NS.

setName

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

setScheduling

The method compute.beta.InstancesService.SetScheduling is not available in Trusted Cloud by S3NS.

setSecurityPolicy

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

setServiceAccount

The method compute.beta.InstancesService.SetServiceAccount is not available in Trusted Cloud by S3NS.

setShieldedInstanceIntegrityPolicy

The method compute.beta.InstancesService.SetShieldedInstanceIntegrityPolicy is not available in Trusted Cloud by S3NS.

setShieldedVmIntegrityPolicy

The method compute.beta.InstancesService.SetShieldedVmIntegrityPolicy is not available in Trusted Cloud by S3NS.

setTags

The method compute.beta.InstancesService.SetTags is not available in Trusted Cloud by S3NS.

simulateMaintenanceEvent

The method compute.beta.InstancesService.SimulateMaintenanceEvent is not available in Trusted Cloud by S3NS.

start

The method compute.beta.InstancesService.Start is not available in Trusted Cloud by S3NS.

startWithEncryptionKey

The method compute.beta.InstancesService.StartWithEncryptionKey is not available in Trusted Cloud by S3NS.

stop

The method compute.beta.InstancesService.Stop is not available in Trusted Cloud by S3NS.

suspend

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

testIamPermissions

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

update

The method compute.beta.InstancesService.Update is not available in Trusted Cloud by S3NS.

updateAccessConfig

The method compute.beta.InstancesService.UpdateAccessConfig is not available in Trusted Cloud by S3NS.

updateDisplayDevice

The method compute.beta.InstancesService.UpdateDisplayDevice is not available in Trusted Cloud by S3NS.

updateNetworkInterface

The method compute.beta.InstancesService.UpdateNetworkInterface is not available in Trusted Cloud by S3NS.

updateShieldedInstanceConfig

The method compute.beta.InstancesService.UpdateShieldedInstanceConfig is not available in Trusted Cloud by S3NS.

updateShieldedVmConfig

The method compute.beta.InstancesService.UpdateShieldedVmConfig is not available in Trusted Cloud by S3NS.