Create a VM 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

  • Read the Instance Template documentation.
  • Create an instance template.
  • If you haven't already, set up authentication. Authentication verifies your identity 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

    1. Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command: 

      gcloudinit

      If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    2. 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.

      If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

      If you're using a local shell, then create local authentication credentials for your user account: 

      gcloudauthapplication-defaultlogin

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    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.

      If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

      If you're using a local shell, then create local authentication credentials for your user account: 

      gcloudauthapplication-defaultlogin

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    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.

      If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

      If you're using a local shell, then create local authentication credentials for your user account: 

      gcloudauthapplication-defaultlogin

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    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.

      If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

      If you're using a local shell, then create local authentication credentials for your user account: 

      gcloudauthapplication-defaultlogin

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    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.

      If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    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

  1. In the Google Cloud console, go to the Create an instance page.

    Go to Create an instance

  2. In the Create VM from ... menu, select Instance templates.

  3. In the Create VM from template window that appears, do the following:

    1. Select a template.

    2. To create and start the VM, click Create.

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_URL

Replace the following:

  • VM_NAME: the name of the instance.
  • INSTANCE_TEMPLATE_URL: the URL of the instance template that you want to use to create VMs in the MIG. The URL can contain either the ID or name of the instance template. Specify one of the following values:
    • For a regional instance template: projects/PROJECT_ID/regions/REGION/instanceTemplates/INSTANCE_TEMPLATE_ID
    • For a global instance template: INSTANCE_TEMPLATE_ID

For example:

gcloud compute instances create example-instance \
 --source-instance-template 1234567890

Go 

import(
"context"
"fmt"
"io"
compute"cloud.google.com/go/compute/apiv1"
computepb"cloud.google.com/go/compute/apiv1/computepb"
"google.golang.org/protobuf/proto"
)
// createInstanceFromTemplate creates a Compute Engine VM instance from an instance template.
funccreateInstanceFromTemplate(wio.Writer,projectID,zone,instanceName,instanceTemplateUrlstring)error{
// projectID := "your_project_id"
// zone := "europe-central2-b"
// instanceName := "your_instance_name"
// instanceTemplateUrl := "global/instanceTemplates/your_instance_template"
ctx:=context.Background()
instancesClient,err:=compute.NewInstancesRESTClient (ctx)
iferr!=nil{
returnfmt.Errorf("NewInstancesRESTClient: %w",err)
}
deferinstancesClient.Close()
req:=&computepb.InsertInstanceRequest{
Project:projectID,
Zone:zone,
InstanceResource:&computepb.Instance{
Name:proto.String(instanceName),
},
SourceInstanceTemplate:&instanceTemplateUrl,
}
op,err:=instancesClient.Insert(ctx,req)
iferr!=nil{
returnfmt.Errorf("unable to create instance: %w",err)
}
iferr=op.Wait(ctx);err!=nil{
returnfmt.Errorf("unable to wait for the operation: %w",err)
}
fmt.Fprintf(w,"Instance created\n")
returnnil
}

Java 


importcom.google.cloud.compute.v1.AttachedDisk ;
importcom.google.cloud.compute.v1.AttachedDiskInitializeParams ;
importcom.google.cloud.compute.v1.InsertInstanceRequest ;
importcom.google.cloud.compute.v1.Instance ;
importcom.google.cloud.compute.v1.InstanceProperties ;
importcom.google.cloud.compute.v1.InstanceTemplate ;
importcom.google.cloud.compute.v1.InstanceTemplatesClient ;
importcom.google.cloud.compute.v1.InstancesClient ;
importcom.google.cloud.compute.v1.Operation ;
importjava.io.IOException;
importjava.util.ArrayList;
importjava.util.List;
importjava.util.concurrent.ExecutionException;
importjava.util.concurrent.TimeUnit;
importjava.util.concurrent.TimeoutException;
publicclass CreateInstanceFromTemplate{
publicstaticvoidmain(String[]args)
throwsIOException,ExecutionException,InterruptedException,TimeoutException{
/* TODO(developer): Replace these variables before running the sample.
 projectId - ID or number of the project you want to use.
 zone - Name of the zone you want to check, for example: us-west3-b
 instanceName - Name of the new instance.
 instanceTemplateURL - URL of the instance template using for creating the new instance.
 It can be a full or partial URL.
 Examples:
 - https://www.googleapis.com/compute/v1/projects/project/global/instanceTemplates/example-instance-template
 - projects/project/global/instanceTemplates/example-instance-template
 - global/instanceTemplates/example-instance-template
 */
StringprojectId="your-project-id";
Stringzone="zone-name";
StringinstanceName="instance-name";
StringinstanceTemplateUrl="instance-template-url";
createInstanceFromTemplate(projectId,zone,instanceName,instanceTemplateUrl);
}
// Create a new instance from template in the specified project and zone.
publicstaticvoidcreateInstanceFromTemplate(StringprojectId,Stringzone,StringinstanceName,
StringinstanceTemplateName)
throwsIOException,ExecutionException,InterruptedException,TimeoutException{
try(InstancesClient instancesClient=InstancesClient .create();
InstanceTemplatesClient instanceTemplatesClient=InstanceTemplatesClient .create()){
InstanceTemplate instanceTemplate=instanceTemplatesClient.get(projectId,
instanceTemplateName);
// Adjust diskType field of the instance template to use the URL formatting 
// required by instances.insert.diskType
// For instance template, there is only a name, not URL.
List<AttachedDisk>reformattedAttachedDisks=newArrayList<>();
for(AttachedDisk disk:instanceTemplate.getProperties ().getDisksList()){
disk=AttachedDisk .newBuilder(disk)
.setInitializeParams (AttachedDiskInitializeParams
.newBuilder(disk.getInitializeParams())
.setDiskType(
String.format(
"zones/%s/diskTypes/%s",zone,disk.getInitializeParams().getDiskType()))
.build())
.build();
reformattedAttachedDisks.add(disk);
}
// Clear existing disks and set the reformatted disks in the instance template.
instanceTemplate=InstanceTemplate
.newBuilder(instanceTemplate)
.setProperties(InstanceProperties
.newBuilder(instanceTemplate.getProperties ())
.clearDisks()
.addAllDisks(reformattedAttachedDisks)
.build())
.build();
InsertInstanceRequest insertInstanceRequest=InsertInstanceRequest .newBuilder()
.setProject(projectId)
.setZone(zone)
.setInstanceResource(Instance .newBuilder().setName(instanceName).build())
.setSourceInstanceTemplate(instanceTemplate.getSelfLink ()).build();
Operation response=instancesClient.insertAsync(insertInstanceRequest)
.get(3,TimeUnit.MINUTES);
if(response.hasError ()){
System.out.println("Instance creation from template failed ! ! "+response);
return;
}
System.out
.printf("Instance creation from template: Operation Status %s: %s ",instanceName,
response.getStatus ());
}
}
}

Node.js 

/**
 * TODO(developer): Uncomment and replace these variables before running the sample.
 */
// const projectId = 'YOUR_PROJECT_ID';
// const zone = 'europe-central2-b'
// const instanceName = 'YOUR_INSTANCE_NAME'
// const instanceTemplateUrl = 'YOUR_INSTANCE_TEMPLATE_URL'
constcompute=require('@google-cloud/compute');
// Create a new instance from template in the specified project and zone.
asyncfunctioncreateInstanceFromTemplate(){
constinstancesClient=newcompute.InstancesClient ();
console.log(
`Creating the ${instanceName} instance in ${zone} from template ${instanceTemplateUrl}...`
);
const[response]=awaitinstancesClient.insert({
project:projectId,
zone,
instanceResource:{
name:instanceName,
},
sourceInstanceTemplate:instanceTemplateUrl,
});
letoperation=response.latestResponse;
constoperationsClient=newcompute.ZoneOperationsClient ();
// Wait for the create operation to complete.
while(operation.status!=='DONE'){
[operation]=awaitoperationsClient.wait({
operation:operation.name,
project:projectId,
zone:operation.zone.split('/').pop(),
});
}
console.log('Instance created.');
}
createInstanceFromTemplate();

Python 

from__future__import annotations
importsys
fromtypingimport Any
fromgoogle.api_core.extended_operationimport ExtendedOperation
fromgoogle.cloudimport compute_v1
defwait_for_extended_operation(
 operation: ExtendedOperation, verbose_name: str = "operation", timeout: int = 300
) -> Any:
"""
 Waits for the extended (long-running) operation to complete.
 If the operation is successful, it will return its result.
 If the operation ends with an error, an exception will be raised.
 If there were any warnings during the execution of the operation
 they will be printed to sys.stderr.
 Args:
 operation: a long-running operation you want to wait on.
 verbose_name: (optional) a more verbose name of the operation,
 used only during error and warning reporting.
 timeout: how long (in seconds) to wait for operation to finish.
 If None, wait indefinitely.
 Returns:
 Whatever the operation.result() returns.
 Raises:
 This method will raise the exception received from `operation.exception()`
 or RuntimeError if there is no exception set, but there is an `error_code`
 set for the `operation`.
 In case of an operation taking longer than `timeout` seconds to complete,
 a `concurrent.futures.TimeoutError` will be raised.
 """
 result = operation.result(timeout=timeout)
 if operation.error_code:
 print(
 f"Error during {verbose_name}: [Code: {operation.error_code}]: {operation.error_message}",
 file=sys.stderr,
 flush=True,
 )
 print(f"Operation ID: {operation.name}", file=sys.stderr, flush=True)
 raise operation.exception() or RuntimeError(operation.error_message)
 if operation.warnings:
 print(f"Warnings during {verbose_name}:\n", file=sys.stderr, flush=True)
 for warning in operation.warnings:
 print(f" - {warning.code}: {warning.message}", file=sys.stderr, flush=True)
 return result
defcreate_instance_from_template(
 project_id: str, zone: str, instance_name: str, instance_template_url: str
) -> compute_v1.Instance:
"""
 Creates a Compute Engine VM instance from an instance template.
 Args:
 project_id: ID or number of the project you want to use.
 zone: Name of the zone you want to check, for example: us-west3-b
 instance_name: Name of the new instance.
 instance_template_url: URL of the instance template used for creating the new instance.
 It can be a full or partial URL.
 Examples:
 - https://www.googleapis.com/compute/v1/projects/project/global/instanceTemplates/example-instance-template
 - projects/project/global/instanceTemplates/example-instance-template
 - global/instanceTemplates/example-instance-template
 Returns:
 Instance object.
 """
 instance_client = compute_v1 .InstancesClient ()
 instance_insert_request = compute_v1 .InsertInstanceRequest ()
 instance_insert_request.project = project_id
 instance_insert_request.zone = zone
 instance_insert_request.source_instance_template = instance_template_url
 instance_insert_request.instance_resource.name = instance_name
 operation = instance_client.insert (instance_insert_request)
 wait_for_extended_operation(operation, "instance creation")
 return instance_client.get (project=project_id, zone=zone, instance=instance_name)

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_URL

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/1234567890.

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/1234567890

{ "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.

Console

  1. In the Google Cloud console, go to the Create an instance page.

    Go to Create an instance

  2. In the Create VM from ... menu, select Instance templates.

  3. In the Create VM from template window that appears, select a template, and then click Customize.

  4. Optional: Specify other configuration options. For more information, see Configuration options during instance creation.

  5. To create and start the instance, click Create.

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 1234567890 --machine-type e2-standard-2 \
 --image-family debian-9 --image-project debian-cloud \
 --metadata bread=butter --disk=boot=no,name=my-override-disk

Go 

import(
"context"
"fmt"
"io"
compute"cloud.google.com/go/compute/apiv1"
computepb"cloud.google.com/go/compute/apiv1/computepb"
"google.golang.org/protobuf/proto"
)
// createInstanceFromTemplate creates a Compute Engine VM instance from an instance template, but overrides the disk and machine type options in the template.
funccreateInstanceFromTemplateWithOverrides(wio.Writer,projectID,zone,instanceName,instanceTemplateName,machineType,newDiskSourceImagestring)error{
// projectID := "your_project_id"
// zone := "europe-central2-b"
// instanceName := "your_instance_name"
// instanceTemplateName := "your_instance_template_name"
// machineType := "n1-standard-2"
// newDiskSourceImage := "projects/debian-cloud/global/images/family/debian-12"
ctx:=context.Background()
instancesClient,err:=compute.NewInstancesRESTClient (ctx)
iferr!=nil{
returnfmt.Errorf("NewInstancesRESTClient: %w",err)
}
deferinstancesClient.Close()
intanceTemplatesClient,err:=compute.NewInstanceTemplatesRESTClient (ctx)
iferr!=nil{
returnfmt.Errorf("NewInstanceTemplatesRESTClient: %w",err)
}
deferintanceTemplatesClient.Close()
// Retrieve an instance template by name.
reqGetTemplate:=&computepb.GetInstanceTemplateRequest{
Project:projectID,
InstanceTemplate:instanceTemplateName,
}
instanceTemplate,err:=intanceTemplatesClient.Get(ctx,reqGetTemplate)
iferr!=nil{
returnfmt.Errorf("unable to get intance template: %w",err)
}
for_,disk:=rangeinstanceTemplate.Properties.Disks{
diskType:=disk.InitializeParams.GetDiskType()
ifdiskType!=""{
disk.InitializeParams.DiskType=proto.String(fmt.Sprintf(`zones/%s/diskTypes/%s`,zone,diskType))
}
}
reqInsertInstance:=&computepb.InsertInstanceRequest{
Project:projectID,
Zone:zone,
InstanceResource:&computepb.Instance{
Name:proto.String(instanceName),
MachineType:proto.String(fmt.Sprintf(`zones/%s/machineTypes/%s`,zone,machineType)),
Disks:append(
// If you override a repeated field, all repeated values
// for that property are replaced with the
// corresponding values provided in the request.
// When adding a new disk to existing disks,
// insert all existing disks as well.
instanceTemplate.Properties.Disks,
&computepb.AttachedDisk{
InitializeParams:&computepb.AttachedDiskInitializeParams{
DiskSizeGb:proto.Int64(10),
SourceImage:&newDiskSourceImage,
},
AutoDelete:proto.Bool(true),
Boot:proto.Bool(false),
Type:proto.String(computepb.AttachedDisk_PERSISTENT .String()),
},
),
},
SourceInstanceTemplate:instanceTemplate.SelfLink,
}
op,err:=instancesClient.Insert(ctx,reqInsertInstance)
iferr!=nil{
returnfmt.Errorf("unable to create instance: %w",err)
}
iferr=op.Wait(ctx);err!=nil{
returnfmt.Errorf("unable to wait for the operation: %w",err)
}
fmt.Fprintf(w,"Instance created\n")
returnnil
}

Java 


importcom.google.cloud.compute.v1.AttachedDisk ;
importcom.google.cloud.compute.v1.AttachedDiskInitializeParams ;
importcom.google.cloud.compute.v1.InsertInstanceRequest ;
importcom.google.cloud.compute.v1.Instance ;
importcom.google.cloud.compute.v1.InstanceTemplate ;
importcom.google.cloud.compute.v1.InstanceTemplatesClient ;
importcom.google.cloud.compute.v1.InstancesClient ;
importcom.google.cloud.compute.v1.Operation ;
importjava.io.IOException;
importjava.util.ArrayList;
importjava.util.List;
importjava.util.concurrent.ExecutionException;
importjava.util.concurrent.TimeUnit;
importjava.util.concurrent.TimeoutException;
publicclass CreateInstanceFromTemplateWithOverrides{
publicstaticvoidmain(String[]args)
throwsIOException,ExecutionException,InterruptedException,TimeoutException{
/* TODO(developer): Replace these variables before running the sample.
 * projectId - ID or number of the project you want to use.
 * zone - Name of the zone you want to check, for example: us-west3-b
 * instanceName - Name of the new instance.
 * instanceTemplateName - Name of the instance template to use when creating the new instance.
 * machineType - Machine type you want to set in following format:
 * "zones/{zone}/machineTypes/{type_name}". For example:
 * "zones/europe-west3-c/machineTypes/f1-micro"
 * You can find the list of available machine types using:
 * https://cloud.google.com/sdk/gcloud/reference/compute/machine-types/list
 * newDiskSourceImage - Path the the disk image you want to use for your new
 * disk. This can be one of the public images
 * (like "projects/debian-cloud/global/images/family/debian-11")
 * or a private image you have access to.
 * You can check the list of available public images using the doc:
 * http://cloud.google.com/compute/docs/images
 */
StringprojectId="your-project-id";
Stringzone="zone-name";
StringinstanceName="instance-name";
StringinstanceTemplateName="instance-template-name";
createInstanceFromTemplateWithOverrides(projectId,zone,instanceName,instanceTemplateName);
}
// Creates a Compute Engine VM instance from an instance template,
// but overrides the disk and machine type options in the template.
publicstaticvoidcreateInstanceFromTemplateWithOverrides(StringprojectId,Stringzone,
StringinstanceName,StringinstanceTemplateName)
throwsIOException,ExecutionException,InterruptedException,TimeoutException{
try(InstancesClient instancesClient=InstancesClient .create();
InstanceTemplatesClient instanceTemplatesClient=InstanceTemplatesClient .create()){
StringmachineType="n1-standard-1";
StringnewDiskSourceImage="projects/debian-cloud/global/images/family/debian-11";
// Retrieve an instance template.
InstanceTemplate instanceTemplate=instanceTemplatesClient
.get(projectId,instanceTemplateName);
// Adjust diskType field of the instance template to use the URL formatting 
// required by instances.insert.diskType
// For instance template, there is only a name, not URL.
List<AttachedDisk>reformattedAttachedDisks=newArrayList<>();
for(AttachedDisk disk:instanceTemplate.getProperties ().getDisksList()){
disk=AttachedDisk .newBuilder(disk)
.setInitializeParams (AttachedDiskInitializeParams
.newBuilder(disk.getInitializeParams())
.setDiskType(
String.format(
"zones/%s/diskTypes/%s",zone,disk.getInitializeParams().getDiskType()))
.build())
.build();
reformattedAttachedDisks.add(disk);
}
AttachedDisk newdisk=AttachedDisk .newBuilder()
.setInitializeParams (AttachedDiskInitializeParams .newBuilder()
.setDiskSizeGb(10)
.setSourceImage(newDiskSourceImage).build())
.setAutoDelete(true)
.setBoot(false)
.setType(AttachedDisk .Type.PERSISTENT.toString()).build();
Instance instance=Instance .newBuilder()
.setName(instanceName)
.setMachineType(String.format("zones/%s/machineTypes/%s",zone,machineType))
// If you override a repeated field, all repeated values
// for that property are replaced with the
// corresponding values provided in the request.
// When adding a new disk to existing disks,
// insert all existing disks as well.
.addAllDisks(reformattedAttachedDisks)
.addDisks(newdisk)
.build();
InsertInstanceRequest insertInstanceRequest=InsertInstanceRequest .newBuilder()
.setProject(projectId)
.setZone(zone)
.setInstanceResource(instance)
.setSourceInstanceTemplate(instanceTemplate.getSelfLink ()).build();
Operation response=instancesClient.insertAsync(insertInstanceRequest)
.get(3,TimeUnit.MINUTES);
if(response.hasError ()){
System.out.println("Instance creation from template with overrides failed ! ! "+response);
return;
}
System.out
.printf("Instance creation from template with overrides: Operation Status %s: %s ",
instanceName,response.getStatus ());
}
}
}

Node.js 

/**
 * TODO(developer): Uncomment and replace these variables before running the sample.
 */
// const projectId = 'YOUR_PROJECT_ID';
// const zone = 'europe-central2-b';
// const instanceName = 'YOUR_INSTANCE_NAME';
// const instanceTemplateName = 'YOUR_INSTANCE_TEMPLATE_NAME';
// const machineType = 'n1-standard-1';
// const newDiskSourceImage = 'projects/debian-cloud/global/images/family/debian-11';
constcompute=require('@google-cloud/compute');
// Creates a new instance in the specified project and zone using a selected template,
// but overrides the disk and machine type options in the template.
asyncfunctioncreateInstanceFromTemplateWithOverrides(){
constinstancesClient=newcompute.InstancesClient ();
constinstanceTemplatesClient=newcompute.InstanceTemplatesClient ();
console.log(
`Creating the ${instanceName} instance in ${zone} from template ${instanceTemplateName}...`
);
// Retrieve an instance template by name.
const[instanceTemplate]=awaitinstanceTemplatesClient.get({
project:projectId,
instanceTemplate:instanceTemplateName,
});
// Adjust diskType field of the instance template to use the URL formatting required by instances.insert.diskType
// For instance template, there is only a name, not URL.
for(constdiskofinstanceTemplate.properties.disks){
if(disk.initializeParams.diskType){
disk.initializeParams.diskType=`zones/${zone}/diskTypes/${disk.initializeParams.diskType}`;
}
}
const[response]=awaitinstancesClient.insert({
project:projectId,
zone,
instanceResource:{
name:instanceName,
machineType:`zones/${zone}/machineTypes/${machineType}`,
disks:[
// If you override a repeated field, all repeated values
// for that property are replaced with the
// corresponding values provided in the request.
// When adding a new disk to existing disks,
// insert all existing disks as well.
...instanceTemplate.properties.disks,
{
initializeParams:{
diskSizeGb:'10',
sourceImage:newDiskSourceImage,
},
autoDelete:true,
boot:false,
type:'PERSISTENT',
},
],
},
sourceInstanceTemplate:instanceTemplate.selfLink,
});
letoperation=response.latestResponse;
constoperationsClient=newcompute.ZoneOperationsClient ();
// Wait for the create operation to complete.
while(operation.status!=='DONE'){
[operation]=awaitoperationsClient.wait({
operation:operation.name,
project:projectId,
zone:operation.zone.split('/').pop(),
});
}
console.log('Instance created.');
}
createInstanceFromTemplateWithOverrides();

Python 

from__future__import annotations
importsys
fromtypingimport Any
fromgoogle.api_core.extended_operationimport ExtendedOperation
fromgoogle.cloudimport compute_v1
defwait_for_extended_operation(
 operation: ExtendedOperation, verbose_name: str = "operation", timeout: int = 300
) -> Any:
"""
 Waits for the extended (long-running) operation to complete.
 If the operation is successful, it will return its result.
 If the operation ends with an error, an exception will be raised.
 If there were any warnings during the execution of the operation
 they will be printed to sys.stderr.
 Args:
 operation: a long-running operation you want to wait on.
 verbose_name: (optional) a more verbose name of the operation,
 used only during error and warning reporting.
 timeout: how long (in seconds) to wait for operation to finish.
 If None, wait indefinitely.
 Returns:
 Whatever the operation.result() returns.
 Raises:
 This method will raise the exception received from `operation.exception()`
 or RuntimeError if there is no exception set, but there is an `error_code`
 set for the `operation`.
 In case of an operation taking longer than `timeout` seconds to complete,
 a `concurrent.futures.TimeoutError` will be raised.
 """
 result = operation.result(timeout=timeout)
 if operation.error_code:
 print(
 f"Error during {verbose_name}: [Code: {operation.error_code}]: {operation.error_message}",
 file=sys.stderr,
 flush=True,
 )
 print(f"Operation ID: {operation.name}", file=sys.stderr, flush=True)
 raise operation.exception() or RuntimeError(operation.error_message)
 if operation.warnings:
 print(f"Warnings during {verbose_name}:\n", file=sys.stderr, flush=True)
 for warning in operation.warnings:
 print(f" - {warning.code}: {warning.message}", file=sys.stderr, flush=True)
 return result
defcreate_instance_from_template_with_overrides(
 project_id: str,
 zone: str,
 instance_name: str,
 instance_template_name: str,
 machine_type: str,
 new_disk_source_image: str,
) -> compute_v1.Instance:
"""
 Creates a Compute Engine VM instance from an instance template, changing the machine type and
 adding a new disk created from a source image.
 Args:
 project_id: ID or number of the project you want to use.
 zone: Name of the zone you want to check, for example: us-west3-b
 instance_name: Name of the new instance.
 instance_template_name: Name of the instance template used for creating the new instance.
 machine_type: Machine type you want to set in following format:
 "zones/{zone}/machineTypes/{type_name}". For example:
 - "zones/europe-west3-c/machineTypes/f1-micro"
 - You can find the list of available machine types using:
 https://cloud.google.com/sdk/gcloud/reference/compute/machine-types/list
 new_disk_source_image: Path the the disk image you want to use for your new
 disk. This can be one of the public images
 (like "projects/debian-cloud/global/images/family/debian-12")
 or a private image you have access to.
 For a list of available public images, see the documentation:
 http://cloud.google.com/compute/docs/images
 Returns:
 Instance object.
 """
 instance_client = compute_v1 .InstancesClient ()
 instance_template_client = compute_v1 .InstanceTemplatesClient ()
 # Retrieve an instance template by name.
 instance_template = instance_template_client.get (
 project=project_id, instance_template=instance_template_name
 )
 # Adjust diskType field of the instance template to use the URL formatting required by instances.insert.diskType
 # For instance template, there is only a name, not URL.
 for disk in instance_template.properties.disks :
 if disk.initialize_params.disk_type:
 disk.initialize_params.disk_type = (
 f"zones/{zone}/diskTypes/{disk.initialize_params.disk_type}"
 )
 instance = compute_v1 .Instance ()
 instance.name = instance_name
 instance.machine_type = machine_type
 instance.disks = list(instance_template.properties.disks )
 new_disk = compute_v1 .AttachedDisk ()
 new_disk.initialize_params.disk_size_gb = 50
 new_disk.initialize_params.source_image = new_disk_source_image
 new_disk.auto_delete = True
 new_disk.boot = False
 new_disk.type_ = "PERSISTENT"
 instance.disks .append(new_disk)
 instance_insert_request = compute_v1 .InsertInstanceRequest ()
 instance_insert_request.project = project_id
 instance_insert_request.zone = zone
 instance_insert_request.instance_resource = instance
 instance_insert_request.source_instance_template = instance_template.self_link
 operation = instance_client.insert (instance_insert_request)
 wait_for_extended_operation(operation, "instance creation")
 return instance_client.get (project=project_id, zone=zone, instance=instance_name)

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 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/1234567890

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

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025年10月30日 UTC.