Deterministic instance templates

This page describes when and why to create deterministic instancetemplates. Deterministic instance templates make explicitly clearthe type of third-party services or apps to install onyour instances when the instance template is deployed. By creating deterministicinstance templates, you minimize ambiguity and unexpected behavior from yourinstance templates.

Why create deterministic instance templates

In general, we recommend that the properties of your instance template be asexplicit and deterministic as possible. If you employ startupscripts in your instance templates that install or use third-party services,make sure that these scripts provide explicit information, such as theversion of app to install. Compute Engine can only rely oninformation defined in the template and has no control over referencedthird-party services. If your template is too vague, your instance templatemight behave unexpectedly.

For example, consider the following command to create an instance template witha startup script that installs apache2 and uses a file that is hosted on anexternal server:

Note: This is just an example snippet pointing to a non-existent server at108.59.87.185. Copying this example directly fails when the script attemptsto connect to 108.59.87.185. Instead, replace the last line with your own serverinformation, if applicable.
gcloudcomputeinstance-templatescreateexample-template-with-startup\--image-familydebian-9\--image-projectdebian-cloud\--metadatastartup-script='#!/bin/bashsudoaptinstall-yapache2scpmyuser@108.59.87.185:index.php/var/www/'

There are two potential issues with this startup script:

  • The script does not explicitly define which version of apache2 to install,and relies on the current version available in theapt repository.
  • The script relies on a file hosted on a third-party that isn't versioned andcould have been changed since the last time the instance template was used.

If you use anautoscaler, a non-deterministicinstance template can cause your autoscaler to add new instances to amanaged instance group with a differentconfiguration, such as a different version of apache2.

Similarly, if you applied this template to a managed instance group,updatedthe group to a different templateservice, and then decided to roll back to the previous template, you might endup with instances that use a different version of apache2 or index.php filethan before the update because your instances would always fetch the most recentversion at startup.

Avoiding ambiguous or unexpected instance template behavior

To avoid unexpected template behavior, use the following methods:

  • Usecontainer-optimized images orDocker, with Docker tags. For example, we recommend that you assign new tagsfor every new build of your Docker image, and use these tags in your instancetemplates instead of the default latest tag. For a container-optimized image,you can explicitly reference a particular build of your image in your manifestfile. The example below uses Docker image "myimage" at version tagged with"version_2_1_3":

    version:v1beta2containers:-name:simple-echoimage:myimage:version_2_1_3[restofyourmanifestfile]

  • Create a custom imageto use as the image for the template. This is preferable to startup scriptsbecause it guarantees that every instance is the same. Startup scripts mighthave different results after distribution package updates. Use startup scriptsin your instance templates for prototyping and rapid development, and usecustom images when you are ready to deploy production-quality services.

  • If you do use startup scripts, consider updating your scripts to bedeterministic. For example, create a new version of the previous template, andspecify a deterministic startup script as follows:

    gcloudcomputeinstance-templatescreateexample-template-with-startup-2-1-3\--image-familydebian-9\--image-projectdebian-cloud\--metadatastartup-script='#!/bin/bashsudoaptinstall-yapache2=2.2.20-1ubuntu1scpmyuser@108.59.87.185:version_2_1_3/index.php/var/www/'

    where "version_2_1_3" is a subdirectory containing PHP scripts for theversion 2.1.3 of your service.

  • When specifying an instance template—for example when you are creating orupdating a managed instance group—Google recommends that you specify thetemplate's ID value instead of its name value. Although both values are valid,the ID is unique, which means that the instance template that you specify isthe one that is used when creating VMs from that instance template. Using anID instead of a name helps to mitigate potential security vulnerabilities—forexample,TOCTOUvulnerabilities, where an attacker can delete a template and recreate it withthe same name prior to its use.

    To view the ID of an instance template, seeGet information about an instance template.

What's next

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

Last updated 2025-12-15 UTC.