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 likecompute.v1.instance
, a type provider such asgcp-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:
Add the
accessControl
section to the top-level configuration for each resource for which you want to apply access control policies.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:
User | Role |
---|---|
alice@example.com |
roles/pubsub.editor |
|
roles/pubsub.publisher |
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 references to 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.