Exposer les informations à l'aide de sorties

Lorsque vous créez un déploiement, vous pouvez exposer les propriétés clés de vos configurations ou modèles pour que d'autres modèles ou d'autres utilisateurs aient accès à ces informations. Par exemple, vous pouvez exposer l'adresse IP d'une base de données créée dans un modèle afin que les utilisateurs puissent facilement référencer cette adresse IP lorsqu'ils configurent leurs propres modèles.

Vous pouvez utiliser la section Résultats de votre modèle ou configuration pour définir la liste des paires valeur/clé que les utilisateurs peuvent appeler. Dans la section des résultats, créez des clés arbitraires et définissez la valeur de ces clés sur une référence, une propriété de modèle ou une variable d'environnement. Les utilisateurs peuvent consulter les sorties pour accéder aux informations clés sur les ressources créées par le modèle. Par exemple, vous pouvez déclarer une sortie appelée databaseIP qui référence l'adresse IP d'une instance hébergeant une base de données, ce qui permet aux utilisateurs de référencer cette sortie dans d'autres modèles du même déploiement.

Avant de commencer

• Si vous voulez vous servir des exemples de ligne de commande de ce guide, installez l'outil de ligne de commande gcloud.
• Si vous voulez utiliser les exemples d'API de ce guide, configurez l'accès aux API.
• Assurez-vous d'avoir bien compris comment créer une configuration de base.

Exemple

Voici un exemple de modèle avec des sorties :

mongodb.jinja
{% set MASTER = env["name"] + "-" + env["deployment"] + "-mongodb" %}
resources:
- name: {{ MASTER }}
  type: instance
  ...
outputs:
- name: databaseIp
  value: $(ref.{{ MASTER }}.network[0].ip)  # Treated as a string during expansion
- name: databasePort
  value: 88

La section des sorties déclare deux propriétés : databaseIp et databasePort. La propriété databaseIp utilise une référence qui résout l'adresse IP réseau de la ressource principale, tandis que databasePort est une valeur statique. Un autre modèle vous permet d'importer mongodb.jinja, de l'utiliser en tant que type et d'appeler les sorties. Exemple :

imports:
- path: example/path/to/mongodb.jinja
  name: mongodb.jinja

resources:
- name: my_mongo
  type: mongodb.jinja
  properties:
    size: 100

- name: my_instance
  type: compute.v1.instance
  properties:
    …
    databaseIp: $(ref.my_mongo.databaseIp)
    databasePort: $(ref.my_mongo.databasePort)

Déclarer une sortie

Vous pouvez déclarer une sortie dans un modèle ou une configuration en définissant une section outputs: au même niveau que la section resources:. Les clés de sortie doivent être uniques dans le modèle ou la configuration.

Une section outputs: pourrait par exemple ressembler à ceci :

...
outputs:
- name: databaseIp
  value: $(ref.my-first-vm.networkInterfaces[0].accessConfigs[0].natIP)
- name: machineType
  value: {{ properties['machineType'] }}
- name: databasePort
  value: 88

Dans un modèle complet, la section outputs pourrait ressembler à cela :

resources:
- name: my-first-vm
  type: compute.v1.instance
  properties:
    zone: us-central1-a
    machineType: zones/us-central1-a/machineTypes/{{ properties['machineType'] }}
    disks:
    - deviceName: boot
      type: PERSISTENT
      boot: true
      autoDelete: true
      initializeParams:
        sourceImage: projects/debian-cloud/global/images/family/debian-11
    networkInterfaces:
    - network: global/networks/default
      accessConfigs:
      - name: External NAT
        type: ONE_TO_ONE_NAT

# Declare outputs here
outputs:
- name: databaseIp
  value: $(ref.my-first-vm.networkInterfaces[0].accessConfigs[0].natIP)
- name: machineType
  value: {{ properties['machineType'] }}
- name: databasePort
  value: 88

Les valeurs de sortie peuvent se présenter sous différentes formes :

• Une chaîne statique
• Une référence à une propriété
• Une propriété de modèle
• Une variable d'environnement

Utiliser les sorties des modèles

Pour utiliser une sortie définie dans un modèle, importez le modèle contenant la sortie en tant que type. Par exemple, pour utiliser les sorties définies dans un modèle appelé template_with_outputs.jinja, vous devez importer le modèle et créer une ressource sur cette base :

# 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.
imports:
- path: template_with_outputs.jinja
  name: template.jinja

resources:
- name: my-first-vm
  type: template.jinja
  properties:
    machineType: n1-standard-1

outputs:
- name: databaseIp
  value: $(ref.my-first-vm.databaseIp)
- name: machineType
  value: $(ref.my-first-vm.machineType)
- name: databasePort
  value: $(ref.my-first-vm.databasePort)

Pour appeler une sortie, utilisez le format suivant :

$(ref.RESOURCE.OUTPUT)

• RESOURCE correspond au nom de la ressource créée par le modèle. Dans l'exemple ci-dessus, il s'agit de my-first-vm.

• OUTPUT correspond à la sortie déclarée dans le modèle. Dans l'exemple ci-dessus, vous devriez utiliser databaseIpet databasePort. Il s'agit de la même syntaxe que vous utilisez pour déclarer des références. Vous pouvez également référencer des éléments de liste (par exemple, $ref.template.property[0])

Lorsque vous déployez la configuration, Deployment Manager développe la configuration, puis remplace les références aux sorties par les valeurs de sortie.

Décrire les résultats dans des schémas

Pour les modèles dotés de schémas d'accompagnement, vous pouvez décrire les propriétés de sortie plus en détail. Deployment Manager n'applique ni ne valide aucune information présente dans la section des sorties. Il peut toutefois être utile de fournir des informations complémentaires sur les sorties pertinentes dans cette section afin d'aider les utilisateurs qui s'appuient sur vos modèles.

Dans votre fichier de schéma, fournissez une section outputs correspondant à la sortie de votre modèle. Exemple :

...
outputs:
  databaseIp:
    description: Reference to ip address of your new cluster
    type: string
  databasePort:
    description: Port to talk on
    type: integer

Les utilisateurs peuvent se référer à votre fichier de schéma pour comprendre comment utiliser vos sorties et connaître leur type.

Rechercher les valeurs de sortie finales

Une fois que vous avez déployé des modèles utilisant des sorties, vous pouvez visualiser les valeurs de sortie finales en affichant le schéma de configuration du déploiement. Les valeurs de sortie finales sont indiquées par la propriété finalValue. Toutes les valeurs de sortie sont incluses dans ce champ, y compris les valeurs de sortie des modèles imbriqués. Exemple :

layout: |
  resources:
  - name: vm_template
    outputs:
    - finalValue: 104.197.69.69
      name: databaseIp
      value: $(ref.vm-test.networkInterfaces[0].accessConfigs[0].natIP)
    properties:
      zone: us-central1-a
    resources:
    - name: datadisk-example-instance
      type: compute.v1.disk
    - name: vm-test
      type: compute.v1.instance
    type: vm_template.jinja
name: manifest-1455057116997

Éviter les dépendances circulaires

Soyez prudent lorsque vous créez des modèles dans lesquels deux ou plusieurs ressources s'appuient sur les sorties respectives des autres ressources. Deployment Manager n'empêche pas ce type de structure, mais si les sorties ont provoqué une dépendance circulaire, le déploiement ne s'effectuera pas correctement. Par exemple, le fragment de code suivant est accepté par Deployment Manager, mais si le contenu des modèles entraîne une dépendance circulaire, le déploiement échoue :

resources:
- name: frontend
  type: frontend.jinja
  properties:
    ip: $(ref.backend.ip)
- name: backend
  type: backend.jinja
  properties:
    ip: $(ref.frontend.ip)

Voyons maintenant un exemple de dépendance circulaire entraînant l'échec du déploiement. Supposons que frontend.jinja et backend.jinja ressemblent à ceci :

resources:
- name: {{ env['name'] }}
  type: compute.v1.instance
  properties:
    zone: us-central1-f
    ...
    networkInterfaces:
    - network: global/networks/default
      accessConfigs:
      - name: External NAT
        type: ONE_TO_ONE_NAT
    metadata:
      items:
      - key: startup-script
        value: |
          #!/bin/bash
          export IP={{ properties["ip"] }}
      ...

outputs:
- name: ip
  value: $(ref.{{ env['name'] }}.networkInterfaces[0].accessConfigs[0].natIP)

Rappelez-vous que chacune des deux ressources a utilisé la propriété de sortie IP de l'autre ressource :

resources:
- name: frontend
  type: frontend.jinja
  properties:
    ip: $(ref.backend.ip)
- name: backend
  type: backend.jinja
  properties:
    ip: $(ref.frontend.ip)

Mais aucun champ de valeur IP ne peut être peuplé car chacune des deux propriétés dépend de l'existence de l'autre ressource, ce qui crée une dépendance circulaire. Voici le même modèle, entièrement développé :

resources:
- name: frontend
  type: compute.v1.instance
  properties:
    zone: us-central1-f
    ...
    networkInterfaces:
    - network: global/networks/default
      accessConfigs:
      - name: External NAT
        type: ONE_TO_ONE_NAT
    metadata:
      items:
      - key: startup-script
        value: |
          #!/bin/bash
          export IP=$(ref.backend.networkInterfaces[0].accessConfigs[0].natIP)
- name: backend
  type: compute.v1.instance
  properties:
    zone: us-central1-f
    ...
    networkInterfaces:
    - network: global/networks/default
      accessConfigs:
      - name: External NAT
        type: ONE_TO_ONE_NAT
    metadata:
      items:
      - key: startup-script
        value: |
          #!/bin/bash
          export IP=$(ref.frontend.networkInterfaces[0].accessConfigs[0].natIP)

Deployment Manager renvoie une erreur si vous essayez d'exécuter la configuration :

 code: u'CONDITION_NOT_MET'
 message: u'A dependency cycle was found amongst backend, frontend.'>]>

Notez toutefois que ce modèle pourrait fonctionner si :

1. frontend.jinja créait deux instances de machines virtuelles, vm-1 et vm-2 ;
2. backend.jinja créait vm-3 et vm-4 ;
3. vm-1 exposait son adresse IP externe en tant que sortie et que vm-4 utilisait cette sortie ;
4. vm-3 exposait une adresse IP externe en tant que sortie et que vm-2 utilisait cette sortie.

Étapes suivantes

• Créer un déploiement
• En savoir plus sur les modèles