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 fichiers sont différentes et la syntaxe du modèle peut l'être aussi.
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é.
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.
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
(chaîne, booléen, entier, nombre, etc.)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 sur la Validation de schéma JSON pour obtenir la liste des mots-clés de validation.
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 sur le 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 un fichier de schéma, identifié par le suffixe .schema
, Deployment Manager importera le schéma et validera 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. Ensuite, incluez le fichier de schéma en ligne dans le corps de votre requête en procédant de la même façon que lorsque vous incluez un modèle.
Étape suivante
- 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