Page History

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.

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"

Définition de l'utilisation de VALUES

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

• 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=>)

Prenons par exemple une VM possédant les tags suivants :

Et le mapping suivant :

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

Nous obtiendrons donc le résultat suivant :

La data _TRANSFORM_OPERATION contiendra donc le valeur suivantes :

• ['Prod_bdx', 'Preprod_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 :

Et l'on veut modifier chacun des tags 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 :

1. CentOS →  TRANSFORM(CentOS=>OS_CentOS)
2. Alma → TRANSFORM(Alma=>OS_Alma)
3. 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 :

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.

{
  "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 :

Et que l'on veuille associer le nom de la machine à chaque OS, on peut utiliser la règle suivante 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_"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 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 "

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

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

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 :