Deterministic Instance Templates

This page describes when and why you should create deterministic instance templates. Deterministic instance templates make it explicitly clear in terms of the type of third-party services or applications that should be installed on your instances when the instance template is deployed. By creating deterministic instance templates, you minimize ambiguity and unexpected behavior from your instance templates.

Before you begin

Why you should create deterministic instance templates

In general, we recommend that the properties of your instance template are as explicit and deterministic as possible. If you employ startup scripts in your instance templates that install or use third-party services, make sure that these scripts provide explicit information, such as the version of application to install. Compute Engine can only rely on information defined in the template and has no control over referenced third-party services. If your template is too vague, your instance template might behave unexpectedly.

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

gcloud compute instance-templates create example-template-with-startup \
    --image-family debian-9 \
    --image-project debian-cloud \
    --metadata startup-script='#! /bin/bash
    sudo apt-get install -y apache2
    scp myuser@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 the apt-get repository.
  • The script relies on a file hosted on a third-party that isn’t versioned and could have been changed since the last time the instance template was used.

If you use an autoscaler, a non-deterministic instance template could cause your autoscaler to add new instances to a managed instance group with a different configuration, such as a different version of apache2.

Similarly, if you applied this template to a managed instance group, updated the group to a different template using the Instance Group Updater service, and then decided to rollback to the previous template, you might end up with instances using a different version of apache2 or index.php file than before the update, because your instances would always fetch the most recent version at startup.

Avoiding ambiguous or unexpected instance template behavior

To avoid unexpected template behavior, use one the following methods:

  • Use Container-optimized images or Docker, with Docker tags. For example, we recommend that you assign new tags for every new build of your Docker image, and use these tags in your instance templates, instead of the default latest tag. For a Container-optimized image, you can explicitly reference a particular build of your image in your manifest file. The example below uses Docker image “myimage” at version tagged with “version_2_1_3”:

    version: v1beta2
    containers:
      - name: simple-echo
        image: myimage:version_2_1_3
           [ rest of your manifest file ]
    
  • Create a custom image to use as the image for the template. This is preferable to startup scripts as it guarantees every instance will be the same, while startup scripts might have different result after distribution package updates. Use startup scripts in your instance templates for prototyping and rapid development, and use custom images when you are ready to deploy production-quality services.

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

    gcloud compute instance-templates create example-template-with-startup-2-1-3 \
        --image-family debian-9 \
        --image-project debian-cloud \
        --metadata startup-script='#! /bin/bash
        sudo apt-get install -y apache2=2.2.20-1ubuntu1
        scp myuser@108.59.87.185:version_2_1_3/index.php /var/www/'
    

    where “version_2_1_3” is a subdirectory containing PHP scripts for the version 2.1.3 of your service.

What's next

Was this page helpful? Let us know how we did:

Send feedback about...

Compute Engine Documentation