Documentation de référence sur la syntaxe

Cette page décrit la syntaxe utilisée par Deployment Manager. Utilisez ce guide comme référence pour la syntaxe à utiliser dans vos configurations et modèles.

Syntaxe pour les configurations et les modèles

Syntaxe de base

  • resources : ensemble de ressources à créer.
    • name : nom utilisé pour cette instanciation de la ressource concernée.
    • type : type de la ressource. Il peut s'agir d'un type de base comme compute.v1.instance, d'un fournisseur de type tel que gcp-types/compute-v1:addresses ou d'un modèle importé. Consultez la liste des fournisseurs de types agréés.
    • properties : propriétés de la ressource concernée. Pour en savoir plus à ce sujet, consultez la section Propriétés du modèle.
    • metadata : options de configuration supplémentaires pour la ressource concernée. La liste des champs disponibles est présentée dans la section Métadonnées.

Exemple

resources:
- name: vm-instance
  type: compute.v1.instance
  properties:
    machineType: zones/us-central1-a/machineTypes/n1-standard-1
    ...

Contrôle des accès

Si vous souhaitez définir des stratégies IAM sur vos ressources, vous devez utiliser une section accessControl :

  1. Ajoutez la section accessControl à la configuration de premier niveau pour chaque ressource à laquelle vous souhaitez appliquer des stratégies de contrôle d'accès.

  2. Spécifiez la stratégie gcpIamPolicy souhaitée pour la ressource. Chaque stratégie IAM peut contenir plusieurs liaisons. Chaque liaison associe une liste de comptes principaux à un rôle.

Pour obtenir des informations détaillées sur le contrôle des accès aux ressources, consultez la page Définir le contrôle des accès d'une configuration.

Par exemple, la section accessControl suivante ajoute des liaisons qui attribuent ces rôles aux utilisateurs :

User Rôle
alice@example.com roles/pubsub.editor
  • my-other-app@appspot.gserviceaccount.com
  • jane@example.com
 roles/pubsub.publisher 
resources:
- name: a-new-pubsub-topic
  type: pubsub.v1.topic
  properties:
    ...

  accessControl:
    gcpIamPolicy:
      bindings:
      - role: roles/pubsub.editor
        members:
        - "user:alice@example.com"
      - role: roles/pubsub.publisher
        members:
        - "user:jane@example.com"
        - "serviceAccount:my-other-app@appspot.gserviceaccount.com"

Références

Pour en savoir plus sur l'utilisation des références et découvrir d'autres exemples, consultez la page sur la création de références.

Vous pouvez utiliser des references aux propriétés d'autres ressources au lieu de fournir directement des valeurs. Par exemple, si vous souhaitez créer un gestionnaire de groupe d'instances qui utilise un modèle d'instance du même déploiement, au lieu de saisir explicitement le lien d'accès complet au modèle d'instance, vous pouvez indiquer une référence en appliquant la syntaxe $(ref.instance-template.selfLink).

Pour voir les propriétés vers lesquelles vous pouvez créer des références, consultez la méthode get de l'API de la ressource. Par exemple, pour obtenir la liste de toutes les propriétés d'une instance de VM, consultez la réponse de la méthode instances.get().

Vous déclarez des références en utilisant une syntaxe semblable à la notation JSONPath suivie d'un point. Pour déclarer une référence, utilisez la syntaxe suivante :

$(ref.RESOURCE_NAME.PATH_TO_PROPERTY)

Pour les propriétés qui correspondent à des listes, telles que les interfaces réseau d'une instance Compute Engine, utilisez la syntaxe suivante :

$(ref.RESOURCE_NAME.LIST_PROPERTY[index].ITEM)

Exemples

$(ref.exampleInstance.networkInterfaces[0].natIp)
$(ref.exampleInstance.serviceAccounts[0].email)

Variables d'environnement spécifiques au déploiement

Lorsque vous créez un déploiement, Deployment Manager génère des variables d'environnement contenant des informations sur votre déploiement, telles que le nom du projet en cours, le nom du déploiement, etc.

Pour une liste complète des variables d'environnement disponibles, consultez la section Variables d'environnement.

Pour utiliser une variable d'environnement :

{{ env["deployment"] }} # Jinja

context.env["deployment"] # Python

Exemple

- type: compute.v1.instance
  name: vm-{{ env["deployment"] }}

Propriétés du modèle

Une propriété de modèle est une propriété arbitraire que vous créez. Au lieu de coder une valeur en dur, vous pouvez déclarer une propriété de modèle et définir la valeur de la propriété dans la configuration de niveau supérieur. Vous n'avez ainsi pas besoin de fournir la propriété et la valeur directement dans le modèle. Pour créer une propriété de modèle, utilisez la syntaxe suivante :

{{ properties["property-name"] }} # Jinja

context.properties["property-name"] # Python

Ensuite, dans votre configuration de niveau supérieur ou votre modèle parent, définissez la valeur de la propriété :

imports:
- path: vm_template.jinja

resources:
- name: my-vm
  type: vm_template.jinja
  properties:
   property-name: example-value

En savoir plus sur les propriétés de modèle.

Résultats

Dans la section des sorties, vous pouvez définir des paires valeur/clé arbitraires qui exposent certaines informations relatives à votre déploiement. Pour cela, vous devez fournir la clé et définir la valeur sous la forme d'une chaîne statique, d'une référence à une propriété, d'une variable de modèle ou d'une variable d'environnement.

  • outputs : déclare une liste de résultats que les utilisateurs peuvent appeler dans leurs propriétés de ressources.
    • name : nom de la propriété de sortie.
    • value : valeur de la propriété de sortie.

Exemple

resources:
- name: vm-instance
  type: compute.v1.instance
  ...

outputs:
- name: databaseIp
  value: $(ref.vm-instance.networkInterfaces[0].natIp)
- name: databaseName
  value: example-database

En savoir plus sur les sorties.

Métadonnées

La section metadata contient des métadonnées spéciales que vous pouvez appliquer par ressource. Deployment Manager utilise des métadonnées uniques qui déclenchent certaines fonctionnalités. Par exemple, la fonction dependsOn repose sur une entrée de métadonnées.

Depends on

La propriété dependsOn crée des dépendances explicites entre vos ressources. Par exemple, si vous spécifiez que la ressource A dépend de la ressource B, la ressource B sera toujours créée avant la ressource A.

metadata: the metadata for this resource
  dependsOn: Any explicit dependencies to another resource.

Exemple

resources:
- name: vm-instance
  type: compute.v1.instance
  properties:
    machineType: zones/us-central1-a/machineTypes/n1-standard-1
    ...
  metadata:
    dependsOn:
    - persistent-disk-1
    - a-new-network-1

En savoir plus sur la création de dépendances explicites.

Syntaxe pour les schémas

Un schéma vous permet de contrôler la façon dont vos utilisateurs peuvent interagir avec vos modèles. La syntaxe suivante peut être utilisée dans votre fichier de schéma. En savoir plus sur les schémas

info

La propriété info contient des méta-informations sur le schéma. Elle inclut notamment des informations telles que le titre, le numéro de version, la description, etc.

Ajoutez au minimum un titre et une description dans cette propriété.

Exemple

info:
  title: MongoDB Template
  author: Jane
  description: Creates a MongoDB cluster
  version: 1.0

imports

Le champ imports contient la liste des fichiers requis pour les modèles utilisant ce schéma. Lorsque vous importez un modèle avec un schéma comportant une liste d'importations, Deployment Manager vérifie que tous les fichiers de la propriété imports ont été importés avec le modèle.

Exemple

imports:
  - path: helper.py
    name: mongodb_helper.py

required

Le champ required contient la liste des éléments du champ properties requis dans le modèle qui utilise le schéma. Les éléments qui ne sont pas spécifiés dans ce champ required sont considérés comme facultatifs.

Exemple

required:
  - name

properties:
  name:
    type: string
    description: Name of your Mongo Cluster

  size:
    type: integer
    default: 2
    description: Number of Mongo Secondaries

properties

Le champ properties contient les règles de schéma JSON applicables à ce document. Les éléments décrits dans le champ properties peuvent être définis par les utilisateurs du modèle. Vous pouvez utiliser toutes les validations de schéma JSON prises en charge pour ces propriétés, telles que :

  • type (string, boolean, integer, number, ...)
  • default
  • minimum / exclusiveMinimum / maximum / exclusiveMaximum
  • minLength / maxLength
  • pattern
  • not X / allOf X, Y / anyOf X, Y / oneOf X, Y

Il est au minimum recommandé d'inclure un type et une description pour le champ afin que les utilisateurs sachent quelles valeurs peuvent être utilisées pour la propriété. En outre, une bonne pratique consiste à inclure une valeur par défaut pour les propriétés facultatives.

Lisez la documentation Validation de schéma JSON pour obtenir une liste des mots-clés de validation.

Exemple

properties:
  name:
    type: string
    description: Name of your Mongo Cluster

  size:
    type: integer
    default: 2
    description: Number of Mongo Secondaries
    minimum: 1

Étapes suivantes