Please note that the contents of this offline web site may be out of date. To access the most recent documentation visit the online version .
Note that links that point to online resources are green in color and will open in a new window.
We would love it if you could give us feedback about this material by filling this form (You have to be online to fill it)



Instances

Represents an Instance resource. See the Instance documentation for more information.

For a list of methods for this resource, see the end of this page.

Resource representations

An Instance resource. 

{
  "kind": "compute#instance",
  "id": unsigned long,
  "creationTimestamp": string,
  "zone": string,
  "status": string,
  "statusMessage": string,
  "name": string,
  "description": string,
  "tags": {
    "items": [
      string
    ],
    "fingerprint": bytes
  },
  "machineType": string,
  "canIpForward": boolean,
  "networkInterfaces": [
    {
      "network": string,
      "networkIP": string,
      "name": string,
      "accessConfigs": [
        {
          "kind": "compute#accessConfig",
          "type": string,
          "name": string,
          "natIP": string
        }
      ]
    }
  ],
  "disks": [
    {
      "kind": "compute#attachedDisk",
      "index": integer,
      "type": string,
      "mode": string,
      "source": string,
      "deviceName": string,
      "boot": boolean,
      "initializeParams": {
        "diskName": string,
        "sourceImage": string,
        "diskSizeGb": long,
        "diskType": string
      },
      "autoDelete": boolean,
      "licenses": [
        string
      ]
    }
  ],
  "metadata": {
    "kind": "compute#metadata",
    "fingerprint": bytes,
    "items": [
      {
        "key": string,
        "value": string
      }
    ]
  },
  "serviceAccounts": [
    {
      "email": string,
      "scopes": [
        string
      ]
    }
  ],
  "selfLink": string,
  "scheduling": {
    "onHostMaintenance": string,
    "automaticRestart": boolean
  }
}
Property name Value Description Notes
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 .
creationTimestamp string [Output Only] Creation timestamp in RFC3339 text format.
description string An optional textual description of the resource; provided by the client when the resource is created.
disks[] list Array of disks associated with this instance. Persistent disks must be created before you can assign them.
disks[]. autoDelete boolean Whether the disk will be auto-deleted when the instance is deleted (but not when the disk is detached from the instance).
disks[]. boot boolean Indicates that this is a boot disk. VM will use the first partition of the disk for its root filesystem.
disks[]. deviceName string A unique device name that is reflected into the /dev/ tree of a Linux operating system running within the instance. If not specified, the server chooses a default device name to apply to this disk, in the form persistent-disks- x , where x is a number assigned by Google Compute Engine. This field is only applicable for persistent disks.
disks[]. index integer [Output Only] A zero-based index to assign to this disk, where 0 is reserved for the boot disk. If not specified, the server chooses an appropriate value.
disks[]. initializeParams nested object Initialization parameters.
disks[].initializeParams. diskName string Name of the disk (when not provided defaults to the name of the instance).
disks[].initializeParams. diskSizeGb long Size of the disk in base-2 GB.
disks[].initializeParams. diskType string URL of the disk type resource describing which disk type to use to create the disk; provided by the client when the disk is created. For example: 
https://www.googleapis.com/compute/v1/projects/<project-id>/zones/<zone>/diskTypes/<disk-type>
disks[].initializeParams. sourceImage string The source image used to create this disk.
disks[]. kind string [Output Only] The type of the resource. Always compute#attachedDisk for Disk resources.
disks[]. licenses[] list Public visible licenses.
disks[]. mode string The mode to attach this persistent disk, either READ_WRITE or READ_ONLY .

Acceptable values are:
  • " READ_ONLY ": Attaches this disk in read-only mode.
  • " READ_WRITE ": Attaches this disk in read-write mode.
disks[]. source string The fully-qualified URL of the Persistent Disk resource. This field is only applicable for persistent disks.
disks[]. type string The type of the disk.

Acceptable values are:
  • " PERSISTENT ": Indicates a persistent disk.
  • " SCRATCH ": [Deprecated] Indicates an ephemeral or scratch disk.
id unsigned long [Output Only] Unique identifier for the resource. This is generated by the server.
kind string [Output Only] The type of the resource. This is always compute#instance for Instance resources.
machineType string Fully-qualified URL of the machine type resource to use for the instance. This is provided by the client during instance creation.
metadata nested object The metadata key/value pairs assigned to this instance. This includes custom metadata and predefined keys.
metadata. fingerprint bytes Fingerprint of the metadata; a hash of the metadata's contents. This field is used for optimistic locking. Only required when updating a running instance's metadata entries.
metadata. items[] list Array of key/value pairs. The total size of all keys and values must be less than 512 KB.
metadata.items[]. key string Key for the metadata entry. Keys must conform to the following regexp: [a-zA-Z0-9-_]+, and be less than 128 bytes in length. This is reflected as part of a URL in the metadata server. Additionally, to avoid ambiguity, keys must not conflict with any other metadata keys for the project.
metadata.items[]. value string Value for the metadata entry. These are free-form strings, and only have meaning as interpreted by the image running in the instance. The only restriction placed on values is that their size must be less than or equal to 32768 bytes.
metadata. kind string The type of the resource. Always compute#metadata for metadata.
name string Name of the resource; provided by the client when the resource is created. 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.
networkInterfaces[] list An array of configurations for this interface. This specifies how this interface is configured to interact with other network services, such as connecting to the internet. Currently, ONE_TO_ONE_NAT is the only access config supported. If there are no accessConfigs specified, then this instance will have no external internet access.
networkInterfaces[]. accessConfigs[] list An array of configurations for this interface. This specifies how this interface is configured to interact with other network services, such as connecting to the internet. Currently, ONE_TO_ONE_NAT is the only access config supported. If there are no accessConfigs specified, then this instance will have no external internet access.
networkInterfaces[].accessConfigs[]. kind string The type of the resource. Always compute#accessConfig for access configs.
networkInterfaces[].accessConfigs[]. name string Name of this access configuration.
networkInterfaces[].accessConfigs[]. natIP string An external IP address associated with this instance. Specify an unused reserved IP address available to the project or leave this field undefined to use an IP from a shared ephemeral IP address pool. If you specify a reserved IP address, it must reside in the same region as the zone of the instance.
networkInterfaces[].accessConfigs[]. type string Type of configuration. Must be set to ONE_TO_ONE_NAT .

Acceptable values are:
  • " ONE_TO_ONE_NAT ": Configures port-for-port NAT to the internet.
networkInterfaces[]. name string [Output Only] The name of the network interface, generated by the server. For network devices, these are eth0 , eth1 , etc.
networkInterfaces[]. network string Output Only] The name of the network interface, generated by the server. For network devices, these are eth0 , eth1 , etc. URL of the network resource attached to this interface.
networkInterfaces[]. networkIP string [Output Only] An IPV4 internal network address to assign to the instance for this network interface.
scheduling nested object Scheduling options for this instance. The level of maintenance which the Instance should tolerate.
scheduling. automaticRestart boolean Specifies whether the instance should be automatically restarted if it is terminated by Compute Engine (not terminated by a user).
scheduling. onHostMaintenance string Defines the maintenance behavior for this instance. The default behavior is migrate. For more information, see Setting maintenance behavior .


Acceptable values are:
  • " MIGRATE ": Allows Compute Engine to automatically migrate instances out of the way of maintenance events.
  • " TERMINATE ": Tells Compute Engine to terminate and (optionally) restart the instance away from the maintenance activity. If you would like your instance to be restarted, set the automaticRestart flag to true. Your instance may be restarted more than once, and it may be restarted outside the window of maintenance events.

serviceAccounts[] list A list of service accounts, with their specified scopes, authorized for this instance. Service accounts generate access tokens that can be accessed through the metadata server and used to authenticate applications on the instance. See Authenticating from Google Compute Engine for more information.
serviceAccounts[]. email string Email address of the service account.
serviceAccounts[]. scopes[] list The list of scopes to be made available for this service account.
status string [Output Only] The status of this instance.


Acceptable values are:
  • " PROVISIONING ": The instance is currently being provisioned.
  • " RUNNING ": The instance is running.
  • " STAGING ": The instance is being staged.
  • " STOPPED ": The instance has been stopped.
  • " STOPPING ": The instance is in the process of being stopped.
  • " TERMINATED ": The instance has been terminated.
statusMessage string [Output Only] An optional, human-readable explanation of the instance status.
tags nested object A list of tags to appy 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 .
tags. fingerprint bytes The fingerprint of this resource; a hash of the tags stored in this object. This field is used optimistic locking. Only required for updating a running instance's tags. An up-to-date tags fingerprint must be provided in order to modify tags.
tags. items[] list An array of tags. Each tag must be 1-63 characters long, and comply with RFC1035 .
zone string [Output Only] Fully-qualified URL of the Zone resource describing  zone this instance should live in.

Methods

The following are valid Instance resource methods:

addAccessConfig
Adds an access config to an instance's network interface.
aggregatedList
Retrieves the list of Instance resources across all available zones.
attachDisk
Attaches a Persistent Disk resource to an instance.


You can also attach one persistent disk to multiple instances in read-only mode; it is not possible to attach one persistent disk to multiple instances in read-write mode.
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.
getSerialPortOutput
Returns the specified instance's serial port output.
insert
Creates an instance resource in the specified project using the data included in the request.
list
Retrieves the list of instance resources contained within the specified zone.
reset
Performs a hard reset on the instance.
setDiskAutoDelete
Sets the auto-delete flag for a disk attached to an instance
setMetadata
Sets metadata for the specified instance to the data included in the request.
setScheduling
Sets an instance's scheduling options.
setTags
Sets tags for the specified instance to the data included in the request.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License , and code samples are licensed under the Apache 2.0 License . For details, see our Site Policies .

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.