Utiliser des schémas

Un schéma décrit les spécifications d'un modèle Deployment Manager. Si un schéma existe pour un modèle, Deployment Manager utilise ce schéma pour définir la façon dont les utilisateurs peuvent interagir avec le modèle. Les schémas définissent un ensemble de règles qu'un fichier de configuration doit respecter pour qu'il soit possible d'utiliser un modèle particulier.

Les schémas ne servent pas uniquement à définir les règles d'un modèle. Ils permettent également aux utilisateurs d'exploiter les modèles que vous écrivez, sans qu'il leur soit nécessaire d'examiner et de connaître en détail chaque couche de ces modèles. Les utilisateurs peuvent simplement consulter les exigences définies dans votre schéma. Ils n'ont pas besoin de savoir quelles propriétés sont paramétrables ou requises pour le modèle concerné.

Par exemple, vous pouvez créer un schéma dans lequel le modèle correspondant doit toujours définir un ensemble spécifique de propriétés requises, chacune d'entre elles ayant des caractéristiques qui lui sont propres. Une propriété doit être une chaîne, une autre doit être un nombre entier inférieur à 100, et ainsi de suite. Si un utilisateur souhaite appliquer votre modèle, il lui suffit d'examiner le schéma et de définir correctement les propriétés dans sa configuration.

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 un modèle de base.
• Assurez-vous d'avoir bien compris comment créer une configuration.
• Assurez-vous d'avoir bien compris le schéma JSON.

Exemple de schéma

L'exemple de schéma est écrit pour le moteur de création de modèles Jinja. Si vous utilisez un autre moteur de création de modèles, vos extensions de fichier et la syntaxe du modèle peuvent varier.

Il s'agit d'un fichier de schéma simple nommé vm-instance-with-network.jinja.schema :

info:
  title: VM Template
  author: Jane
  description: Creates a new network and instance
  version: 1.0

imports:
- path: vm-instance.jinja # Must be a relative path

required:
- IPv4Range

properties:
  IPv4Range:
    type: string
    description: Range of the network

  description:
    type: string
    default: "My super great network"
    description: Description of network

Le schéma s'applique à ce modèle, vm-instance-with-network.jinja :

resources:
- name: vm-1
  type: vm-instance.jinja

- name: a-new-network
  type: compute.v1.network
  properties:
    IPv4Range: {{ properties['IPv4Range'] }}
    description: {{ properties['description'] }}

Si un utilisateur souhaite utiliser ce modèle dans sa configuration, il peut vérifier qu'il existe une propriété obligatoire qu'il doit définir (IPv4Range) et une propriété facultative description qu'il peut omettre ou inclure. Un utilisateur peut ensuite créer un fichier de configuration, en veillant à fournir une propriété nommée IPv4Range :

imports:
- path: vm-instance-with-network.jinja

resources:
- name: vm-1
  type: vm-instance-with-network.jinja
  properties:
    IPv4Range: 10.0.0.1/16

Structure d'un schéma

Vous trouverez ci-dessous un exemple de document de schéma. Deployment Manager recommande que les schémas soient écrits au format YAML, mais vous pouvez également écrire des schémas au format JSON qui seront acceptés par Deployment Manager.

Deployment Manager accepte les schémas écrits conformément à la révision 4 des spécifications du schéma JSON.

<mongodb.py.schema>
info:
  title: MongoDB Template
  author: Jane
  description: Creates a MongoDB cluster
  version: 1.0

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

required:
  - name

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

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

  zone:
    type: string
    default: us-central1-a
    description: Zone to run
    metadata: gce-zone

Un fichier de schéma valide est un fichier de schéma JSON auquel sont ajoutés deux champs de niveau supérieur, info et imports. Les paragraphes suivants décrivent brièvement chaque champ et les types de contenus valides associés.

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é.

imports

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

Lorsque vous spécifiez un fichier dans ce champ d'importation, vous pouvez l'omettre de votre champ imports dans la configuration. Dans l'exemple ci-dessus, le champ imports importe un nom de fichier vm-instance.jinja:

imports:
- path: vm-instance.jinja

L'utilisateur n'a pas besoin d'indiquer l'importation du fichier vm-instance.jinja dans le fichier de configuration correspondant. Celui-ci sera de toute manière importé automatiquement lorsque Deployment Manager inspectera le schéma du modèle.

Les chemins d'importation doivent être relatifs à l'emplacement du fichier de schéma. Cela vous permet de stocker les modèles, les schémas et les configurations dans le même répertoire et de vous assurer que les fichiers seront correctement importés, même si le répertoire est partagé ou déplacé.

requis

Le champ requiredcontient 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.

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 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 default pour les propriétés facultatives.

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

Remarque : Techniquement, il n'est pas nécessaire de décrire toutes les propriétés qui peuvent être définies pour vos modèles dans le schéma. Pour des raisons qui vous sont propres, vous pouvez décider de décrire certaines propriétés et pas d'autres. Il vous appartient de décider quelle quantité d'informations vous souhaitez inclure. Par exemple, vous pouvez inclure une propriété dans le champ required qui n'est pas décrite dans la section properties, ce qui signifie que la propriété doit être définie, mais que vous avez décidé de ne pas décrire la propriété dans le schéma

Définir des métadonnées arbitraires

Par défaut, Deployment Manager ignore les champs qui ne correspondent pas à un schéma JSON valide. Si vous avez besoin d'étendre vos schémas afin d'insérer des champs ou propriétés spécialisés, vous pouvez créer arbitrairement n'importe quelle propriété et l'ajouter à votre schéma, l'essentiel étant que le champ ou la propriété ne chevauche aucun mot clé de validation du schéma JSON.

Par exemple, vous pouvez ajouter un champ de métadonnées afin d'insérer une annotation sur l'une de vos propriétés :

properties:
  zone:
    type: string
    default: us-central1-a
    description: Zone to run
    metadata: a-special-property

Vous pouvez également créer une variable spéciale que vous pourrez utiliser dans d'autres applications en dehors de Deployment Manager :

properties:
  size:
    type: integer
    default: 2
    description: Number of Mongo Slaves
    variable-x: ultra-secret-sauce

Créer un schéma

Un schéma est un document distinct nommé en fonction du modèle qu'il décrit. Les schémas doivent porter le même nom que le modèle correspondant, avec .schema ajouté à la fin :

TEMPLATE_NAME.EXTENSION.schema

Par exemple, pour un modèle nommé vm-instance.py, le fichier de schéma correspondant doit être nommé vm-instance.py.schema. Un seul schéma peut exister pour chaque modèle.

Les schémas peuvent contenir un ou plusieurs des champs décrits dans la section Structure d'un schéma. Vous pouvez également écrire des schémas en JSON. Pour consulter des exemples de schémas JSON, reportez-vous à la documentation relative au schéma JSON.

Utiliser un schéma

gcloud

Lorsque vous créez un déploiement à l'aide de la Google Cloud CLI, Deployment Manager importe automatiquement tous les modèles pertinents pour la configuration. De même, s'il existe des fichiers de schéma, identifiés par le format .schema ajouté, Deployment Manager importe le schéma et valide le déploiement par rapport à celui-ci avant de tenter de créer des ressources.

Pour utiliser un schéma, incluez-le simplement dans le répertoire local contenant vos modèles et votre configuration, puis créez votre déploiement comme vous le feriez normalement. La gcloud CLI détecte le fichier de schéma et le transmet à Deployment Manager.

API

Suivez les instructions pour créer un déploiement dans l'API et incluez le fichier de schéma en ligne avec le corps de votre requête comme si vous incluiez un modèle.

Étapes suivantes

• En savoir plus sur les modèles
• Utiliser les propriétés du modèle pour pousser plus avant l'abstraction de contenu
• Renseigner des informations relatives à vos projets et déploiements à l'aide de variables d'environnement
• Ajouter un modèle qui sera associé de façon permanente à votre projet en tant que type composite