# 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-vmtype:compute.v1.instanceproperties:zone:us-central1-fmachineType:https://www.googleapis.com/compute/v1/projects/MY_PROJECT/zones/us-central1-f/machineTypes/f1-microdisks:-deviceName:boottype:PERSISTENTboot:trueautoDelete:trueinitializeParams:sourceImage:https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/family/debian-11networkInterfaces:# The resource's "network value" has been replaced with a# reference to the new network's "selfLink" property. The network # resource has been added to the end of this file.-network:$(ref.a-new-network.selfLink)accessConfigs:-name:External NATtype:ONE_TO_ONE_NAT-name:the-second-vmtype:compute.v1.instanceproperties:zone:us-central1-fmachineType:https://www.googleapis.com/compute/v1/projects/MY_PROJECT/zones/us-central1-f/machineTypes/g1-smalldisks:-deviceName:boottype:PERSISTENTboot:trueautoDelete:trueinitializeParams:sourceImage:https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/family/debian-11networkInterfaces:# As in the resource above, the "network" value has been replaced with # the new network's "selfLink" property. -network:$(ref.a-new-network.selfLink)accessConfigs:-name:External NATtype:ONE_TO_ONE_NAT# The following network is a new resource added to the "two-vms.yaml" file.-name:a-new-networktype:compute.v1.networkproperties:routingConfig:routingMode:REGIONALautoCreateSubnetworks:true
[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["很难理解","hardToUnderstand","thumb-down"],["信息或示例代码不正确","incorrectInformationOrSampleCode","thumb-down"],["没有我需要的信息/示例","missingTheInformationSamplesINeed","thumb-down"],["翻译问题","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC)：2025-09-03。"],[[["\u003cp\u003eReferences allow you to use properties of other resources in your configurations or templates instead of hardcoding values, improving readability and maintainability.\u003c/p\u003e\n"],["\u003cp\u003eUsing references lets you access properties that are determined during resource creation, such as a virtual machine's IP address, which is not known beforehand.\u003c/p\u003e\n"],["\u003cp\u003eReferences create dependencies between resources, meaning Deployment Manager will automatically create resources in the correct order to resolve the references.\u003c/p\u003e\n"],["\u003cp\u003eReferences are declared using the format \u003ccode\u003e$(ref.RESOURCE_NAME.PROPERTY)\u003c/code\u003e in configurations and templates, and can be combined with template properties and environment variables.\u003c/p\u003e\n"],["\u003cp\u003eYou cannot use references within the name field of a resource, and the processed value of a reference cannot be used in your Python or Jinja code, only after the deployment creation or update.\u003c/p\u003e\n"]]],[],null,["# Using references\n\nWhen you define the properties for your configuration or templates, you can\nuse **references** to the properties of other resources instead of directly\nproviding values. For example, if you want to create an instance group manager\nthat uses an instance template from the same deployment, instead of explicitly\ntyping the full link for the instance template, you can use a reference with the\nsyntax `$(ref.instance-template.selfLink)`.\n\nWith references, you can:\n\n- Access properties that are not defined until the resource is created. For\n example, when you define a virtual machine in your configuration, you do not\n yet know its IP address. However, you can still use a reference to the IP\n address. When you deploy your configuration, the VM is created first, and\n Deployment Manager gets the external IP address when it is available.\n\n- Make your configurations or templates easier to read and troubleshoot.\n For example, if you need to configure multiple forwarding rules, you must\n also specify a network to use. Instead of providing a link to the network\n for each forwarding rule, you can create a reference to the network's\n `selfLink` property using the following syntax:\n\n $(ref.network-name.selfLink)\n\n If you need to troubleshoot your configuration, the reference makes it easier\n to tell which network is being used in the forwarding rule.\n\nWhen you create a reference to a resource, you also create a dependency between\nresources. For example, consider the following snippet, where `sandbox-vm` uses\na reference to `network-a`: \n\n resources:\n - name: sandbox-vm\n type: compute.v1.instance\n properties:\n network: $(ref.network-a.selfLink)\n ...\n ...\n - name: network-a\n type: compute.v1.network\n properties:\n ...\n\nWhen you deploy this configuration, Deployment Manager creates `network-a`\nbefore `sandbox-vm`, so that the reference can be resolved. If any references\ndo not resolve successfully, your deployment fails.\n\nYou can use references in both configurations and templates.\n| **Note:** To avoid errors, don't use a reference within the name field of a resource.\n\nBefore you begin\n----------------\n\n- If you want to use the command-line examples in this guide, install the [\\`gcloud\\` command-line tool](/sdk).\n- If you want to use the API examples in this guide, set up [API access](/deployment-manager/docs/reference/latest).\n- Be familiar with [creating a configuration](/deployment-manager/docs/configuration/create-basic-configuration).\n- Be familiar with [creating a basic template](/deployment-manager/docs/configuration/templates/create-basic-template).\n\nMaking references in configuration files\n----------------------------------------\n\nDeclare references in your configuration using the following format: \n\n $(ref.RESOURCE_NAME.PROPERTY)\n\nThe following example creates a network, and then creates two\ninstances that use references to the newly created network. In this example,\nthe reference is: \n\n $(ref.a-new-network.selfLink)\n\n # Copyright 2016 Google Inc. All rights reserved.\n #\n # Licensed under the Apache License, Version 2.0 (the \"License\");\n # you may not use this file except in compliance with the License.\n # You may obtain a copy of the License at\n #\n # http://www.apache.org/licenses/LICENSE-2.0\n #\n # Unless required by applicable law or agreed to in writing, software\n # distributed under the License is distributed on an \"AS IS\" BASIS,\n # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n # See the License for the specific language governing permissions and\n # limitations under the License.\n\n resources:\n - name: the-first-vm\n type: compute.v1.instance\n properties:\n zone: us-central1-f\n machineType: https://www.googleapis.com/compute/v1/projects/MY_PROJECT/zones/us-central1-f/machineTypes/f1-micro\n disks:\n - deviceName: boot\n type: PERSISTENT\n boot: true\n autoDelete: true\n initializeParams:\n sourceImage: https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/family/debian-11\n networkInterfaces:\n # The resource's \"network value\" has been replaced with a\n # reference to the new network's \"selfLink\" property. The network \n # resource has been added to the end of this file.\n - network: $(ref.a-new-network.selfLink)\n accessConfigs:\n - name: External NAT\n type: ONE_TO_ONE_NAT\n - name: the-second-vm\n type: compute.v1.instance\n properties:\n zone: us-central1-f\n machineType: https://www.googleapis.com/compute/v1/projects/MY_PROJECT/zones/us-central1-f/machineTypes/g1-small\n disks:\n - deviceName: boot\n type: PERSISTENT\n boot: true\n autoDelete: true\n initializeParams:\n sourceImage: https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/family/debian-11\n networkInterfaces:\n # As in the resource above, the \"network\" value has been replaced with \n # the new network's \"selfLink\" property. \n - network: $(ref.a-new-network.selfLink)\n accessConfigs:\n - name: External NAT\n type: ONE_TO_ONE_NAT\n # The following network is a new resource added to the \"two-vms.yaml\" file.\n - name: a-new-network\n type: compute.v1.network\n properties:\n routingConfig:\n routingMode: REGIONAL\n autoCreateSubnetworks: true\n\nWhen you deploy this configuration, the network is created before the two\ninstances, and the reference resolves to the `selfLink` of the network resource.\n\nMaking references in templates\n------------------------------\n\nIn template files, the entire reference must be preceded by a `$` and then\ncontained within a set of parentheses: \n\n $(ref.RESOURCE_NAME.PROPERTY)\n\nYou can combine references with other features like template properties\nand environment variables. To make sure that Deployment Manager parses the\nreference correctly, it is important to remember to keep your entire reference\nstring within the parentheses.\n| **Note:** Your reference declaration is evaluated after your template is processed and the [expanded configuration is created](/deployment-manager/docs/deployments/viewing-manifest#expanded_configuration), so you can't use the processed value of a reference in your Python or Jinja code. If you need to get the value of a reference after you create or update a deployment, consider [exposing the value as an output](/deployment-manager/docs/configuration/expose-information-outputs) and accessing the value after the create or update operation.\n\nHere are some examples of declaring references in your templates: \n\n### Jinja\n\n- Reference that includes an environment variable\n\n network: $(ref.{{ env[\"deployment\"] }}-network.selfLink)\n\n- Reference to a value in an array\n\n subnetwork: $(ref.{{ env[\"deployment\"] }}-vm.networkInterfaces[2].subnetwork)\n\n- Reference that includes a [template property](/deployment-manager/docs/configuration/templates/define-template-properties)\n\n network: $(ref.{{ properties[\"network\"] }}.selfLink)\n\n- Reference using a Jinja parameter\n\n network: $(ref.{{ NETWORK_NAME }}.selfLink)\n\n- Reference in [outputs](/deployment-manager/docs/configuration/expose-information-outputs)\n\n outputs:\n - name: UrlToService\n value: http://$(ref.{{ env[\"deployment\"] }}-network.networkInterfaces[0].accessConfigs[0].natIp):8080/\n\n### Python\n\n- Reference that includes an environment variable\n\n 'network': '$(ref.' + context.env['deployment'] + '-network.selfLink)'\n\n- Reference to a value in an array\n\n 'subnetwork': '$(ref.' + context.env['deployment'] + '-vm.networkInterfaces[2].subnetwork)'\n\n- Reference that includes a [template property](/deployment-manager/docs/configuration/templates/define-template-properties)\n\n 'network': '$(ref.' + context.properties['network'] + '.selfLink)'\n\n- Reference using a Python parameter\n\n 'value': '$(ref.' + base_name + '.networkInterfaces[0].networkIP)'\n\n- Reference in [outputs](/deployment-manager/docs/configuration/expose-information-outputs)\n\n outputs = [{'name': 'UrlToService',\n 'value': '$(ref.' + context.env['deployment'] + '-network.networkInterfaces[0].accessConfigs[0].natIP):8080'}]\n\nWhat's next\n-----------\n\n- [Preview your configuration](/deployment-manager/docs/configuration/preview-configuration-file) before you commit to deploying it.\n- [Create a deployment](/deployment-manager/docs/deployments).\n- Learn more about [templates](/deployment-manager/docs/configuration/templates/create-basic-template)."]]
