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
- If you want to use the command-line examples in this guide:
- Install or update to the latest version of the gcloud command-line tool.
- Set a default region and zone.
- If you want to use the API examples in this guide, set up API access.
- Read the Instance Template documentation.
- Create an instance template.
Creating a VM instance from an instance template
To create an instance exactly as described in the instance template, follow these instructions.
Console
- Go to the VM instances page.
- Click Create instance.
- Click New VM instance from template.
- Select your template and click Continue.
- Specify a name for your instance and make further customizations as needed.
- 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
andnetworkInterfaces
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 typeobject
.
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
- Read the Preemptible VM instances documentation.
- Read about Shutdown scripts.
- Refer to the preemptible instance pricing.
- Connect to your instance.