Creating a VM Instance from an Instance Template

This page explains how to use an instance template to create a VM instance. An instance template is an API resource that defines the properties of VM instances. You define properties like the machine type, OS image, persistent disk configurations, metadata, startup scripts, and so on, in an instance template and then can use the instance template to create individual VM instances or groups of managed instances.

When you create a VM instance from an instance template, the default behavior is to create a VM instance that is identical to the properties specified in the template, with the exception of the VM instance name and the zone where the instance will live. Alternatively, you can also optionally override certain fields during instance creation if you want to change certain properties of the instance template for specific uses.

This document assumes that you have an instance template ready to use. If you do not have an instance template, follow the instructions to create a new instance template.

Before you begin

Creating a VM instance from an instance template

To create an instance exactly as described in the instance template, follow these instructions.

Console

  1. Go to the VM instances page.

    Go to the VM instances page

  2. Click Create instance.
  3. Click New VM instance from template.
  4. Select your template and click Continue.
  5. Specify a name for your instance and make further customizations as needed.
  6. Click Create. Read create an instance for additional setup details.

gcloud

With gcloud compute, use the same instances create command that you would use to create a normal instance, but add the --source-instance-template flag:

gcloud compute instances create [INSTANCE_NAME] --source-instance-template [INSTANCE_TEMPLATE_NAME]

where:

  • [INSTANCE_NAME] is the name of the instance.

  • [INSTANCE_TEMPLATE_NAME] is the name of the instance template to use.

    For example:

    gcloud compute instances create example-instance --source-instance-template my-instance-template

API

In the API, construct a normal request to create an instance but include the sourceInstanceTemplate query parameter followed by a qualified path to an instance template.

POST https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances?sourceInstanceTemplate=[INSTANCE_TEMPLATE_NAME]

In the request body, provide a name for the VM instance:

{ "name": "example-instance" }

For example, the following snippet includes a fully-qualified path to the template: https://compute.googleapis.com/compute/v1/projects/myproject/global/instanceTemplates/example-instance-template.

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances?sourceInstanceTemplate=https://compute.googleapis.com/compute/v1/projects/myproject/global/instanceTemplates/example-instance-template

{ "name": "example-instance" }

Creating a VM instance from an instance template with overrides

When you use an instance template to start a VM instance, the default behavior is to create a VM instance exactly as described in the instance template with the exception of the instance name and zone.

If you want to create an instance primarily based on an instance template but with a few changes, you can use the override behavior. To use the override behavior, you pass in attributes to override for the existing instance template when creating the instance.

gcloud

Using the gcloud tool, make a request to create an instance with the --source-instance-template flag and override any property you want with the appropriate gcloud flag. To see a list of applicable flags, review the gcloud reference.

For example, to override the machine type, metadata, operating system, a boot persistent disk, and a secondary disk of an instance template, provide following flags:

gcloud compute instances create example-instance --source-instance-template example-instance \
    --machine-type n1-standard-2 --image-family debian-8 --image-project debian-cloud \
    --metadata bread=butter --disk=boot=no,name=my-override-disk

API

In the API, use the sourceInstanceTemplate query parameter and provide any fields you want to override in the request body when constructing a normal request to create an instance.

The override behavior in the API follows the JSON merge patch rules, described by RFC 7396.

Specifically:

  • If you override a primitive field, the corresponding primitive field in the instance template will be replaced with the primitive field value in the request. Primitive fields include machineType, sourceImage, name, and so on.
  • If you override a repeated field, all repeated values for that property will be replaced with the corresponding values provided in the request. Repeated fields are generally properties of type list. For example, disks and networkInterfaces are repeated fields.
  • If you override a nested object, the object in the instance template will be merged with the corresponding object specification in the request. Note that if a nested object lives within a repeated field, the field is treated according to rules for repeated fields. Labels are an exception to this rule, and are treated as a repeated field even though it is of type object.

For example, let's assume you have an instance template with two non-boot disks but you want to override one of the disks. You must provide the entire disks specification in your request, including any disks you want to keep.

The URL for this request:

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances?sourceInstanceTemplate=https://compute.googleapis.com/compute/v1/projects/myproject/global/instanceTemplates/example-instance-template

The request body:

{
  "disks": [
    {
      # Since you are overriding the repeated disk property, you must
      # specify a boot disk in the request, even if it is already
      # specified in the instance template
      "autoDelete": true,
      "boot": true,
      "initializeParams": {
        "sourceImage": "projects/debian-cloud/global/images/family/debian-8"
      },
      "mode": "READ_WRITE",
      "type": "PERSISTENT"
    },
    {
      # New disk you want to use
      "autoDelete": false,
      "boot": false,
      "mode": "READ_WRITE",
      "source": "zones/us-central1-f/disks/my-override-disk",
      "type": "PERSISTENT"
    },
    {
       # Assume this disk is already specified in instance template, but
       # you must specify it again since you are overriding the disks
       # property
      "autoDelete": false,
      "boot": false,
      "mode": "READ_WRITE",

      "source": "zones/us-central1-f/disks/my-other-disk-to-keep",
      "type": "PERSISTENT"
    }
  ],
  "machineType": "zones/us-central1-f/machineTypes/n1-standard-2",
  "name": "example-instance"
}

What's next