Como usar referências

Ao definir as propriedades de configuração ou modelos, é possível usar references às propriedades de outros recursos em vez de fornecer valores diretamente. Por exemplo, se você quiser criar um gerenciador de grupo de instâncias que use um modelo da mesma implantação, em vez de digitar explicitamente o link completo do modelo de instância, use uma referência com a sintaxe $(ref.instance-template.selfLink).

Com referências, é possível:

  • Acessar propriedades que não são definidas até a criação do recurso. Por exemplo, ao definir uma máquina virtual na configuração, você ainda não conhece o respectivo endereço IP. Mesmo assim, ainda é possível usar uma referência ao endereço IP. Ao implantar a configuração, a VM é criada primeiro e o Deployment Manager recebe o endereço IP externo quando ele se torna disponível.

  • Facilite a leitura e a resolução de problema das suas configurações ou modelos. Por exemplo, se você precisar configurar várias regras de encaminhamento, também precisará especificar uma rede a ser usada. Em vez de fornecer um link para a rede a cada regra de encaminhamento, crie uma referência à propriedade selfLink da rede usando a seguinte sintaxe:

    $(ref.network-name.selfLink)

    Se você precisar solucionar problemas de configuração, a referência facilita a identificação da rede que está sendo usada na regra de encaminhamento.

Ao criar uma referência para um recurso, você também criará uma dependência entre recursos. Por exemplo, pense no seguinte snippet, em que sandbox-vm usa uma referência a network-a:

resources:
- name: sandbox-vm
  type: compute.v1.instance
  properties:
    network: $(ref.network-a.selfLink)
    ...
...
- name: network-a
  type: compute.v1.network
  properties:
    ...

Quando você implanta essa configuração, o Deployment Manager cria network-a antes de sandbox-vm, para que a referência possa ser resolvida. Se alguma referência não for resolvida com sucesso, sua implementação falhará.

Você pode usar referências tanto nos arquivos de configuração quanto nos modelos.

Antes de começar

Como fazer referências em arquivos de configuração

Declare as referências na configuração usando o seguinte formato:

$(ref.RESOURCE_NAME.PROPERTY)

O exemplo a seguir primeiro cria uma rede e depois cria duas instâncias que usam referências à rede recém-criada. Neste exemplo, a referência é:

$(ref.a-new-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-11
    networkInterfaces:
    # 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 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-11
    networkInterfaces:
    # 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 NAT
        type: ONE_TO_ONE_NAT
# The following network is a new resource added to the "two-vms.yaml" file.
- name: a-new-network
  type: compute.v1.network
  properties:
    routingConfig:
      routingMode: REGIONAL
    autoCreateSubnetworks: true

Quando você implanta essa configuração, a rede é criada antes das duas instâncias, e a referência é resolvida para o selfLink do recurso de rede.

Como fazer referências em arquivos de modelo

Nos arquivos de modelo, é necessário que a referência inteira esteja entre parênteses, precedidos por um $:

$(ref.RESOURCE_NAME.PROPERTY)

É possível combinar referências com outros recursos, como propriedades de modelo e variáveis de ambiente. Para garantir que o Deployment Manager analise a referência corretamente, é importante manter a string de referência inteira entre parênteses.

Aqui estão alguns exemplos de declaração de referências nos modelos:

Jinja

  • Referência que inclui uma variável de ambiente

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

  • Referência a um valor em uma matriz

    subnetwork: $(ref.{{ env["deployment"] }}-vm.networkInterfaces[2].subnetwork)

  • Referência que inclui uma propriedade de modelo

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

  • Referência usando um parâmetro Jinja

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

  • Referência de saídas

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

Python

  • Referência que inclui uma variável de ambiente

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

  • Referência a um valor em uma matriz

    'subnetwork': '$(ref.' + context.env['deployment'] + '-vm.networkInterfaces[2].subnetwork)'

  • Referência que inclui uma propriedade de modelo

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

  • Referência que usa um parâmetro Python

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

  • Referência de saídas

    outputs = [{'name': 'UrlToService',
            'value': '$(ref.' + context.env['deployment'] + '-network.networkInterfaces[0].accessConfigs[0].natIP):8080'}]

A seguir