Using References

When you define the properties for your configuration or template files, you can use references to other properties instead of directly providing property values. For example, for Compute Engine, when you define a new virtual machine instance, you can also reserve a static external IP address to assign to the instance in the same configuration. The value of the address is not available until the Address resource is created. In this case, you can create a reference the Address resource's natIP field so that Deployment Manager can get the external IP address when it is available.

References are particularly useful for values that are not defined until a resource is created, such as a resource's selfLink, IP address, or system-generated ID. In these cases, you can point to these properties using a reference.

Creating a reference to another property also creates a dependency between these two properties; the Deployment Manager service resolves these dependencies in order. For example, if Resource A references Resource B, then Deployment Manager will know to create Resource B first, before creating Resource A. If any references do not resolve successfully, your template will not work and Deployment Manager will reject your deployment request.

You can use references in both configurations and templates.

Before you begin

Making references in configuration files

Declare references in your configuration using the following format:

$(ref.RESOURCE_NAME.PROPERTY)

For example, the following example creates a Compute Engine network, and then creates two instances that reference the newly-created network. In this example, the reference is:

$(ref.my-network.selfLink)
# Copyright 2016 Google Inc. All rights reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

resources:
- name: the-first-vm
  type: compute.v1.instance
  properties:
    zone: us-central1-f
    machineType: https://www.googleapis.com/compute/v1/projects/[MY_PROJECT]/zones/us-central1-f/machineTypes/f1-micro
    disks:
    - deviceName: boot
      type: PERSISTENT
      boot: true
      autoDelete: true
      initializeParams:
        sourceImage: https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/family/debian-8
    networkInterfaces:
    - network: $(ref.a-new-network.selfLink)
      accessConfigs:
      - name: External NAT
        type: ONE_TO_ONE_NAT
- name: the-second-vm
  type: compute.v1.instance
  properties:
    zone: us-central1-f
    machineType: https://www.googleapis.com/compute/v1/projects/[MY_PROJECT]/zones/us-central1-f/machineTypes/g1-small
    disks:
    - deviceName: boot
      type: PERSISTENT
      boot: true
      autoDelete: true
      initializeParams:
        sourceImage: https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/family/debian-8
    networkInterfaces:
    - network: $(ref.a-new-network.selfLink)
      accessConfigs:
      - name: External NAT
        type: ONE_TO_ONE_NAT
- name: a-new-network
  type: compute.v1.network
  properties:
    IPv4Range: 10.0.0.1/16

When you deploy this configuration, the references will resolve to the correct values. In this case, the reference resolves to the selfLink of the network resource.

Making references in templates

In template files, the entire reference must be preceded by a $ and then contained within a set of parenthesis:

$(ref.RESOURCE_NAME.PROPERTY)

You can combine references with other features like template properties and environment variables. To make sure Deployment Manager parses the reference correctly, it is important to remember to keep your entire reference string within the parentheses. Deployment Manager will resolve all properties and variables first and then resolve all references before the template gets processed.

Here are some examples of declaring references.

Jinja examples

  • Reference an environment variable

    network: $(ref.{{ env["deployment"] }}-network.selfLink)

  • Reference using a template property

    network: $(ref.{{ properties["network"] }}.selfLink)

  • Reference using a Jinja parameter

    network: $(ref.{{ NETWORK_NAME }}.selfLink)

  • Reference as part of a string

    outputs:
    - name: UrlToService
      value: http://$(ref.{{ env["deployment"] }}-network.networkInterfaces[0].accessConfigs[0].natIp):8080/

Python examples

  • Reference an environment variable

    'network': '$(ref.' + context.env['deployment'] + '.selfLink)',

  • Reference using a template property

    'network': '$(ref.' + context.properties['network'] + '.selfLink)',

  • Reference using a Python parameter

    'value': '$(ref.' + base_name + '.networkInterfaces[0].networkIP)'

  • Reference as part of a string

    outputs = [{'name': 'instanceTemplateSelfLink',
                'value': '$(ref.' + instance_template['name'] + '.selfLink)'}]

What's next

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

Send feedback about...

Cloud Deployment Manager Documentation