Creating Instance Templates

This page describes how to create and manage instance templates. Instance templates define the machine type, image, zone, and other instance properties for the instances in a managed instance group. You need an instance template before you can create a managed instance group.

To learn about instance templates, read the Instance Groups Overview.

Before you begin

Creating an instance template

An instance template is required for creating managed instance groups. A managed instance group contains identical virtual machine instances. To maintain these identical instances, the instance group uses the specified instance template to create VM instances for the group.

Any of the instance properties that you can define in a regular API request to create an individual VM instance can be described in the instance template, including any instance metadata, startup scripts, persistent disks, service accounts, and so on.

At a minimum, the same required properties for creating an instance are also required to create an instance template. See a list of the required fields on the instanceTemplates().insert reference.

Create an instance template through the Google Cloud Platform Console, gcloud compute tool, or the API.

Console

  1. In the Cloud Platform Console, go to the Instance Templates page.

    Go to the Instance templates page

  2. Click New instance template.
  3. Fill in the fields you want for your instance template, or accept the default values. The following values are provided by default:

    • Machine type: n1-standard-1
    • Image: The latest Debian image
    • Boot disk: A new standard boot disk named after the instance
    • VPC network: The default VPC network
    • IP address: An ephemeral external IP address
  4. Click Create to create the template.

gcloud

In gcloud compute, create an instance template using the instance-templates create command:

gcloud compute instance-templates create [INSTANCE_TEMPLATE]

where you replace [INSTANCE_TEMPLATE] with the desired name of the instance template.

If you do not provide explicit template settings, gcloud compute creates a template with the following default values:

  • Machine type: n1-standard-1
  • Image: The latest Debian image
  • Boot disk: A new standard boot disk named after the instance
  • Network: The default VPC network
  • IP address: An ephemeral external IP address

You can also explicitly provide these configuration settings. For example:

gcloud compute instance-templates create example-template-custom \
    --machine-type n1-standard-4 \
    --image-family debian-8 \
    --image-project debian-cloud \
    --boot-disk-size 250GB

You can see a list of available flags in the gcloud compute reference.

A template with the default configuration settings might look like the following:

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/family/debian-8
    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

API

In the instance template API, you must explicitly define all of the required configuration fields as described in the instanceTemplates().insert documentation. For example, an instance template with the minimal required fields looks like the following:

{
"name": "example-template",
"properties": {
  "machineType": "zones/us-central1-a/machineTypes/n1-standard-4",
  "networkInterfaces": [
    {
      "network": "global/networks/default",
      "accessConfigs":
      [
        {
          "name": "external-IP",
          "type": "ONE_TO_ONE_NAT"
        }
      ]
    }
  ],
  "disks":
  [
    {
      "type": "PERSISTENT",
      "boot": true,
      "mode": "READ_WRITE",
      "initializeParams":
      {
        "sourceImage": "projects/debian-cloud/global/images/family/debian-8"
      }
    }
  ]
  }
}

For the disks property, you must either provide the initializeParams property to create new persistent boot disks for each instance, or you can provide the source property to attach an existing persistent boot disk. If you attach an existing boot disk, you can only create one instance from your template.

Creating an instance template that specifies a subnet

Instance template commands now have --subnet and --region flags that place new instances into the subnet of your choice. The --subnet flag requires the --region flag. The subnet must exist before you can include it in an instance template.

gcloud compute instance-templates create [INSTANCE_TEMPLATE] \
    --region [REGION] \
    --subnet [SUBNET_NAME]

where you replace the following:

  • [INSTANCE_TEMPLATE] with the desired name of the instance template.
  • [REGION] with the region of the subnet.
  • [SUBNET_NAME] with the name of the subnet.

This example creates a template called template-qa that only creates instances in the subnet-us-qa subnet.

gcloud compute instance-templates create template-qa \
    --region us-central1 \
    --subnet subnet-us-qa
Created [https://www.googleapis.com/compute/latest/projects/PROJECT_ID/global/instanceTemplates/template-qa].
NAME        MACHINE_TYPE  PREEMPTIBLE CREATION_TIMESTAMP
template-qa n1-standard-1             2015-12-23T20:34:00.791-07:00

Using this template to create instances for a Managed Instance Group (with or without autoscaling) automatically creates the instance in the specified region and subnet. This lets you control the subnet of new instances created for load balancing.

Using custom or public images in your instance templates

Because managed instance groups are designed to add and remove instances frequently, it is useful to create a custom image and specify it in the instance template. Prepare your image with the applications and settings that your instances need so you don't have to manually configure those items on individual instances in the managed instance group.

Alternatively, you can create an instance template that uses a public image and a startup script to prepare the instance after it starts running. Custom image are more deterministic and start more quickly than instances with startup scripts. However, startup scripts are more flexible and allow you to update the applications and settings in your instances more easily.

Deterministic instance templates

In general, we recommend that the properties of your instance template are as explicit and deterministic as possible. If you employ startup scripts in your instance templates that install or use third-party services, 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-family debian-8 \
    --image-project debian-cloud \
    --metadata startup-script='#! /bin/bash
    sudo apt-get install -y 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 ]
    
  • Create a custom image to use as the image for the template. This is preferable to startup scripts as it guarantees every instance will be the same, while startup scripts might have different result after distribution package updates. Use startup scripts in your instance templates for prototyping and rapid development, and use custom images when you are ready to deploy production-quality services.

  • If you do use startup scripts, consider updating your scripts to be deterministic. For example, create a new version of the previous template, and specify a deterministic startup script as follows:

    gcloud compute instance-templates create example-template-with-startup-2-1-3 \
        --image-family debian-8 \
        --image-project debian-cloud \
        --metadata startup-script='#! /bin/bash
        sudo apt-get install -y 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.

Metadata and startup scripts

Instance templates accept metadata and startup scripts in the same way you would specify them when creating an instance directly. Any startup scripts and metadata you provide through the instance template apply to any new instances created or recreated from the template.

For example, if you set a metadata key:value pair in your instance template like so:

POST https://www.googleapis.com/compute/v1/projects/myproject/global/instanceTemplates

{
 "name": "example-instance-template",
 "properties": {
  "machineType": "n1-standard-1",
  "disks": [
    ...
   }
  ],
  "metadata": {
   "items": [
    {
     "key": "apple",
     "value": "red"
    }
   ]
  },
  ...
}

The metadata apple:red is applied to all instances that you create from this instance template.

Updating an instance template

It is not possible to update an existing instance template or change an instance template after it has been created. If an instance template goes out of date, or you need to make changes to the configuration, create a new instance template.

Getting information about an instance template

Console

  1. In the Cloud Platform Console, go to the Instance Templates page.

    Go to the Instance templates page

  2. Click the name of the instance template to see the details of the template.

gcloud

Using the gcloud command-line tool, run:

gcloud compute instance-templates describe [INSTANCE_TEMPLATE]

API

In the API, make a instanceTemplates().get request:

GET https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/instanceTemplates/[INSTANCE_TEMPLATE]

Listing instance templates

To get a list of instance templates you created:

Console

The Instance Templates page lists all of the instance templates in your project.

Go to the Instance Templates page

gcloud

Using the gcloud command-line tool, run:

gcloud compute instance-templates list

API

In the API, make a instanceTemplates().list request:

GET https://www.googleapis.com/compute/v1/projects/myproject/global/instanceTemplates

Deleting an instance template

Deleting an instance template removes it from your list of templates. You cannot delete an instance template if a managed instance group references it.

Console

  1. In the Cloud Platform Console, go to the Instance Templates page.

    Go to the Instance Templates page

  2. Select the instance templates you want to delete.
  3. Click Delete.

gcloud

Using the gcloud command-line tool, run:

gcloud compute instance-templates delete example-template

API

In the API, make a instanceTemplates().delete request:

DELETE https://www.googleapis.com/compute/v1/projects/myproject/global/instanceTemplates/example-template

Sometimes the instances in a managed instance group can be out of sync with the rest of the group, and use a different instance template than the rest of the group. If an instance in a managed instance group uses a different template than what is specified on the group, that instance will continue to use its template for autohealing events even if that template is deleted. To update an instance to the new template, recreate that instance.

What's next

Send feedback about...

Compute Engine Documentation