View Source

Qu'est-ce que sont les règles de mapping VMWare ?

Ces règles permettent, lors de l'import, de mettre en relation un champ de l'API VMWare avec une propriété ou une donnée de Shinken en fonction du type de l'élément ( hôte, modèle d'hôte, etc ... ).

Elle s'applique pour tous les types d’éléments présents dans l'interface de Shinken.

Définition des règles de mapping

Comme pour les règles d'application des modèles, les règles de mapping sont écrites au format JSON.

La source VMWare ne concerne que les hôtes, donc les fichiers sources commenceront toujours par "hosts"

Elle doit respecter le format suivant :

Valeur du champ de l'API VMWare : nom de la propriété ou de la donnée Shinken
- Il est possible pour la valeur du champ de l'API VMWare de sélectionner les données que l'on veut de la source. Voir les règles de mapping décrites ci-après.

Une propriété est une information nécessaire au moteur Shinken. Pour utiliser une propriété Shinken, vous devez utiliser le nom de cette propriété défini pour l'import des fichiers ( voir la liste des clés d'import présente dans la page Syntaxe des fichiers d'imports ).

Une donnée est une valeur qui va être ajoutée en complément des propriétés. Pour utiliser une donnée, il faut lui donner un nom en la faisant commencer par underscore "_", par exemple "_OS_TYPE".

{
  "hosts": {
    "name": "host_name",
    "shinken.ipAddress" : "address"
    "shinken.machine_type": "_MACHINE_TYPE",
    "config.product.osType": "_OS_TYPE",
  }
}

Il existe 4 règles de mapping définies :

Clé VMWare	Clé Shinken	Description du mapping
name	host_name	La valeur VMWare "name" deviendra le nom de l'hôte ( propriété host_name )
shinken.ipAddress	address	La valeur VMWare "shinken.ipAddress" sera prise en compte comme adresse pour l'hôte ( propriété address )
shinken.machine_type	_MACHINE_TYPE	La valeur VMWare "shinken.machine_type" deviendra une donnée nommée _MACHINE_TYPE sur l'hôte
config.product.osType	_OS_TYPE	La valeur VMWare "config.product.osType" deviendra une donnée nommé _OS_TYPE sur l'hôte

Il est possible d'ajouter des commentaires dans ce fichier.
Toutes les lignes qui commencent par le caractère # seront considérées comme des commentaires.
La clé d'import Shinken n'est pas le nom affiché dans les pages des éléments, mais le nom de la propriété lors de l'import dans Shinken.
Pour trouver le nom d'import d'une propriété, vous pouvez ouvrir l'aide d'une propriété dans une page d'édition d'un élément ( voir la page Editer les Eléments ( hôte, clusters, checks, utilisateurs ... ) ( paragraphe "Informations contextuelles" ) ).
Retrouvez la liste complète des champs VMware collectés par la source sur la page Liste des champs collectés auprès des VCenters ou ESXs .

La propriété shinken _SE_UUID ne peut pas être mappée

Règles de mapping pour les listes ( VALUES )

La source VMWare peux fournir des champs dont les valeurs sont des listes ( par exemple le champ "shinken.tags" ).

Pour faire correspondre une valeur de liste dans un champs de Shinken nous proposons un nouveau mot clé : "VALUES"

Une VM possède la liste de tags suivants : LINUX, FR, DATACENTER_42

Le mapping suivant :

{
  "hosts": {
     "shinken.tags>VALUES(0)": "_MACHINE_TYPE",
     "shinken.tags>VALUES(=DATACENTER)": "_DATACENTER", 
   }
}

Va permettre de créer un hôte avec comme données :

_MACHINE_TYPE LINUX
_DATACENTER   DATACENTER_42

_MACHINE_TYPE contient la première valeur ( indice 0 ) de la liste.
_DATACENTER se voit affecter les valeurs qui contiennent au moins DATACENTER.

Définition de l'utilisation de VALUES

La syntaxe de la condition dans "VALUES(condition)" est la suivante

Signification	Syntaxe	Description	Exemple
Index	nombre	Récupère l'élément à l'index indiqué. L’index doit être un nombre appartenant à l’ensemble des entiers naturels, incluant 0. Cette règle admet une seule exception afin de rendre possible de choisir le dernier élément d’une liste, en utilisant l’index -1. L’index 0 récupérera le premier élément de la liste, 1 le deuxième, 2 le troisième, etc...	`VALUES(0)`
Contient	=texte	La condition signifie que l'élément choisi doit CONTENIR le texte.	`VALUES(=PROD)`
Commence par	=^texte	Si l'expression commence par le caractère "^", la condition signifie que l'élément choisi doit COMMENCER par le texte	`VALUES(=^PROD)`
Termine par	=texte$	Si l'expression termine par le caractère "$" la condition signifie que l'élément choisi doit TERMINER par le texte.	`VALUES(=PROD$)`
Est strictement égal	=^texte$	Si l'expression commence par "^" ET términe par "$", la condition signifie que l'élément choisi doit être l'expression EXACTE	`VALUES(=PROD$)`
Inversion	=!^texte$	Ajouter un "!" avant une autre expression provoque l'effet inverse de celle-ci : • =!texte --> L'élément choisit ne contient pas "texte" • =!^texte --> L'élément choisit ne commence pas par "texte" • =!texte$ --> L'élément choisit ne termine pas par "texte" • =!^texte$ --> L'élément choisit n'est pas strictement égal à "texte"	`VALUES(=!PROD`)

Les conditions sur le texte ne font pas la distinction entre les majuscules et les minuscules.
- Exemple : la règle suivante pourra récupérer la valeur "Bordeaux
  shinken.tags>VALUES(=BoRdeaUx)
Si plusieurs valeurs valident la condition, "VALUES" retourne une liste de valeurs
Si une liste est vide ( Exemple : aucun tags attaché à cette VM ), VALUES ( quels que soient les paramètres ) ne retourne rien
Si une faute de frappe est faite sur le mot VALUES, l’interface de mapping des sources indique une clé inconnue.
VALUES(X) avec X ayant une valeur supérieure au nombre d'éléments présents dans la liste ne retourne rien. ( Exemple : essayer de récupérer le 5ème élément sur une liste de 3 éléments )

Règles de mapping pour les transformations ( TRANSFORM )

Grâce à la règle TRANSFORM il est possible de transformer du texte.

Exemple : L'API VMWare fournie la valeur "Préproduction" et l'on veut transformer cette valeur en "PREPROD" à la place.

La syntaxe de TRANSFORM est la suivante :

TRANSFORM(transformation1,transformation2,transformation3)

TRANSFORM permet d'indiquer plusieurs transformations, nous séparons ces dernières par des virgules.

Attention à ne pas mettre d'espace avant ou après une virgule, autrement il sera pris en compte dans la transformation. Il n'y a actuellement pas de limite sur le nombre de transformations autorisées.

Pour écrire une transformation, il faut séparer le texte à transformer par "=>" du texte désiré ( désigné ci-après par le mot "séparateur" ) : TEXTE1=>TEXTE2

Voici un exemple de syntaxe avec 2 transformations :

TRANSFORM(BORDEAUX=>BDX,PARIS=>PAR)

TRANSFORM permet également de supprimer du texte en laissant vide la partie à droite du séparateur ( => ) censée contenir la modification à apporter au texte.

TRANSFORM(DEAUX=>,IS=>)

Exemple avec une machine possédant les tags suivants :

ENV

Production_Bordeaux
Preproduction_Bordeaux

Et le mapping suivant :

{
  "hosts": {
     "shinken.tags_by_category.ENV>VALUES(=$production)>TRANSFORM(Production=>Prod,Bordeaux=>bdx)": "_TRANSFORM_OPERATION",
  }
}

La data _TRANSFORM_OPERATION contiendra donc la valeur suivante :

['Prod_bdx']

Lorsque TRANSFORM est appelé sur une liste de valeurs ( Exemple : shinken.tags ), il va appliquer la ou les transformations demandées sur chaque élément de la liste individuellement.

Exemple avec une machine possédant les balises ( tags ) suivantes :

OS	CentOS Alma macOS
ENV	Production_Bordeaux Preproduction_Bordeaux

Et le mapping suivant :

{
  "hosts": {
     "shinken.tags_by_category.ENV>VALUES(=production)>TRANSFORM(Production=>Prod,Preproduction=>Preprod,Bordeaux=>bdx)": "_TRANSFORM_OPERATION",
  }
}

La data _TRANSFORM_OPERATION contiendra donc les valeurs suivantes :

['Prod_bdx', 'Preprod_bdx']

Maintenant si l'on veut modifier chacun des tags de la catégorie "OS" pour le faire précéder de "OS_":

CentOS deviendrait OS_CentOS
Alma deviendrait OS_Alma
macOS deviendrait OS_macOS

Dans ce cas, il faut employer $CURRENT$ , ce mot clé prendra la valeur de la balise en train d'être modifiée.

La règle de mapping pour effectuer cette opération est la suivante :

"shinken.tags_by_category.OS>TRANSFORM($CURRENT$=>OS_$CURRENT$)": "_TRANSFORMED_OS"

C'est comme si on réécrivait la règle pour chaque balise :

CentOS → TRANSFORM(CentOS=>OS_CentOS)
Alma → TRANSFORM(Alma=>OS_Alma)
macOS → TRANSFORM(macOS=>OS_MacOS)

Règles de mapping pour les concaténations ( CONCAT )

Il est possible de concaténer plusieurs valeurs de l'API VMWare pour former la valeur d'une propriété d'un élément de Shinken. Cela est possible grâce à la règle : CONCAT.

Exemple : Une VM possédant les listes de tags suivantes :

OS	Linux
ENV	Production
LOCATION	Bordeaux

Et nous voulons les informations de la manière suivante dans la donnée nommée _MACHINE_INFOS :

"Production - Linux - Bordeaux"

La syntaxe se fera de la manière suivante dans le fichier de Mapping.

{
  "hosts": {
     "CONCAT($shinken.tags.OS.VALUES(0)$ - $shinken.tags.ENV.VALUES(0)$ - $shinken.tags.LOCATION.VALUES(0)$)": "_MACHINE_INFOS", 
   }
}

À noter que nous utilisons ici le caractère $ pour indiquer à CONCAT d'aller chercher les valeurs que nous souhaitons faire apparaître.

Si vous voulez faire apparaître le caractère $ dans la chaîne qui sera générée, il faut le doubler.

Exemple : Pour faire la chaîne suivante dans la même donnée que dans l'exemple précédent :

"Production $ Linux - Bordeaux"

Le fichier de mapping ressemblera à ceci :

{
  "hosts": {
     "CONCAT($shinken.tags.OS.VALUES(0)$ $$ $shinken.tags.ENV.VALUES(0)$ - $shinken.tags.LOCATION.VALUES(0)$)": "_MACHINE_INFOS", 
   }
}

CONCAT peut aussi récupérer les valeurs de n'importe quel nom de champ.

Exemple : Avec le fichier de configuration de la source VMWare suivant :

{
  "hosts": {
    "name": "host_name",
    "shinken.ipAddress" : "address"
    "shinken.machine_type": "_MACHINE_TYPE",
    "CONCAT($name$ - $ipAddress$)": "_MACHINE_INFOS",
  }
}

et les valeurs :

"name" valant : "Ubuntu-Preprod"
"ipAddress" valant : "192.168.1.42"

La donnée _MACHINE_INFOS vaudra :

"Ubuntu-Preprod - 192.168.1.42"

Si un champ est vide, alors CONCAT ne fournira pas de valeur pour ce champ.

Exemple, avec les mêmes données que l'exemple précédent, sauf que "name" n'a aucune valeur, la donnée _MACHINE_INFOS vaudra :

" - 192.168.1.42"

Règles de mapping pour les concaténations sur les listes ( CONCAT_ON_ALL )

Comme pour la règle TRANSFORM évoquée plus haut, il est également possible d'appliquer une opération de concaténation sur une liste, à l'aide du mon clé CONCAT_ON_ALL.

De la même manière que lorsque l'on applique l'opération TRANSFORM sur une liste, nous pouvons utiliser $VALUE$ avec CONCAT_ON_ALL pour récupérer la valeur de l'élément sur lequel l'opération est en train d'être effectuée.

Exemple :

Une VM possédant les listes de tags suivantes :

OS	Alma CentOS

Et le fichier de mapping suivant :

{
  "hosts": {
    "name": "host_name",
    "shinken.ipAddress" : "address"
    "shinken.machine_type": "_MACHINE_TYPE",
  }
}

Si on l'on souhaite associer le nom de la machine à chaque OS, on peut ajouter la règle suivante au fichier de mapping :

"shinken.tags_by_category.OS>CONCAT_ON_ALL($name$ has OS: $VALUE$)": "_MACHINE_OS"

Cela génèrera une liste d'éléments qui sera présente dans la data "_MACHINE_OS" :

['MyHost has tag  Prod', 'MyHost has tag  Preprod', 'MyHost has tag  Test']

Il n'est actuellement pas possible d'utiliser les autres règles de mapping avec le CONCAT_ON_ALL mais cela sera possible dans une prochaine version.

Désactivation d'un mapping

Les mappings peuvent être surchargés en créant un mapping avec le nom de la clé que l'on veut désactiver.

Pour le champ en question, au lieu de choisir une propriété Shinken ( ou donnée ), il faut utiliser le mot-clé "disable "

Désactivation du champ shinken.machine_type

{
  "hosts":{
    "shinken.machine_type" : "disable",
    "config.product.fullName" : "display_name"
  }
}

Shinken Entreprise V02.08.02 > Mapping des informations collectées des champs du serveur VMWare vers les propriétés et les données Shinken > A.png

Chemin du fichier de définition des règles de mapping

Pour ajouter une règle utilisateur d'application des modèles, il faut éditer le chemin suivant :

/etc/shinken-user/source-data/source-data-[nom de la source]/configuration/mapping/user_mapping_rules_vm.json
/etc/shinken-user/source-data/source-data-[nom de la source]/configuration/mapping/user_mapping_rules_esx.json

/etc/shinken-user/source-data/source-data-synchronizer-collector-vmware/configuration/mapping/user_mapping_rules_vm.json
/etc/shinken-user/source-data/source-data-synchronizer-collector-vmware/configuration/mapping/user_mapping_rules_esx.json

Visualiser la liste des mappings

Pour visualiser la liste des mapping définie pour cette source, rendez-vous dans l'onglet "Mapping vers les propriétés de Shinken".

Dans cet onglet, vous trouverez les chemins des fichiers de définition des règles mapping des utilisateurs pour l'ESX et les Machines virtuelles du serveur ESX ( 1 ).

Un message d'avertissement apparaîtra si un des fichiers n'existe pas.
Pour résoudre ce problème, créer le fichier avec le chemin indiqué sur l'interface puis appuyer le bouton de rafraîchissement ( 2 ).
Ce fichier peut être vide. Dans ce cas les valeurs par défaut seront utilisées.

Dans l'entête de la liste, vous trouverez aussi le bouton de rafraîchissement de la liste des mappings ( 2 ).

Ce bouton permet de rafraîchir la liste des mappings sans devoir redémarrer le Synchronizer.
Il faudra relancer un import pour réappliquer les nouveaux mapping sur les éléments importés.

La liste des mappings ( 3 ) comporte à la fois les mappings définis par l'utilisateur ( ligne bleue ) et les mappings par défaut ( ligne grise ).

La liste affiche pour chaque mapping une série de colonnes :

Prob. => Affiche les problèmes ou les avertissements si le mapping n'a pas été correctement défini.
Défini par => Par qui le mapping a été définie ( Par défaut ou par l'utilisateur ).
Mapping ESX/VM => Le type de mapping ( un mapping spécifique à l'ESX ou un mapping spécifique aux VMs du serveur ESX ).
La clé dans la source => Le nom du champ dans l'API VMWare.
Description ==> La description du champ dans la source.
Clé Shinken => Nom de la propriété ou donnée Shinken vers laquelle la valeur sera copiée.
Le nom de la propriété ou donnée Shinken dans l'interface.

Certaines des règles de mapping défini par "Défaut" ont une valeur définie dans les champs "Clé de la source" et la "Description", mais aucune valeur dans les champs " Clé Shinken" et " Nom de propriété dans l'interface ".

Cela signifie que ces mappings ne seront pas liés à aucune propriété Shinken.
Nous les avons volontairement listés ici pour que vous puissiez les voir, et faire votre propre mapping si vous en avez besoin ( afin de ne pas partir d'une feuille blanche ).

Ces mappings peuvent être surchargés dans l'un des fichiers de mapping utilisateur ( 1 ).

En bas à droite ( 4 ) se trouve le bouton pour afficher l'aide de la page ( Raccourci sur la touche F1 ).

Exemple

Dans les exemples suivants , nous surchargeons les règles de mapping de " config.guestFullName" et " config.guestId " qui ne sont pas liées à une propriété Shinken.

Pour ce faire, il vous suffit de créer, dans l'un des fichiers de mapping utilisateur ( 1 ), une règle possédant la même clé que celle que vous voulez surcharger ( 5 ).

Avant :

Après :