Page History

Concept

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.

Elles peuvent être visualisées depuis l'onglet "Mapping vers les propriétés et les données de Shinken" de l'interface de la source.

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

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

Exemple de mapping dans le fichier "user_mapping_rules_vm.json"

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

Opérateur pour les régles de mapping

Opérateur VALUES pour les listes

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

Pour faire correspondre une valeur de liste dans un champ de Shinken, il est possible d'utiliser l'opérateur : "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 ).

Opérateur TRANSFORM pour les transformations

Grâce à l'opérateur 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, ces dernières sont séparées 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 :

Et le mapping suivant :

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

La data _TRANSFORM_OPERATION contiendra donc la valeur suivante :

• ['Prod_bdx']

Lorsque l'opérateur 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 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"

Opérateur CONCAT pour les concaténations 

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 à l'opérateur : CONCAT.

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

Et les informations doivent être affichées 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", 
   }
}

L'opérateur 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$ - $shinken.ipAddress$)": "_MACHINE_INFOS",
  }
}

et les valeurs :

• "name" valant : "Ubuntu-Preprod"
• "shinken.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"

Opérateur CONCAT_ON_ALL pour les concaténations sur les listes

Comme pour l'opérateur TRANSFORM évoquée plus haut, il est également possible d'appliquer une opération de concaténation sur une liste, à l'aide de l'opérateur CONCAT_ON_ALL.

De la même manière que lorsque l'opération TRANSFORM est appliquée sur une liste, il est possible d'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 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']

"CONCAT($shinken.tags_by_category.ENV>CONCAT_ON_ALL($name$ has tag  $CURRENT$)$)": "_CONCAT_ON_ALL_IN_ANOTHER_RULE"

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"
  }
}

Visualiser la liste des mappings

Pour visualiser la liste des mapping définie pour cette source, il faut se rendre dans l'onglet "Mapping vers les propriétés de Shinken". 

Dans cet onglet, se trouve le chemin des fichiers de définition des règles mapping des utilisateurs pour l'ESXi et les Machines virtuelles du serveur ESXi ( 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, se trouve également 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 ESXi/VM => Le type de mapping ( un mapping spécifique à l'ESXi ou un mapping spécifique aux VMs du serveur ESXi ).
• 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.
• Elles sont volontairement listées ici pour être vus, et faciliter la création de son propre mapping ( 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

Les exemples suivants surchargent 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 suffit de créer, dans l'un des fichiers de mapping utilisateur ( 1 ), une règle possédant la même clé que celle à surcharger ( 5 ).

Avant :

Après :