 |
This is a machine translation based on the English version of the article. It might or might not have already been subject to text preparation. If you find errors, please file a GitHub issue that states the paragraph that has to be improved. |
1. Introduction
Checkmk présente une structure très modulaire, et les personnes ayant des connaissances en programmation Python peuvent étendre cette structure à de nombreux endroits. Il est notamment possible d'étendre Checkmk avec les éléments suivants :
Des checks personnalisés et des plugins d'agent, y compris des masques de saisie pour l'environnement de configuration.
Des plugins personnalisés pour l'inventaire matériel/logiciel de Checkmk
Extensions pour l'interface graphique (vues, tableaux de bord, colonnes, icônes, etc.).
Définitions de graphiques ou de Perf-O-Meters
Scripts de gestion des notifications et des gestionnaires d'alertes (également en shell ou dans d'autres langages de script).
Toutes ces extensions peuvent être implémentées en plaçant des fichiers supplémentaires dans le répertoire ~/local au sein du site Checkmk.
Pour gérer ces extensions, les déployer dans des environnements distribués et les partager avec d’autres utilisateurs, Checkmk fournit son propre format de paquet : le pack d'extension Checkmk — en abrégé MKP.
Un MKP peut inclure n’importe quel ensemble d’extensions souhaité — par exemple, un ensemble de plugins de supervision comprenant les pages de manuel associées, les environnements de configuration des valeurs seuils et les définitions de métriques associées. Il peut en outre contenir des paramètres pour la distribution via la boulangerie d’agents. Un MKP possède un nom, un numéro de version et peut être installé ou supprimé d’un simple geste.
 |
Utilisez une instance de test pour créer et personnaliser des MKP, puis copiez-les sur l’instance de production pour la phase de déploiement. Cela vous évitera deux problèmes potentiels majeurs qui surviennent lorsque les fichiers modifiés ne sont pas intégrés aux MKP en temps opportun :
|
1.1. The Checkmk Exchange
Sur le Checkmk Exchange, les programmeurs de plugins peuvent mettre à disposition des paquets pour d’autres utilisateurs de Checkmk et les échanger entre eux. Depuis l’Exchange, vous pouvez télécharger et utiliser des extensions gratuitement. Veuillez noter que les paquets provenant de l’Exchange sont partagés volontairement par d’autres utilisateurs et sont fournis sans aucune garantie.
Des plugins mal programmés peuvent entraîner une augmentation de la charge CPU/système et des besoins en mémoire. De plus, il est possible qu’un MKP ait été développé pour des versions plus anciennes de Checkmk et ne soit donc pas entièrement compatible (par exemple, avec la mise à jour de la version 1.6.0 vers la version 2.0.0, Checkmk est passé de Python 2 à Python 3). Dans les cas extrêmes, il peut y avoir un risque de perte de données. Nous vous recommandons donc vivement, avant d’utiliser des MKP tiers dans un environnement de production, de les installer d’abord sur une instance de test.
1.2. Outils pour les MKP
Il existe deux outils pour la gestion des MKP :
L'instruction «
mkp»Dans le menu de configuration, l'élément « Extension Packages » (éditions commerciales uniquement)
Nous allons maintenant vous présenter ces deux outils de gestion plus en détail. Ils sont compatibles entre eux, ce qui vous permet d'utiliser à la fois l'instruction et l'Extension Packages sans « tout gâcher ».
2. Gestion des paquets d'extension via le menu de configuration
La fonctionnalité permettant de gérer les MKP via l'interface graphique est disponible exclusivement dans les éditions commerciales de Checkmk.
Dans le menu «Setup », vous accédez à la gestion des MKP via «Setup > Maintenance > Extension packages».
Vous pouvez y installer, modifier ou créer des MKP :
|
Les MKP obsolètes ne peuvent être installés que via la ligne de commande. À partir de l’Extension packages, vous ne pouvez installer (activer et mettre en service) que les MKP qui répondent aux exigences de version. Les autres MKP seront activés mais non installés (un message d’erreur correspondant s’affichera). |
2.1. Ajouter un MKP
Un MKP que vous avez téléchargé depuis l'Exchange, par exemple, peut être importé dans Checkmk en cliquant sur le bouton « Upload package » ; il sera alors disponible pour l'installation.
Pour ce faire, le fichier doit se trouver sur la machine sur laquelle votre navigateur web est également en cours d'exécution.
Le nom de fichier du paquet doit inclure l'extension « .mkp ».
Après l'installation, le paquet d'extension est initialement disponible, mais pas actif. Il se trouve sous « All packages (enabled or disabled) » :
2.2. Activation d'un MKP
Ce n’est qu’en cliquant sur l’icône de la prise 
qu’un paquet disponible sera également activé.
Lors de l’activation, les fichiers sont installés dans une hiérarchie de dossiers sous ~/local/.
Le fichier de description du paquet est également placé dans ~/var/check_mk/packages/.
Après l’activation, le paquet apparaîtra également dans la liste des MKP activés et actifs — Enabled (active on this site) :
Procédez maintenant à l’activation des modifications, après quoi toutes les fonctions du paquet seront intégrées au système et prêtes à l’emploi.
2.3. Désactivation et suppression de paquets
La suppression complète d’un paquet s’effectue également en deux étapes.
À l’aide du bouton « 
», vous désactivez d’abord un paquet dans la liste des paquets actifs.
Au cours de cette étape, les fichiers installés sont supprimés, mais le MKP est conservé — cette étape ne fait qu’annuler l’activation.
À l'aide de l'icône « 
» dans la liste de tous les paquets, vous pouvez à nouveau supprimer les paquets installés et inutilisés.
Lors de la suppression, le paquet est supprimé et l'extension est complètement retirée — c'est-à-dire l'inverse de l'ajout d'un paquet.
2.4. MKP dans les environnements distribués
Dans le cas d’une supervision distribuée avec une configuration centrale, il suffit de mettre les paquets à disposition sur l’instance centrale.
Pour chaque instance distante associée à l’instance centrale, vous pouvez ensuite déterminer séparément si les personnalisations doivent être propagées vers cette instance distante.
Il vous suffit d’activer l’option « Replicate extensions ».
Par la suite, les MKP et toutes les autres modifications présentes dans le répertoire ~/local seront également transférées lors d’une synchronisation.
Si vous ne souhaitez pas qu’un transfert particulier ait lieu, il vous suffit de désactiver l’option pour cette instance ou pour toutes les instances.
Important : les personnalisations de la configuration centrale ne seront transférées que si l'option « Enable replication » est définie sur « Push configuration to this site ».
2.5. Un cas particulier : les paquets activés mais inactifs
Une situation particulière se présente lorsque l'on tente d'activer un paquet qui ne correspond pas à la version de Checkmk utilisée. Un tel paquet, qui est activé mais dont l'activation échoue en raison d'une version incompatible de Checkmk, se retrouvera dans la liste « Enabled (inactive on this site) ».
Mais pourquoi installer des paquets qui ne correspondent pas à la version de Checkmk que vous utilisez ? Il existe deux bonnes raisons possibles :
Une mise à jour de la version de Checkmk : Vous avez la possibilité de stocker des paquets pour l’ancienne et la nouvelle version — lors de votre prochaine mise à jour, le paquet le plus récent sera activé automatiquement.
Supervision distribuée : Pour faciliter les mises à jour, la version majeure de Checkmk des instances distantes peut être supérieure d’une version à celle de l’instance centrale. Cependant, cela rendait auparavant difficile la distribution des MKP, car ceux-ci devaient être compatibles avec les deux versions majeures. Grâce à la possibilité de déverrouiller les paquets non compatibles, vous pouvez conserver sur l’instance centrale des paquets qui correspondent à la fois à la version source et à la version cible. La version la plus récente sera alors automatiquement activée lors d’une mise à jour.
D'après les numéros de version indiqués dans la capture d'écran ci-dessus, vous pouvez constater qu'il s'agit d'une instance centrale Checkmk 2.1.0 qui fournit des paquets aux instances distantes ayant déjà été mises à niveau vers 2.2.0.
3. Gestion des paquets d'extension via la ligne de commande
Vous pouvez également effectuer toutes les actions ci-dessus à partir de la ligne de commande.
La commande mkp est utilisée à cette fin.
Si vous l'exécutez sans sous-commande, elle affiche des conseils d'utilisation.
Pour plus de clarté, nous avons réduit ici la sortie, qui compte environ 50 lignes, à moins de la moitié :
Dans les sections suivantes, nous vous présenterons les instructions les plus importantes pour la gestion des MKP. Vous trouverez un tableau de référence des instructions utiles à la fin de cet article.
3.1. Ajouter un MKP
L'ajout d'un paquet s'effectue à l'aide de l'instruction « mkp add ».
Pour ce faire, vous devez bien sûr commencer par transférer le fichier MKP sur le serveur Checkmk (par exemple, avec l'instruction « scp »).
Exécutez ensuite l'instruction suivante :
Vous demandez la liste des paquets disponibles avec mkp list.
Après une installation, le paquet d'extension est initialement disponible, mais pas actif — dans la liste, il aura l'état Disabled :
3.2. Activation d’un MKP
Ce n’est qu’avec la sous-commande enable qu’un paquet disponible sera également activé.
La spécification du numéro de version n’est requise que lors d’un événement où le nom seul ne serait pas unique :
En principe, vous ne pouvez activer que les MKP correspondant à la version de votre installation Checkmk, même en ligne de commande.
Si vous souhaitez contourner les restrictions de version et installer (activer) le MKP dans toutes les conditions, utilisez --force-install.
Ceci concerne principalement les développeurs qui doivent adapter progressivement les paquets aux nouvelles versions de Checkmk dans des environnements distribués.
Une fois activé — que vous utilisiez ou non force-install —, les fichiers sont installés dans une hiérarchie de répertoires sous ~/local/ et le fichier de description du paquet est placé dans ~/var/check_mk/packages/.
Le paquet se retrouve alors dans l'état « Enabled (active on this site) » :
Vous pouvez obtenir des détails sur un paquet individuel à l'aide de mkp show ; son état d'activation actuel n'a pas d'importance :
3.3. Désactivation et suppression de paquets
La désinstallation d'un paquet s'effectue en deux étapes.
Tout d'abord, le paquet est désactivé à l'aide de la commande `mkp disable`.
Cela supprime les fichiers installés, mais conserve le paquet — par exemple, en vue d'une éventuelle réactivation ultérieure.
Là encore, il n'est nécessaire de préciser le numéro de version que si le nom du paquet seul n'est pas unique :
Dans la liste des paquets, vous verrez désormais l'état « Disabled » lorsque vous appellerez à nouveau mkp list :
Seule la commande « mkp remove » supprimera le paquet de manière irréversible :
3.4. Un cas particulier : les paquets activés mais inactifs
Une situation particulière se présente lorsqu'un paquet est installé qui ne correspond pas à la version de Checkmk utilisée :
Vous pouvez activer un tel paquet, mais l'activation échouera en raison de l'incompatibilité de la version de Checkmk, et le paquet passera à l'état « Enabled (inactive on this site) ».
Nous avons expliqué plus haut, dans la section « Configuration » correspondante, les circonstances dans lesquelles il peut être judicieux d’installer des paquets incompatibles, par exemple lors de mises à jour dans des environnements distribués.
Comme pour la procédure de configuration, utilisez « mkp enable packagename version » pour activer un paquet, ou « mkp disable packagename version » pour désactiver une activation existante.
4. MKP pour les développeurs
La plupart d’entre nous qui connaissons ou apprenons la programmation sommes « comme des nains debout sur les épaules de géants pour pouvoir voir plus loin qu’eux » : C’est dans le libre que nous pouvons réellement tirer profit des travaux antérieurs d’autrui. Dans le cas de Checkmk, cela vaut tout particulièrement pour les extensions qui, dans le cadre de la licence GPL, constituent des œuvres dérivées de Checkmk lui-même, lequel est lui-même soumis à la licence GPL (version 2.0). Concrètement, cela signifie que vous pouvez personnaliser à votre guise (ou simplement en fonction de vos besoins actuels) les paquets téléchargés depuis Checkmk Exchange.
Dans les sections suivantes, nous vous présentons — depuis le reconditionnement avec des modifications mineures, en passant par la résolution d’un paquet existant (exemple), jusqu’à la compilation de fichiers non conditionnés — toutes les étapes pertinentes présentées dans l’ordre typique dans lequel elles sont effectuées.
Si vous programmez ou modifiez vos propres plugins pour Checkmk, consultez les articles sur les interfaces de programmation existantes et l’intégration dans la boulangerie d’agents.
4.1. Edition des paquets
La correction d’erreurs mineures rend souvent nécessaire l’adaptation d’un paquet existant sans en modifier la structure ou le nom. Dans ce cas, il est conseillé non seulement d’adapter les fichiers existants stockés dans le système de fichiers, mais aussi de mettre à jour au moins le numéro de version du paquet. Si des modifications apportées aux API de Checkmk nécessitent des modifications d’un paquet, ajustez également les numéros de version stockés dans le paquet pour les versions minimale et maximale prises en charge. De plus, lors de l’utilisation de la boulangerie d’agents, la présence de nouveaux MKP déclenche la reconstruction des paquets d’agents.
Dans les éditions commerciales, utilisez l'icône « 
» pour accéder au dialogue des modifications.
Les utilisateurs de Checkmk Community (
) doivent quant à eux suivre les deux étapes suivantes via « resolve » et « recreate ».
4.2. Décompression des paquets
Le menu de configuration
Le décompressage d'un paquet dans l'
« libère » pour ainsi dire les fichiers contenus dans ~/local/ et supprime uniquement la description du paquet.
En conséquence, les fichiers seront décompressés et les extensions resteront actives.
C'est l'inverse de la création d'un paquet à partir de fichiers précédemment décompressés.
En pratique, vous aurez très probablement besoin de décompresser un paquet lorsque vous souhaiterez personnaliser une extension, puis de le recompresser ultérieurement pour y inclure vos modifications. Par exemple, vous pouvez commencer par notre exemple « Hello world ! », qui ne fait rien d’utile en soi, mais peut servir de modèle pour votre premier paquet personnalisé.
La ligne d'instruction
En ligne de commande, vous pouvez publier un paquet à l'aide de l'instruction `mkp release`.
Pour que cela fonctionne, le paquet à décompresser doit avoir le statut « Enabled (active on this site) ».
Les fichiers d'extension proprement dits sont conservés et seule la description du paquet est supprimée :
Le paquet d'origine reste intact et passe à l'état « Enabled (inactive on this site) ». Il peut ainsi servir de sauvegarde au cas où un problème surviendrait lors de la personnalisation. Il suffit alors de supprimer les fichiers « redondants », de réactiver le paquet et de recommencer.
4.3. Recherche de fichiers non packagés
Le menu de configuration
Une fois le travail de programmation ou de personnalisation terminé, il sera nécessaire de retrouver les fichiers existants et ceux qui ont été ajoutés. Comme ces fichiers n'appartiennent actuellement à aucun paquet, ils sont répertoriés dans la liste des fichiers de la Configuration sous « Unpackaged files » :
La ligne d'instruction
L'équivalent en ligne de commande est « mkp find » :
Supprimez les fichiers inutiles ou notez ceux qui ne doivent pas être inclus dans le nouveau paquet. À l'étape suivante, les fichiers décompressés seront (à nouveau) regroupés dans un paquet.
4.4. Création de paquets
Le menu de configuration
Le bouton « 
» (Create package) dans l'aperçu des fichiers non packagés vous amène au dialogue permettant de créer un nouveau paquet :
Outre les détails évidents, il est important que vous sélectionniez au moins un fichier à inclure dans le paquet.
La création d’un paquet génère également une description du paquet sous ~/var/check_mk/packages/,
qui contient des informations générales ainsi que la liste des fichiers inclus.
La version maximale de Checkmk prise en charge est bien sûr difficile à prévoir sans boule de cristal.
|
Les extensions qui utilisent les nouvelles API introduites dans Checkmk 2.3.0 sont à l'épreuve du temps et fonctionneront également jusqu'à Checkmk 2.5.0 sans aucun ajustement. Vous pouvez saisir 2.5.99 pour Valid until Checkmk version comme version maximale de Checkmk prise en charge dans ce cas. Aucune déclaration ne peut être faite concernant l'avenir au-delà de cette date au moment de la révision de cet article. |
Vous pouvez désormais télécharger ce nouveau paquet sous forme de fichier MKP via la liste des paquets à l’aide de l’icône « 
» — par exemple pour le transférer vers un autre système ou le mettre en ligne sur Exchange.
La ligne d'instruction
La procédure de création de MKP en ligne de commande est analogue à celle du menu de configuration.
Commencez par utiliser « mkp template » pour créer une configuration de paquet qui (pour l’instant) contient tous ces fichiers.
Spécifiez le nom souhaité pour le nouveau paquet en tant que paramètre :
Vous pouvez désormais éditer les propriétés du paquet à l'aide d'un éditeur de texte :
{'author': 'Add your name here',
'description': 'Please add a description here',
'download_url': 'https://example.com/hello_world_ng/',
'files': {'agents': ['plugins/hello_world', 'windows/plugins/hello_world.cmd'],
'cmk_addons_plugins': ['hello_world/agent_based/hello_world.py',
'hello_world/checkman/hello_world',
'hello_world/graphing/helloworld_perfometer_graphing.py',
'hello_world/rulesets/ruleset_hello_world.py',
'hello_world/rulesets/ruleset_hello_world_bakery.py'],
'lib': ['python3/cmk/base/cee/plugins/bakery/hello_world.py']},
'name': 'hello_world_ng',
'title': 'Title of hello_world_ng',
'version': '1.0.0',
'version.min_required': '2.3.0p27',
'version.packaged': 'cmk-mkp-tool 0.2.0',
'version.usable_until': None}Modifiez ce fichier selon vos besoins.
Veillez à respecter la syntaxe Python : les chaînes Unicode (textes contenant des caractères non ASCII tels que des trémas) doivent être préfixées d'un petit u, par exemple.
Sous l'entrée « files », vous pouvez supprimer les fichiers qui ne doivent pas être inclus dans le paquet.
À l'adresse « version.min_required », indiquez la version minimale de Checkmk requise pour pouvoir utiliser le paquet.
Une fois cette opération terminée, vous pouvez créer un fichier MKP à l'aide de la commande mkp package :
Les paquets sont stockés sous ~/var/check_mk/packages_local :
5. Le format de paquet MKP
Vous souhaiterez peut-être programmer et créer de nouveaux paquets d'extension sur une machine de développement, puis transférer le paquet fini vers le serveur Checkmk pour le tester.
Cela est assez simple à réaliser, car le format MKP est simplement un fichier « .tar.gz », qui contient à son tour des fichiers « .tar » et des fichiers de manifeste.
L'examen de l'hello_world-0.2.5.mkp téléchargé révèle le premier niveau de sa structure :
Décompressez le paquet dans un répertoire temporaire, où vous pourrez consulter le contenu des archives tar incluses. Les chemins d'accès aux fichiers sont relatifs au répertoire contenant leurs composants respectifs :
Et qu'en est-il des deux fichiers de manifeste info et info.json ?
Vous avez déjà vu le fichier info et ses champs au format Python Dict ci-dessus.
L'équivalent JSON info.json contient exactement les mêmes champs et valeurs, mais a été sérialisé au format JSON.
Si vous souhaitez créer le paquet dans le cadre d'un script, vous devez importer le fichier Python dict info et générer le fichier JSON info.json à partir de celui-ci avant de procéder à l'empaquetage.
Lorsque vous reconditionnez les archives, veillez à ne pas inclure de chemins d'accès à des fichiers qui ne font pas partie de la hiérarchie de dossiers sous ~/local.
Le niveau supérieur ne doit contenir que les manifestes et les fichiers tar.
6. Référence des instructions
6.1. Gestion
| Sous-commande | Paramètre | Fonction |
|---|---|---|
|
Nom du fichier du paquet à ajouter |
Rend un paquet disponible, mais ne l'active pas encore. |
|
Nom du paquet (et numéro de version, le cas échéant) |
Active un paquet pour une utilisation locale ou pour une distribution vers des instances distantes, en fonction de la compatibilité des versions. |
|
Nom du paquet (et numéro de version, le cas échéant) |
Active un paquet même en l'absence de compatibilité de version. |
|
Nom du paquet et numéro de version |
Désactive un paquet, qui reste disponible dans le système de fichiers. |
|
Nom du paquet et numéro de version |
Supprime complètement un paquet précédemment désactivé. |
|
Nom du fichier du paquet à ajouter |
Cette sous-commande est obsolète et sera bientôt supprimée ! |
|
aucun |
Fait une liste de tous les paquets disponibles et de leur état d'activation. |
|
Nom du fichier du paquet à inspecter |
Affiche des informations sur un MKP désinstallé. |
|
Nom du paquet (et numéro de version, le cas échéant) |
Affiche des informations sur un MKP disponible. |
|
aucun |
Affiche des informations sur tous les MKP disponibles. |
|
Nom du paquet (et numéro de version, le cas échéant) |
Fait une liste de tous les fichiers appartenant à un paquet. |
6.2. Développement
| Sous-commande | Paramètre | Fonction |
|---|---|---|
|
Nom du paquet |
Résout un paquet actif. |
|
aucun |
Fait une liste de tous les fichiers n'appartenant à aucun paquet. |
|
Nom du nouveau paquet à créer |
Crée un fichier manifeste qui servira de base à un nouveau paquet. |
|
Chemin d'accès au fichier manifeste |
Crée un fichier MKP à partir du contenu d'un fichier manifeste. |
6.3. Mises à jour
| Sous-commande | Paramètre | Fonction |
|---|---|---|
|
aucun |
Désactive les paquets qui ne correspondent plus à la version de Checkmk après une mise à jour. |
|
aucun |
Active les paquets correspondant à la version de Checkmk après une mise à jour. |