Usar referências

Quando define as propriedades da sua configuração ou modelos, pode usar referências às propriedades de outros recursos em vez de fornecer diretamente valores. Por exemplo, se quiser criar um grupo de gestores de instâncias que use um modelo de instância da mesma implementação, em vez de escrever explicitamente o link completo para o modelo de instância, pode usar uma referência com a sintaxe $(ref.instance-template.selfLink).

Com as referências, pode:

  • Aceda a propriedades que não estão definidas até o recurso ser criado. Por exemplo, quando define uma máquina virtual na sua configuração, ainda não sabe o respetivo endereço IP. No entanto, ainda pode usar uma referência ao endereço IP. Quando implementa a configuração, a VM é criada primeiro e o Deployment Manager recebe o endereço IP externo quando estiver disponível.

  • Facilitar a leitura e a resolução de problemas das suas configurações ou modelos. Por exemplo, se precisar de configurar várias regras de encaminhamento, também tem de especificar uma rede a usar. Em vez de fornecer um link para a rede para cada regra de encaminhamento, pode criar uma referência à propriedade selfLink da rede através da seguinte sintaxe:

    $(ref.network-name.selfLink)

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

Quando cria uma referência a um recurso, também cria uma dependência entre recursos. Por exemplo, considere o seguinte fragmento, 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 implementa esta 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 êxito, a implementação falha.

Pode usar referências em configurações e modelos.

Antes de começar

Fazer referências em ficheiros de configuração

Declare referências na sua configuração através do seguinte formato:

$(ref.RESOURCE_NAME.PROPERTY)

O exemplo seguinte cria uma rede e, em seguida, 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 implementa esta configuração, a rede é criada antes das duas instâncias e a referência é resolvida para o selfLink do recurso de rede.

Fazer referências em modelos

Nos ficheiros de modelos, toda a referência tem de ser precedida por $ e, em seguida, estar contida num conjunto de parênteses:

$(ref.RESOURCE_NAME.PROPERTY)

Pode combinar referências com outras funcionalidades, como propriedades de modelos e variáveis de ambiente. Para se certificar de que o Deployment Manager analisa a referência corretamente, é importante lembrar-se de manter toda a string de referência entre parênteses.

Seguem-se alguns exemplos de declaração de referências nos seus modelos:

Jinja

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

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

  • Referência a um valor numa matriz

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

  • Referência que inclui uma propriedade de modelo

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

  • Faça referência através de um parâmetro Jinja

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

  • Referência em 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 numa 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 através de um parâmetro Python

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

  • Referência em saídas

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

O que se segue?