Syntax Reference

This page describes the syntax used by Deployment Manager. Use this guide as a reference for what syntax to use in your configurations and templates.

Syntax for configurations and templates

Basic syntax

• resources - A set of resources to create.
  • name - The name for this instantiation of this resource.
  • type - The resource type. This can be a base type like compute.v1.instance , a type provider such as gcp-types/compute-v1:addresses , or an imported template. See the list of supported type providers .
  • properties - The properties of this resource. For an introduction, see Template properties .
  • metadata - Extra configuration for this resource. See a list of fields in Metadata .

Example

  resources 
 : 
 - 
  
 name 
 : 
  
 vm 
 - 
 instance 
  
 type 
 : 
  
 compute 
 . 
 v1 
 . 
 instance 
  
 properties 
 : 
  
 machineType 
 : 
  
 zones 
 / 
 us 
 - 
 central1 
 - 
 a 
 / 
 machineTypes 
 / 
 n1 
 - 
 standard 
 - 
 1 
  
 ... 
 

Access Control

If you want to set IAM policies on your resources, you use an accessControl section:

1. Add the accessControl section to the top-level configuration for each resource for which you want to apply access control policies.

2. Specify the desired gcpIamPolicy for the resource. Each IAM policy can contain a list of bindings. Each binding binds a list of principals to a role.

For detailed information on controlling access to resources, see Setting access control in a configuration .

For example, the following accessControl section adds bindings that grant these roles to users:

  resources 
 : 
 - 
 name: 
  
 a 
 - 
 new 
 - 
 pubsub 
 - 
 topic 
  
 type 
 : 
  
 pubsub 
 . 
 v1 
 . 
 topic 
  
 properties 
 : 
  
 ... 
  
 accessControl 
 : 
  
 gcpIamPolicy 
 : 
  
 bindings 
 : 
  
 - 
  
 role 
 : 
  
 roles 
 / 
 pubsub 
 . 
 editor 
  
 members 
 : 
  
 - 
  
 "user:alice@example.com" 
  
 - 
  
 role 
 : 
  
 roles 
 / 
 pubsub 
 . 
 publisher 
  
 members 
 : 
  
 - 
  
 "user:jane@example.com" 
  
 - 
  
 "serviceAccount:my-other-app@appspot.gserviceaccount.com" 
 

References

For information on when to use references, and more examples, learn more about creating references .

You can use referencesto the properties of other resources instead of directly providing values. For example, if you want to create an instance group manager that uses an instance template from the same deployment, instead of explicitly typing the full link for the instance template, you can use a reference with the syntax $(ref.instance-template.selfLink) .

To see which properties you can create references to, see the get method for the resource's API. For example, for a list of all the properties for a VM instance, see the response for the instances.get() method .

You declare references using a similar syntax to the JSONPath 'dot' notation . Use the following syntax to declare a reference:

 $(ref. RESOURCE_NAME 
. PATH_TO_PROPERTY 
) 

For properties that are lists, such as the network interfaces for a Compute Engine instances, use the following syntax:

  $ 
 ( 
 ref 
 . 
  RESOURCE_NAME 
 
 . 
  LIST_PROPERTY 
 
 [ 
  index 
 
 ] 
 . 
  ITEM 
 
 ) 
 

Examples

 $(ref.exampleInstance.networkInterfaces[0].natIp)
$(ref.exampleInstance.serviceAccounts[0].email) 

Deployment-specific environment variables

When you create a deployment, Deployment Manager creates environment variables that contain pieces of information about your deployment, such as the current project name, the deployment's name, and so on.

For a full list of available environment variables, see Environment variables .

To use an environment variable:

{{ env["deployment"] }} # Jinja

context.env["deployment"] # Python

Example

- type: compute.v1.instance
  name: vm-{{ env["deployment"] }}

Template properties

A template property is an arbitrary property that you create. Instead of hard-coding a value, you could declare a template property and set the value of the property in the top-level configuration, as opposed to statically providing the property and value directly in the template. To create a template property, use the syntax:

{{ properties["property-name"] }} # Jinja

context.properties["property-name"] # Python

Then in your top-level configuration or parent template, set the value of the property:

  imports 
 : 
 - 
  
 path 
 : 
  
 vm_template 
 . 
 jinja 
 resources 
 : 
 - 
  
 name 
 : 
  
 my 
 - 
 vm 
  
 type 
 : 
  
 vm_template 
 . 
 jinja 
  
 properties 
 : 
  
 property 
 - 
 name 
 : 
  
 example 
 - 
 value 
 

Learn more about Template Properties .

Outputs

In the outputs section, you can define arbitrary key/value pairs that expose certain information about your deployment. You provide the key and set the value either as a static string, a reference to a property, a template variable, or an environment variable.

• outputs - Declares a list of outputs that users can call in their resource properties.
  • name - Name of the output property.
  • value - Value of the output property.

Example

  resources 
 : 
 - 
  
 name 
 : 
  
 vm 
 - 
 instance 
  
 type 
 : 
  
 compute 
 . 
 v1 
 . 
 instance 
  
 ... 
 outputs 
 : 
 - 
  
 name 
 : 
  
 databaseIp 
  
 value 
 : 
  
 $ 
 ( 
 ref 
 . 
 vm 
 - 
 instance 
 . 
 networkInterfaces 
 [ 
 0 
 ]. 
 natIp 
 ) 
 - 
  
 name 
 : 
  
 databaseName 
  
 value 
 : 
  
 example 
 - 
 database 
 

Learn more about Outputs .

Metadata

The metadata section contains special metadata that you can apply on a per-resource basis. Deployment Manager has unique metadata that triggers certain features. For example, the dependsOn feature relies on a metadata entry.

Depends on

The dependsOn property creates explicit dependencies between your resources. For example, specifying that Resource A depends on Resource B ensures that Resource B is always created before Resource A.

  metadata 
 : 
  
 the 
  
 metadata 
  
 for 
  
 this 
  
 resource 
  
 dependsOn 
 : 
  
 Any 
  
 explicit 
  
 dependencies 
  
 to 
  
 another 
  
 resource 
 . 
 

Example

  resources 
 : 
 - 
  
 name 
 : 
  
 vm 
 - 
 instance 
  
 type 
 : 
  
 compute 
 . 
 v1 
 . 
 instance 
  
 properties 
 : 
  
 machineType 
 : 
  
 zones 
 / 
 us 
 - 
 central1 
 - 
 a 
 / 
 machineTypes 
 / 
 n1 
 - 
 standard 
 - 
 1 
  
 ... 
  
 metadata 
 : 
  
 dependsOn 
 : 
  
 - 
  
 persistent 
 - 
 disk 
 - 
 1 
  
 - 
  
 a 
 - 
 new 
 - 
 network 
 - 
 1 
 

Learn more about creating explicit dependencies .

Syntax for schemas

A schema is a way for you to control how your users can interact with your templates. The following syntax can be used in your schema file. Learn more about Schemas .

info

The info property contains meta information about the schema. This includes information such as a title, a version number, a description and so on.

At a minimum, provide a title and description in this property.

Example

  info 
 : 
  
 title 
 : 
  
 MongoDB 
  
 Template 
  
 author 
 : 
  
 Jane 
  
 description 
 : 
  
 Creates 
  
 a 
  
 MongoDB 
  
 cluster 
  
 version 
 : 
  
 1.0 
 

imports

The imports field contains a list of corresponding files that are required for templates that use this schema. When you upload a template with a schema that has a list of imports, Deployment Manager checks that all of the files in the imports property were uploaded along with the template.

Example

 imports: - 
path: helper.py
    name: mongodb_helper.py 

required

The required field contains a list of elements from the properties field that are required in the template that uses the schema. Any elements not specified in this required field are considered optional.

Example

  required 
 : 
  
 - 
  
 name 
 properties 
 : 
  
 name 
 : 
  
 type 
 : 
  
 string 
  
 description 
 : 
  
 Name 
  
 of 
  
 your 
  
 Mongo 
  
 Cluster 
  
 size 
 : 
  
 type 
 : 
  
 integer 
  
 default 
 : 
  
 2 
  
 description 
 : 
  
 Number 
  
 of 
  
 Mongo 
  
 Secondaries 
 

properties

The properties field contains the JSON schema rules for this document. Elements described in the properties field can be set by users of the template. You can use all supported JSON schema validations for these properties, such as:

• type (string, boolean, integer, number, ...)
• default
• minimum / exclusiveMinimum / maximum / exclusiveMaximum
• minLength / maxLength
• pattern
• not X / allOf X, Y / anyOf X, Y / oneOf X, Y

At a minimum, it is good practice to include a type and description of the field so users know what is an acceptable value for the property. For optional properties, it is also good practice to include a default value.

Read the JSON Schema Validation documentation for a list of validation keywords.

Example

  properties 
 : 
  
 name 
 : 
  
 type 
 : 
  
 string 
  
 description 
 : 
  
 Name 
  
 of 
  
 your 
  
 Mongo 
  
 Cluster 
  
 size 
 : 
  
 type 
 : 
  
 integer 
  
 default 
 : 
  
 2 
  
 description 
 : 
  
 Number 
  
 of 
  
 Mongo 
  
 Secondaries 
  
 minimum 
 : 
  
 1 
 

What's next

• Learn about References .
• Learn about Environment Variables .
• Learn about Template Properties .
• Learn about Outputs .
• Learn about Schemas .