Defining Template Properties

One of the advantages of using templates is the ability to create and define custom template properties. Template properties are arbitrary variables that you define in template files. Any configuration file or template file that uses the template in question can provide a value for the template property without changing the template directly. This lets you abstract the property so that you can change the property's value for each unique configuration without updating the underlying template.

For example, the following line specifies a template property in the machine type's URL:

machineType: zones/{{ properties["zone"] }}/machineTypes/n1-standard-1

In a configuration that uses this template, you can set the value of zone in the properties section of the template:

imports:
- path: vm_template.jinja

resources:
- name: my-vm
  type: vm_template.jinja
  properties:
    zone: us-central1-a

Deployment Manager will know to pass in the value of zone to the underlying template.

Before you begin

Creating a template property

To create a template property:

Jinja

In Jinja, define a property using the following syntax:

{{ properties["PROJECT_NAME"] }}

For example:

- name: vm-{{ env["deployment"] }}
  type: compute.v1.instance
  properties:
    zone: us-central1-a
    machineType: zones/{{ properties["zone"] }}/machineTypes/n1-standard-1
    disks:
    - deviceName: boot
      type: PERSISTENT
      boot: true
      autoDelete: true
      initializeParams:
        sourceImage: projects/debian-cloud/global/images/family/debian-11
    networkInterfaces:
    - network: global/networks/default

Python

In Python, define a property using the following syntax:

  context.properties["PROPERTY_NAME"]

For example:

resources.append({
    'name': 'vm-' + context.env['deployment'],
    'type': 'compute.v1.instance',
    'properties': {
        'zone': 'us-central1-a',
        'machineType': ''.join(['zones/', context.properties['zone'],
                                '/machineTypes/n1-standard-1']),
        'disks': [{
            'deviceName': 'boot',
            'type': 'PERSISTENT',
            'boot': True,
            'autoDelete': True,
            'initializeParams': {
                'sourceImage':
                    'projects/debian-cloud/global/images/family/debian-11'
            }
        }],
        'networkInterfaces': [{
            'network': 'global/networks/default'
        }]
    }

})

For the full Python example, see the Deployment Manager GitHub repository.

Setting values for template properties on the top-level config

On the top-level configuration, you can set values for template properties using the syntax:

imports:
- path: vm_template.jinja

resources:
- name: my-vm
  type: vm_template.jinja
  properties:
    zone: us-central1-a

You must set values for all template properties in the template. For example, if a template has template properties zone, image, network, you must define values for all of those properties in the top-level configuration.

If certain template properties have default values, consider using schemas to set these default values. A template property with a default value can be omitted from the top-level configuration if the default value is appropriate for the deployment.

Setting values for template properties on the command-line

Instead of supplying values for template properties in the parent file importing the template, Deployment Manager offers the ability to set these values directly in the Google Cloud CLI. You can skip creating the top-level YAML file; Deployment Manager will automatically generate a top-level configuration for your deployment based on the information in your request.

For example, assume you have the following template which has a template property called zone:

- name: vm-{{ env["deployment"] }}
  type: compute.v1.instance
  properties:
    zone: us-central1-a
    machineType: zones/{{ properties["zone"] }}/machineTypes/n1-standard-1
    disks:
    - deviceName: boot
      type: PERSISTENT
      boot: true
      autoDelete: true
      initializeParams:
        sourceImage: projects/debian-cloud/global/images/family/debian-11
    networkInterfaces:
    - network: global/networks/default

With the Google Cloud CLI, you can pass in this template file directly and provide the values for your template properties on the command-line. For example, the following request passes in the template and specifies the zone property directly on the command-line:

gcloud deployment-manager deployments create a-single-vm --template vm_template.jinja \
    --properties zone:us-central1-a

Keep in mind that:

  • All values are parsed as YAML values. For example, version: 3 is passed in as an integer. If you want to specify it as a string, put escaped single quotes around the value, version: \'3\'.

  • Boolean values are case insensitive, so TRUE, true, and True are treated the same.

  • You must pass in all required properties defined by the template. You cannot provide just a subset of the properties. If certain properties have default values, you can omit the property from the command-line.

To specify multiple properties, provide comma-separated key:value pairs. It does not matter in what order you specify the pairs. For example:

gcloud deployment-manager deployments create my-igm \
    --template vm_template.jinja \
    --properties zone:us-central1-a,machineType:n1-standard-1,image:debian-9

After running this command, Deployment Manager creates a deployment using the template you provided. You can confirm that the deployment has been created using the Google Cloud console or the gcloud CLI. For information on viewing a deployment, read Viewing a manifest.

What's next