Instance Templates

An instance template can define some or all of the configuration options for your virtual machines, including the machine type, image, zone, and other settings. You can create an instance template once and reuse the template for multiple API requests. You can also create different instance templates for different configurations.

As a global resource, instance templates are not bound to a zone or region. However, as described in the Resource Overview, some resources, such as persistent disks, are zonal resources, which can limit where you deploy a particular virtual machines using your instance template.

Contents

Creating an instance template

An instance template describes how a virtual machine should be configured. The minimal requirements for creating a virtual machine are also required for creating an instance template. You can see a list of the required fields on the instancesTemplates().insert reference.

Creating an instance template does not create any virtual machines. To use an instance template to start virtual machines, you must use the instance template in a managed instance group.

You can create an instance template through the API, or using the gcloud compute tool.

$ gcloud compute instance-templates create example-template

$ gcloud compute instance-templates create example-template-custom \
         --machine-type n1-standard-4 \
         --image debian-7 \
         --boot-disk-size 250GB

$ gcloud compute instance-templates describe example-template
creationTimestamp: '2014-09-10T16:18:32.042-07:00'
description: ''
id: '6057583701980539406'
kind: compute#instanceTemplate
name: example-template
properties:
  canIpForward: false
  disks:
  - autoDelete: true
    boot: true
    initializeParams:
      sourceImage: https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/backports-debian-7-wheezy-vYYYYMMDD
    kind: compute#attachedDisk
    mode: READ_WRITE
    type: PERSISTENT
  machineType: n1-standard-1
  networkInterfaces:
  - accessConfigs:
    - kind: compute#accessConfig
      name: external-nat
      type: ONE_TO_ONE_NAT
    network: https://www.googleapis.com/compute/v1/projects/myproject/global/networks/default
  scheduling:
    automaticRestart: true
    onHostMaintenance: MIGRATE
  serviceAccounts:
  - email: default
    scopes:
    - https://www.googleapis.com/auth/devstorage.read_only
selfLink: https://www.googleapis.com/compute/v1/projects/myproject/global/instanceTemplates/example-template

{
"name": "example-template",
"properties": {
  "machineType": "https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/machineTypes/n1-standard-4",
  "networkInterfaces": [
    {
      "network": "https://www.googleapis.com/compute/v1/projects/myproject/global/networks/default",
      "accessConfigs":
      [
        {
          "name": "external-IP",
          "type": "ONE_TO_ONE_NAT"
        }
      ]
    }
  ],
  "disks":
  [
    {
      "type": "PERSISTENT",
      "boot": true,
      "mode": "READ_WRITE",
      "initializeParams":
      {
        "sourceImage": "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-7-wheezy-vYYYYMMDD"
      }
    }
  ]
  }
}

Single-instance properties

When you use instance templates with the Instance Group Manager service, you can create many virtual machines with the same configuration. However, certain instance properties can only be applied to one virtual machine at a time. As such, if you specify these properties in your instance template, the Instance Group Manager service can only create one virtual machine for the instance group.

The following is a list of single-instance properties, with more information provided in each of the subsections below.

Boot disks

In an Instance Template resource, you can create a boot persistent disk alongside the virtual machine instance, or you can attach an existing boot persistent disk to newly-created virtual machines. Since boot persistent disks can only be attached to a single virtual machine at a time, any time you provide an explicit persistent boot disk name:

• Compute Engine will only be able to create one persistent boot disk with that disk name for one virtual machine per zone.
• If you are attaching an existing persistent boot disk, the instance template can be used to create only one virtual machine per zone.

If you want to create more than one virtual machine per zone using your instance template, do not provide an explicit disk name if you use the initializeParams property in your template and do not specify an existing boot persistent disk.

External IPs

If you provide a reserved IP address using the properties.networkInterfaces.accessConfigs.natIP property, Compute Engine will only create a single virtual machine instance because external IP addresses can be used by only one virtual machine at a time.

If you do not specify a reserved IP address, Compute Engine will use ephemeral IP address for each virtual machine that is created using the instance template.

Deterministic instance templates

In general, we recommend that the properties of your instance template are as explicit (or deterministic) as possible. Specifically, if you employ startup scripts in your instance templates that install or use third-party services, you should make sure that these scripts provide explicit information, such as the version of application to install. Compute Engine can only rely on information defined in the template and has no control over referenced third-party services. If your template is too vague, your instance template might behave unexpectedly.

For example, consider the following command to create an instance template with a startup script that installs apache2 and uses a file that is hosted on an external server:

$ gcloud compute instance-templates create example-template-with-startup \
         --image debian-7 \
         --metadata startup-script='#! /bin/bash
         sudo apt-get install apache2
         scp myuser@108.59.87.185:index.php /var/www/'

There are two potential issues with this startup script:

• The script does not explicitly define which version of apache2 to install, and relies on the current version available in the apt-get repository.
• The script relies on a file hosted on a third-party that isn’t versioned and could have been changed since the last time the instance template was used.

If you use an autoscaler, a non-deterministic instance template could cause your autoscaler to add new instances to a managed instance group with a different configuration, such as a different version of apache2.

Similarly, if you applied this template to a managed instance group, updated the group to a different template using the Instance Group Updater service, and then decided to rollback to the previous template, you might end up with instances using a different version of apache2 or index.php file than before the update, because your instances would always fetch the most recent version at startup.

To avoid unexpected template behavior, use one the following methods:

• Use Container-optimized images or Docker, with Docker tags. For example, we recommend that you assign new tags for every new build of your Docker image, and use these tags in your instance templates, instead of the default latest tag. For a Container-optimized image, you can explicitly reference a particular build of your image in your manifest file. The example below uses Docker image “myimage” at version tagged with “version_2_1_3”:

  version: v1beta2
  containers:
    - name: simple-echo
      image: myimage:version_2_1_3
         [ rest of your manifest file ]
  

• Use custom images or disk snapshots rather than startup scripts.

• If you want to use startup scripts, consider updating your scripts to be deterministic. For example, the preview startup script could be updated as follows:

  $ gcloud compute instance-templates create example-template-with-startup\
           --image debian-7 \
           --metadata startup-script='#! /bin/bash
           sudo apt-get install apache2=2.2.20-1ubuntu1
           scp myuser@108.59.87.185:version_2_1_3/index.php /var/www/'
  

  where “version_2_1_3” is a subdirectory containing PHP scripts for the version 2.1.3 of your service.

Updating an instance template

It isn't possible to update an existing instance template or change an instance template in any way. If an instance template goes out of date, or you need to make changes to the configuration, you need to create a new instance template.

Get information about an instance template

To get the details of an instance template:

$ gcloud compute instance-templates describe example-template

Listing instance templates

To get a list of available instance templates, run:

$ gcloud compute instance-templates list

Deleting an instance template

Deleting an instance template removes it from your project and, if the instance template is being used by a managed instance group, the instance group will not be able to create new virtual machines or recreate virtual machines. Deleting an instance template is permanent and could potentially break existing instance groups. If you are aware of the risks and would still like to delete an instance template, run:

$ gcloud compute instance-templates delete example-template

Getting help

For questions and feedback about instance templates, please email the Open Preview discussion group.

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.