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
- Read the Instance Template documentation.
- Create an instance template.
-
If you haven't already, then set up authentication.
Authentication is
the process by which your identity is verified for access to Google Cloud services and APIs.
To run code or samples from a local development environment, you can authenticate to
Compute Engine by selecting one of the following options:
Select the tab for how you plan to use the samples on this page:
Console
When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
-
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
- Set a default region and zone.
Go
To use the Go samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment.
Java
To use the Java samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment.
Node.js
To use the Node.js samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment.
Python
To use the Python samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment.
REST
To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.
-
Create a VM instance from an instance template
You can use either a regional or a global instance template to create a VM instance. To create an instance exactly as described in the instance template, follow these instructions.
Console
In the Google Cloud console, go to the Create an instance page.
Click New VM instance from template.
Select your template and click Continue.
Specify a name for your VM and make further customizations as needed.
Click Create.
For additional setup details, see Create a VM instance from an image.
gcloud
To create a VM from a regional or global instance template, use the same
gcloud compute instances create
command
that you would use to create a normal instance, but add the
--source-instance-template
flag:
gcloud compute instances create VM_NAME \ --source-instance-template INSTANCE_TEMPLATE_NAME
Replace the following:
VM_NAME
: the name of the instance.INSTANCE_TEMPLATE_NAME
: the name of the instance template to use. For a regional instance template, you must specify the full or partial URL of the template. An example of a full URL ishttps://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1/instanceTemplates/example-regional-instance-template
and a partial URL isprojects/example-project/regions/us-central1/instanceTemplates/example-regional-instance-template
.
For example:
gcloud compute instances create example-instance \ --source-instance-template my-instance-template
Go
Java
Node.js
Python
REST
To create a VM from a regional or global instance template, 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" }
Create 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 CLI, 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, provide the following flags to override the machine type, metadata, operating system, Persistent Disk boot disk, and a secondary disk of an instance template:
gcloud compute instances create example-instance \ --source-instance-template example-instance --machine-type e2-standard-2 \ --image-family debian-9 --image-project debian-cloud \ --metadata bread=butter --disk=boot=no,name=my-override-disk
Go
Java
Node.js
Python
REST
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 basic field, the corresponding basic field
in the instance template will be replaced with the basic field value
in the request. Basic 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/e2-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.