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.

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:

API

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.