Google Cloud Platform
Hide
Compute Engine
Write Feedback

InstanceTemplates

Defines an Instance Template resource that provides configuration settings for your virtual machine instances. Instance templates are not tied to the lifetime of an instance and can be used and reused as to deploy virtual machines. You can also use different templates to create different virtual machine configurations. Instance templates are required when you use the Instance Group Manager API.

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

Resource representations

An Instance Template resource. 

{
  "kind": "compute#instanceTemplate",
  "id": unsigned long,
  "creationTimestamp": string,
  "selfLink": string,
  "name": string,
  "description": string,
  "properties": {
    "description": string,
    "tags": {
      "items": [
        string
      ],
      "fingerprint": bytes
    },
    "machineType": string,
    "canIpForward": boolean,
    "networkInterfaces": [
      {
        "network": string,
        "networkIP": 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
        ],
        "interface": string
      }
    ],
    "metadata": {
      "kind": "compute#metadata",
      "fingerprint": bytes,
      "items": [
        {
          "key": string,
          "value": string
        }
      ]
    },
    "serviceAccounts": [
      {
        "email": string,
        "scopes": [
          string
        ]
      }
    ],
    "scheduling": {
      "onHostMaintenance": string,
      "automaticRestart": boolean
    }
  }
}
Property name Value Description Notes
creationTimestamp string [Output Only] Creation timestamp in RFC3339 text format.
description string An optional textual description of the instance template resource; provided by the client when the resource is created.
id unsigned long [Output Only] Unique identifier for the resource; defined by the server.
kind string [Output Only] Type of the resource. Always compute#instanceTemplate.
name string Name of the resource; provided by the client when the resource is created. The name must be 1-63 characters long, and omply 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.
properties nested object The instance properties portion of this instance template resource.
properties.canIpForward boolean Enables instances created based on this template to send packets with source IP addresses other than their own and receive packets with destination IP addresses other than their own. If these instances will be used as an IP gateway or it will be set as the next-hop in a Route resource, say true. If unsure, leave this set to false. See the canIpForwarddocumentation for more information.
properties.description string An optional textual description for the instances created based on the instance template resource; provided by the client when the template is created.
properties.disks[] list Array of disks associated with instance created based on this template.
properties.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).
properties.disks[].boot boolean Indicates that this is a boot disk. The virtual machine will use the first partition of the disk for its root filesystem.
properties.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.
properties.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.
properties.disks[].initializeParams nested object Initialization parameters.
properties.disks[].initializeParams.diskName string Name of the disk. When not provided, this defaults to the name of the instance. If provided, the instance template can only create one virtual machine per zone.
properties.disks[].initializeParams.diskSizeGb long Size of the disk in base-2 GB.
properties.disks[].initializeParams.diskType string The name, not URL, of Disk Type resource describing which disk type to use to create the disk; provided by the client when the disk is created. Valid values include:
  • pd-ssd
  • pd-standard
  • local-ssd
properties.disks[].initializeParams.sourceImage string The source image used to create this disk. You must define either a sourceImage (which creates a new boot disk) or the source property (which uses an existing boot disk) when creating a virtual machine but cannot define both in your configuration.

You can provide a private (custom) image using the following input, and Compute Engine will use the corresponding image from your project. For example:

global/images/my-private-image

Or you can provide an from a publicly-available project. For example, to use a Debian image from the debian-cloud project, make sure to include the project in the URL:

projects/debian-cloud/global/images/debian-7-wheezy-vYYYYMMDD 

where vYYYYMMDD is the image version. The fully-qualified URL will also work in both cases.
properties.disks[].interface string Specifies the disk interface to use for attaching this disk. The default is SCSI. For performance characteristics of SCSI over NVMe, see Local SSD performance. 

Acceptable values are:
  • "NVME": Attaches the disk using NVMe interface. You can only attach a non-root local SSD data disk with NVMe.
  • "SCSI": Attaches the disk using SCSI interface. This is the default interface.
properties.disks[].kind string [Output Only] The type of the resource. Always compute#attachedDisk for Disk resources.
properties.disks[].licenses[] list [Output Only] Publicly visible licenses.
properties.disks[].mode string The mode in which to attach this disk, either READ_WRITE or READ_ONLY. If you are attaching or creating a boot disk, this must read-write mode. If you are attaching a non-boot data disk, you can attach the disk to one instance in read-write mode, or attach to multiple instances in read-only mode.

Acceptable values are:
  • "READ_ONLY": Attaches this disk in read-only mode.
  • "READ_WRITE": [Default] Attaches this disk in read-write mode.
properties.disks[].source string The name (not URL) of an existing persistent disk to use for this template. Specifying this option tells the service to look for an existing persistent disk in the zone that the instance group is deployed.
properties.disks[].type string Type of the disk. If not specified, the default is PERSISTENT.

Acceptable values are:
  • "PERSISTENT": [Default] Indicates a persistent disk.
  • "SCRATCH": Indicates a scratch disk, such as a local SSD.
properties.machineType string Name of the machine type resource describing which machine type to use to host the instances created based on this template. Notice this differs from how the machine type is specified in the Compute Engine API, as the machine type name is required for instance templates, whereas the machine type URL is required in the API. For example, n1-standard-1.
properties.metadata nested object The metadata key/value pairs assigned to this instance. This includes custom metadata and predefined keys.
properties.metadata.fingerprint bytes Fingerprint of this resource. A hash of the metadata's contents. This field is used for optimistic locking. An up-to-date metadata fingerprint must be provided in order to modify metadata.
properties.metadata.items[] list Array of key/value pairs. The total size of all keys and values must be less than 512 KB.
properties.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.
properties.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.
properties.metadata.kind string [Output Only] The type of the resource. Always compute#metadata for metadata.
properties.networkInterfaces[] list An array of network interfaces for this virtual machines.
properties.networkInterfaces[].accessConfigs[] list 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.
properties.networkInterfaces[].accessConfigs[].kind string The type of the resource. Always compute#accessConfig for access configs.
properties.networkInterfaces[].accessConfigs[].name string Name of this access configuration.
properties.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.

If you specify an IP address, only one virtual machine can be created per region, since an external IP can only be assigned to one instance at a time.
properties.networkInterfaces[].accessConfigs[].type string Type of configuration. Must be set to ONE_TO_ONE_NAT.  

Acceptable values are:
  • "ONE_TO_ONE_NAT": [Default] Configures port-for-port NAT to the internet.
properties.networkInterfaces[].network string Specifies the URL of the network resource for this interface. This is required when inserting an instance template. For example, to specify the default network: 
global/networks/default

If you choose to specify this property, you can specify the network as a full or partial URL. For example, the following are all valid URLs:

  • https://www.googleapis.com/compute/v1/projects/myproject/global/networks/my-network
  • projects/myproject/global/networks/my-network
  • global/networks/default
properties.networkInterfaces[].networkIP string [Output Only] An IPV4 internal network address to assign to the instance for this network interface.
properties.scheduling nested object Scheduling options for the instances created based on this template.
properties.scheduling.automaticRestart boolean Specifies whether the instance should be automatically restarted if it is terminated by Compute Engine (not terminated by a user).
properties.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": [Default] 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.
properties.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.
properties.serviceAccounts[].email string Email address of the service account.
properties.serviceAccounts[].scopes[] list The list of scopes to be made available for this service account.
properties.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.
properties.tags.fingerprint bytes Fingerprint of this resource. A hash of the tags stored in this object. This field is used optimistic locking. An up-to-date tags fingerprint must be provided in order to modify tags.
properties.tags.items[] list An array of tags. Each tag must be 1-63 characters long, and comply with RFC1035.

Methods

delete
Deletes the specified instance template resource.
get
Returns the specified instance template resource.
insert
Creates an instance template resource in the specified project using the data included in the request.
list
Retrieves the list of instance template resources contained within the specified project.

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.