Checkmk
DeutschEnglish
master2.3.0
to checkmk.com
Important

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

CEE Dans les éditions commerciales, vous pouvez utiliser l'API Bakery pour écrire vos propres plug-ins Bakery, qui intègrent des fonctions dans les paquets d'agent provenant de l'Agent Bakery. Dans la plupart des cas, ces fonctions sont des plug-ins d'agent, c'est-à-dire des scripts supplémentaires destinés à être exécutés par l'agent Checkmk, ainsi que les fichiers de configuration de ces plug-ins. Cependant, ils peuvent également affecter les fonctions du gestionnaire de paquets s’ils peuvent être mappés via l’inclusion de fichiers, l’exécution de scriptlets de paquets (pour les formats de paquets RPM, DEB et Solaris PKG), ou s’ils définissent des entrées de configuration spécifiques pour l’agent Windows (en YAML). Tous ces « artefacts » peuvent être décrits dans l’API Bakery à l’aide d’une syntaxe uniforme.

Par exemple, voici un scénario d'application concret : Vous avez lu l'introduction au développement d'extensions pour Checkmk et, inspiré par celle-ci, vous avez écrit votre propre plug-in de vérification basé sur un agent avec son plug-in d'agent associé. Vous avez ensuite combiné ces deux éléments en un seul paquet d'extension Checkmk (MKP).

Vous souhaitez désormais rendre le plug-in d’agent configurable (par exemple, permettre son exécution uniquement par certains utilisateurs ou sur certains hôtes) et effectuer des actions supplémentaires lors de l’installation ou de la désinstallation du paquet d’agent. Pour ce faire, vous pouvez utiliser l’API Bakery — comme aide au packaging et à la distribution, comme nous allons le montrer dans cet article à l’aide d’un scénario type. Cela crée deux nouveaux fichiers, qui peuvent ensuite être regroupés avec les fichiers du plug-in existant pour créer un nouveau MKP. Vous trouverez également un exemple détaillé et commenté de cette procédure sur Checkmk Exchange : le MKP « Hello world ! » (décompressé sur GitHub), qui s’inspire étroitement du scénario présenté dans cet article.

Notez que l’API Bakery ne fournit pas de fonctions permettant de configurer le plug-in Bakery, c’est-à-dire de créer l’ensemble de règles associé, ni pour le contenu des fichiers fournis avec le plug-in, par exemple les plug-ins d’agent.

Tip

Même si l'Agent Bakery n'est inclus que dans les éditions commerciales, l'API Bakery existe dans toutes les éditions depuis la version Checkmk 2.3.0. Cela permet aux utilisateurs de Checkmk Community de créer des paquets d'extension pouvant être installés sur toutes les éditions. Si des paquets créés avec l'API Bakery sont installés sur une instance Checkmk Community, les fonctionnalités supplémentaires sont simplement ignorées.

2. Documentation et gestion des versions de l'API

Le logiciel et la documentation de l'API Bakery proviennent de la même source. Cela garantit que la documentation de l'API correspond toujours au logiciel et décrit exactement ce que l'API peut faire, et il n'est donc pas nécessaire de décrire la partie de référence des fonctions, classes, paramètres, etc. disponibles dans le Guide de l'utilisateur Checkmk. Vous pouvez donc trouver la documentation de l'API directement sur votre site Checkmk. Si vous ne disposez pas actuellement d'un site Checkmk en service, vous pouvez consulter une copie de la documentation de l'API Bakery à l'adresse docs.checkmk.com/plugin-api.

2.1. Gestion des versions

L'API et sa documentation sont versionnées à l'aide d'un système de numérotation à deux niveaux basé sur les principes fondamentaux de la spécification Semantic Versioning 2.x, au format X.Y, où X correspond à une version majeure et Y à une version mineure. Une nouvelle version mineure contient de nouvelles fonctionnalités rétrocompatibles. Une nouvelle version majeure, en revanche, peut contenir des modifications rendant l'API incompatible avec la version majeure précédente.

2.2. Historique des versions et perspectives

Chaque plug-in déclare explicitement la version de l’API sur laquelle il s’appuie lorsqu’il accède à l’API. À partir de Checkmk 2.0.0, la version 1 est la version actuelle de l’API Bakery, qui est décrite dans cet article.

Checkmk 2.5.0 introduit la version 2 de l'API Bakery, initialement avec le suffixe « unstable ». Par conséquent, les versions 1 et 2 peuvent encore être utilisées en parallèle dans 2.5.0. Cela signifie que les plug-ins créés conformément à cet article fonctionneront encore au moins dans Checkmk 2.5.0, et très probablement au-delà également.

Tip

Étant donné que certains chemins d’importation pour les API dans les éditions commerciales ont été déplacés dans Checkmk 2.5.0, vous devrez peut-être apporter des modifications à vos plug-ins. C’est le cas si, contrairement à nos recommandations, vous utilisez des importations absolues au lieu de relatives. Remplacez-les par des importations relatives avant de tester vos plug-ins Bakery avec Checkmk 2.5.0.

L'API Rulesets utilisée pour la configuration des plug-ins Bakery dans l'interface graphique de Checkmk suit son propre historique de versions. Pour cette partie de vos paquets d'extension, veuillez vous reporter à notre article sur le développement de plug-ins de contrôle basés sur des agents.

3. Directives relatives aux tests

Si vous développez des plug-ins Bakery, vous souhaiterez les tester régulièrement. Pour que les modifications soient disponibles dans Checkmk, deux étapes sont nécessaires.

Tout d'abord, utilisez la commande « cmk-validate-plugins » pour vous assurer que tous les plug-ins sont syntaxiquement corrects et peuvent être chargés par Checkmk :

OMD[mysite]:~$ cmk-validate-plugins
Agent based plugins loading succeeded, Active checks loading succeeded, Special
agents loading succeeded, Rule specs loading succeeded, Rule specs forms
creation succeeded, Referenced rule specs validation succeeded, Loaded rule
specs usage succeeded
Copier la ou les commandes dans le presse-papiers
Commande(s) copiée(s) avec succès dans le presse-papiers !
L'accès en écriture au presse-papiers a été refusé !

Redémarrez ensuite votre site :

OMD[mysite]:~$ omd restart
Copier la ou les commandes dans le presse-papiers
Commande(s) copiée(s) avec succès dans le presse-papiers !
L'accès en écriture au presse-papiers a été refusé !

Dans le cas des plug-ins Bakery, Checkmk reconnaît désormais les nouveaux fichiers, mais ne peut pas déterminer les exigences de compilation tant que les numéros de version MKP correspondants n'ont pas été mis à jour. Comme il peut être très fastidieux d'incrémenter constamment les numéros de version lors de la programmation d'un plug-in Bakery, nous vous recommandons de passer à la ligne de commande et d'y utiliser la commande « cmk ». L'option « -f » force la compilation de l'agent pour myserver123 :

OMD[mysite]:~$ cmk -fAv myserver123
Baking packages for targets myserver123:
...
Baking...linux_deb:baking...linux_rpm:baking...solaris_pkg:baking...
windows_msi:baking...linux_tgz:baking...solaris_tgz:baking...aix_tgz:baking
...
Copier la ou les commandes dans le presse-papiers
Commande(s) copiée(s) avec succès dans le presse-papiers !
L'accès en écriture au presse-papiers a été refusé !

Vous pouvez désormais copier l'agent nouvellement créé sur un hôte et l'y installer pour tester les extensions que vous avez ajoutées.

4. Utilisation de l'API

4.1. Exemple de scénario

Nous allons vous présenter l'utilisation de l'API à l'aide du scénario suivant :

  • Un plug-in nommé « hello_world » est fourni pour l’agent Checkmk.

  • Le plug-in d’agent existe en trois variantes — pour Linux, Solaris et Windows — et doit également être inclus dans les paquets d’agent pour ces trois systèmes d’exploitation. Les fichiers correspondants sont également disponibles et s’appellenthello_world (pour Linux),hello_world.solaris.ksh (pour Solaris) ethello_world.cmd (pour Windows).
    Les scripts Python, shell et CMD ne sont que des exemples. Un plug-in d’agent peut être n’importe quel fichier exécutable sur le système cible.
    Dans ce contexte, le contenu réel des fichiers ne nous intéresse pas. La fonction des plug-ins d'agent ne relève pas de l'API Bakery. Vous pouvez en savoir plus à ce sujet dans l'introduction au développement de vos propres plug-ins de vérification basés sur des agents .

  • Il devrait être possible de configurer si la sortie du plug-in doit être mise en cache, c'est-à-dire que, dans ce cas, le plug-in ne sera réexécuté par l'agent qu'une fois le délai configuré (intervalle d'exécution) écoulé.

  • Le plug-in doit être configuré dans le menu Configuration via les paramètres Agent Bakery à l'aide des variablesuser etcontent . Le plug-in Linux lit la configuration à partir du fichier de configurationhello_world.json , et le plug-in Solaris la lit à partir du fichierhello_world.cfg . Le plug-in Windows lit les entréeshello_world.user ethello_world.content à partir du fichier de configuration YAML de l'agent Windows.
    Dans chaque cas, l'accès à ces ressources doit être implémenté dans le plug-in de l'agent et n'est pas géré par l'API Bakery.

  • Sous Linux et Solaris, il existe un programme supplémentaire, some_binary, qui doit être inclus. Il s'agit, par exemple, d'un petit script shell permettant de démarrer un plug-in à l'aide d'une commande, indépendamment de l'agent Checkmk.

  • Sous Linux et Solaris, après l'installation de l'agent, il convient d'indiquer dans le syslog, via une routine du gestionnaire de paquets, que hello_world a été installé. De même, après la désinstallation de l'agent, il convient d'indiquer dans le syslog que hello_world a été désinstallé.
    Sous Linux, les scripts postinst et prerm sont courants : dans le script postinst, vous créez par exemple un cache et démarrez un démon ; dans le script prerm, vous pouvez ensuite arrêter le démon et vider le cache. Pour plus d'informations sur l'utilisation de maintainer scripts, consultez la documentation Debian.

4.2. Création d'un ensemble de règles

Pour un plug-in Bakery, il doit exister un ensemble de règles pour la configuration, grâce auquel le plug-in peut être configuré via l'interface graphique. Dans le cas le plus simple, l'ensemble de règles se contente d'activer un plug-in en l'attribuant à certains hôtes. La création d'un ensemble de règles ne fait pas partie de l'API Bakery. Vous trouverez une introduction à ce sujet dans l'article « Développer vos propres plug-ins de vérification basés sur des agents ». Les conventions de chemin d'accès pour le stockage des ensembles de règles y sont également expliquées.

Tip

Si vous souhaitez porter les ensembles de règles pris en charge jusqu’à la version Checkmk 2.3.0 vers les nouvelles interfaces de programmation, ouvrez cet article du Guide de l’utilisateur pour la version 2.2.0 dans un nouvel onglet ou une nouvelle fenêtre. Comparez-le côte à côte avec la section correspondante de cet article. La configuration effectuée est si similaire que la comparaison peut facilement servir d’aide au portage.

Un ensemble de règles minimal

Un exemple d’un tel ensemble de règles minimal, qui active uniquement la distribution d’un plug-in, pourrait se présenter comme suit. Les classes importées ici sont plus complètes que nécessaire afin de couvrir également l’exemple étendu. La différence la plus notable par rapport à l’ensemble de règles pour les plug-ins de vérification basés sur un agent est l’utilisation de la classe AgentConfig au lieu de CheckParameters.

~/local/lib/python3/cmk_addons/plugins/hello_world/rulesets/ruleset_hello_world_bakery.py
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# Shebang only needed for editor!

from cmk.rulesets.v1 import Label, Title, Help
from cmk.rulesets.v1.form_specs import (
    BooleanChoice,
    DefaultValue,
    DictElement,
    Dictionary,
    String,
    TimeSpan,
    TimeMagnitude
)
from cmk.rulesets.v1.rule_specs import AgentConfig, HostCondition, Topic

def _parameter_form_bakery():
    return Dictionary(
        elements = {}
    )

rule_spec_hello_world_bakery = AgentConfig(
    name = "hello_world",
    title = Title("Hello bakery!"),
    topic = Topic.GENERAL,
    parameter_form = _parameter_form_bakery,
)
Copier le contenu du fichier dans le presse-papiers
Le contenu du fichier a été copié avec succès dans le presse-papiers !
L'accès en écriture au presse-papiers a été refusé !

Un ensemble de règles étendu

Cependant, dans le scénario d'exemple, nous avons spécifié qu'un intervalle d'exécution devait être choisi et que les deux variables user et content devaient être définies. Ces variables sont définies comme clés dans l'Dictionary, qui est renvoyé par la fonction spécifiée comme parameter_form.

~/local/lib/python3/cmk_addons/plugins/hello_world/rulesets/ruleset_hello_world_bakery.py
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# Shebang only needed for editor!

from cmk.rulesets.v1 import Label, Title, Help
from cmk.rulesets.v1.form_specs import (
    BooleanChoice,
    DefaultValue,
    DictElement,
    Dictionary,
    String,
    TimeSpan,
    TimeMagnitude
)
from cmk.rulesets.v1.rule_specs import AgentConfig, HostCondition, Topic

def _parameter_form_bakery():
    return Dictionary(
        elements = {
            "user": DictElement(
                parameter_form = String(
                    title = Title("User for example plugin"),
                )
            ),
            "content": DictElement(
                parameter_form = String(
                    title = Title("The actual content"),
                )
            ),
            "interval": DictElement(
                parameter_form = TimeSpan(
                    title = Title("Run asynchronously"),
                    label = Label("Interval for collecting data"),
                    displayed_magnitudes = [TimeMagnitude.SECOND, TimeMagnitude.MINUTE],
                    prefill = DefaultValue(300.0),
                )
            )
        }
    )

rule_spec_hello_world_bakery = AgentConfig(
    name = "hello_world",
    title = Title("Hello bakery!"),
    topic = Topic.GENERAL,
    parameter_form = _parameter_form_bakery,
)
Copier le contenu du fichier dans le presse-papiers
Le contenu du fichier a été copié avec succès dans le presse-papiers !
L'accès en écriture au presse-papiers a été refusé !

Après avoir enregistré l'ensemble de règles, vérifiez que tous les plug-ins sont valides :

OMD[mysite]:~$ cmk-validate-plugins
Agent based plugins loading succeeded, Active checks loading succeeded, Special
agents loading succeeded, Rule specs loading succeeded, Rule specs forms
creation succeeded, Referenced rule specs validation succeeded, Loaded rule
specs usage succeeded
Copier la ou les commandes dans le presse-papiers
La ou les commandes ont été copiées avec succès dans le presse-papiers !
L'accès en écriture au presse-papiers a été refusé !

Redémarrez ensuite votre site :

OMD[mysite]:~$ omd restart
Copier la ou les commandes dans le presse-papiers
Commande(s) copiée(s) avec succès dans le presse-papiers !
L'accès en écriture au presse-papiers a été refusé !

L'ensemble de règles sera désormais visible dans l'interface Checkmk. L'interface graphique résultant de cet ensemble de règles est illustrée dans la capture d'écran suivante :

GUI for the rule set used to configure the plug-in.

4.3. Création d'un fichier de plug-in

Le fichier du plug-in « hello_world.py » est stocké dans la partie locale de la structure de répertoires du site, à l'emplacement ~/local/lib/check_mk/base/cee/plugins/bakery/s.

Un plug-in Bakery est créé sous la forme d'un fichier importé en tant que module Python 3. Par conséquent, conformément à la convention Checkmk, les fichiers de plug-in commencent également par les lignes suivantes :

~/local/lib/check_mk/base/cee/plugins/bakery/hello_world.py
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
Copier le contenu du fichier dans le presse-papiers
Le contenu du fichier a été copié avec succès dans le presse-papiers !
L'accès en écriture au presse-papiers a été refusé !

Comme il s'agit d'un module, toutes les classes et fonctions requises doivent être importées au début.

4.4. Accès à l'API

Tous les objets de l'API Bakery sont disponibles sous cmk.base.cee.plugins.bakery.bakery_api.vX, où X désigne le numéro de version de l'API, par exemple 1. Étant donné que le fichier du plug-in se trouve lui-même dans l'espace de noms cmk.base.cee.plugins.bakery, une importation relative à partir de .bakery_api.v1 fonctionnera également :

~/local/lib/check_mk/base/cee/plugins/bakery/hello_world.py
from .bakery_api.v1 import (
    OS,
    DebStep,
    RpmStep,
    SolStep,
    Plugin,
    PluginConfig,
    SystemBinary,
    Scriptlet,
    WindowsConfigEntry,
    register,
    FileGenerator,
    ScriptletGenerator,
    WindowsConfigGenerator,
    quote_shell_string,
)
Copier le contenu du fichier dans le presse-papiers
Le contenu du fichier a été copié avec succès dans le presse-papiers !
L'accès en écriture au presse-papiers a été refusé !

Dans l'exemple ci-dessus, seuls les noms nécessaires au scénario de l'exemple sont importés.

4.5. Les objets disponibles dans l'API

Les noms disponibles dans l'API Bakery sont décrits en détail dans la documentation de l'API. Dans ce chapitre, les objets sont néanmoins brièvement présentés, car cela permet de mieux comprendre la mise en œuvre du scénario d'exemple.

Identificateurs / Énumérations

Pour la spécification des différents artefacts de plug-in, des énumérations (Enum) sont disponibles, qui peuvent être utilisées pour spécifier diverses propriétés, généralement sous la forme d'un argument :

  • OS - Le système d'exploitation dans le contexte de l'API Bakery.

  • DebStep - Une étape de transaction pour un « script de maintenance » DEB

  • RpmStep - Une étape de transaction pour un « scriptlet » RPM.

  • SolStep - Une étape de transaction pour un « script d'installation » PKG Solaris.

Artefacts

Les fichiers et leur contenu, qui constituent les composants réels d'un plug-in, sont appelés « artefacts ». Ils sont décrits à l'aide de classes appropriées, qui peuvent être classées dans les catégories suivantes :

  • Fichiers (Plugin, SystemBinary, PluginConfig, SystemConfig) - Chaque fichier à fournir à l’agent Checkmk est décrit par un objet. Le type de fichier est défini par la classe. Un objet distinct doit être défini pour chaque système d’exploitation sur lequel le fichier doit être déployé.

  • Scriptlets (Scriptlet) - Un « script de maintenance » DEB, un « scriptlet » RPM ou un « script d'installation » Solaris PKG à exécuter lors de l'installation, de la désinstallation ou de la mise à jour du paquet de l'agent à l'étape de transaction spécifiée (par exemple preinstall, postremove).

  • Entrées de configuration Windows (WindowsConfigEntry, WindowsConfigItems, WindowsGlobalConfigEntry, WindowsSystemConfigEntry) - Les entrées du fichier de configuration YAML pour l'agent Windows sont également décrites à l'aide de classes appropriées.

Ces artefacts sont chacun décrits dans des fonctions de rappel correspondant à leur catégorie. Les fonctions individuelles sont transmises à la fonction register avec les arguments files_function, scriptlets_function, windows_config_function. Il s'agit de fonctions génératrices qui renvoient les artefacts individuels spécifiés. L'évaluation est effectuée par Agent Bakery.

Les fonctions reçoivent divers paramètres en tant qu’arguments qui peuvent être évalués afin de construire et de déterminer les artefacts renvoyés. Ces paramètres sont, d’une part, la configuration de l’interface graphique de l’agent concerné qui doit être « cuit » (conf) et, d’autre part, le hachage de la configuration actuelle de l’agent et des fichiers de plug-ins (aghash).

La fonction d'enregistrement

L'enregistrement s'effectue à l'aide de la fonction register, qui est appelée lors de l'importation du plug-in Bakery en tant que module.

La fonction reçoit les composants individuels du plug-in Bakery en tant qu’arguments : le nom du plug-in (name) et ses fonctions (files_function, scriptlets_function, windows_config_function), chacune renvoyant une catégorie d’artefact.

Annotations de type

Les noms des annotations de type (FileGenerator, ScriptletGenerator, WindowsConfigGenerator, WindowsConfigContent) peuvent être utilisés de manière facultative pour identifier le type de la fonction spécifiée, par exemple comme ceci :

def get_files(conf: dict) -> FileGenerator:
    yield Plugin(...)
    yield PluginConfig(...)

def get_scriptlets(conf: dict) -> ScriptletGenerator:
    yield Scriptlet(...)

def get_windows_config(conf: dict) -> WindowsConfigGenerator:
    content: WindowsConfigContent = conf["some_entry"]
    yield WindowsGlobalConfigEntry(name="some_name",content=content)
Copier le contenu du fichier dans le presse-papiers
Contenu du fichier copié avec succès dans le presse-papiers !
L'accès en écriture au presse-papiers a été refusé !

Fonctions d'aide

Les fonctions d'aide suivantes peuvent être utilisées :

  • quote_shell_string - Cette fonction permet de convertir une expression sous forme de chaîne de caractères afin qu'elle soit correctement reconnue comme une expression par le shell dans le fichier résultant — sans avoir à masquer manuellement les guillemets dans le code Python.

  • password_store - Ce module permet d'accéder aux mots de passe stockés dans le magasin de mots de passe Checkmk.

4.6. Enregistrement

L'enregistrement du plug-in auprès de Checkmk, avec un nom de plug-in et ses fonctions, s'effectue à l'aide de la fonction `register.bakery_plugin` :

~/local/lib/check_mk/base/cee/plugins/bakery/hello_world.py
register.bakery_plugin(
    name = "hello_world",
    files_function = get_hello_world_plugin_files,
    scriptlets_function = get_hello_world_scriptlets,
    windows_config_function = get_hello_world_windows_config,
)
Copier le contenu du fichier dans le presse-papiers
Contenu du fichier copié avec succès dans le presse-papiers !
L'accès en écriture au presse-papiers a été refusé !

Les fonctions get_hello_world_windows_config, get_hello_world_scriptlets et get_hello_world_plugin_files spécifiées ici sont expliquées plus en détail dans les chapitres suivants.

4.7. Configuration de l'agent Windows

Dans notre exemple, l'intervalle d'exécution doit être défini, et la configuration du plug-in doit pouvoir s'effectuer via deux variables. Veillez à définir les clés et les types de données tels qu'ils sont définis dans le jeu de règles créé ci-dessus.

~/local/lib/check_mk/base/cee/plugins/bakery/hello_world.py
class HelloWorldConfig(TypedDict, total=False):
    interval: float
    user: str
    content: str

def get_hello_world_windows_config(conf: HelloWorldConfig) -> WindowsConfigGenerator:
    yield WindowsConfigEntry(path=["hello_world", "user"], content=conf["user"])
    yield WindowsConfigEntry(path=["hello_world", "content"], content=conf["content"])
Copier le contenu du fichier dans le presse-papiers
Contenu du fichier copié avec succès dans le presse-papiers !
L'accès en écriture au presse-papiers a été refusé !

Dans la fonction get_hello_world_windows_config, nous utilisons l'argument conf pour accéder à la configuration définie via l'ensemble de règles dans l'interface graphique de configuration : L'intervalle de temps pour la réexécution sur la sortie mise en cache (interval) et les deux variables pouvant être utilisées pour configurer le plug-in (user, content). Nous partons ici du principe que la configuration de l'ensemble de règles est fournie sous la forme d'un dict. À l'aide de la méthode TypedDict de la classe HelloWorldConfig, nous pouvons mettre en place un accès standardisé à celle-ci.

Ensuite, la méthode WindowsConfigEntry est utilisée pour spécifier les entrées dans le fichier de configuration YAML de l'agent Windows, à partir duquel les valeurs de user et content sont lues.

4.8. Script d'installation pour Linux

Sous Linux et Solaris, des messages syslog doivent être enregistrés lors de l'installation et de la désinstallation de l'agent. Nous ne présentons ici qu'une implémentation pour la distribution Debian Linux :

~/local/lib/check_mk/base/cee/plugins/bakery/hello_world.py
def get_hello_world_scriptlets(conf: Any) -> ScriptletGenerator:
    installed_lines = ['logger "Installed hello_world"']
    uninstalled_lines = ['logger "Uninstalled hello_world"']

    yield Scriptlet(step=DebStep.POSTINST, lines=installed_lines)
    yield Scriptlet(step=DebStep.POSTRM, lines=uninstalled_lines)
    # yield Scriptlet(step=RpmStep.POST, lines=installed_lines)
    # yield Scriptlet(step=RpmStep.POSTUN, lines=uninstalled_lines)
    # yield Scriptlet(step=SolStep.POSTINSTALL, lines=installed_lines)
    # yield Scriptlet(step=SolStep.POSTREMOVE, lines=uninstalled_lines)
Copier le contenu du fichier dans le presse-papiers
Contenu du fichier copié avec succès dans le presse-papiers !
L'accès en écriture au presse-papiers a été refusé !

On définit d'abord les commandes pour les messages syslog, puis les scripts d'installation pour Debian (DebStep) qui doivent être exécutés après l'installation (POSTINST) et après la désinstallation (POSTRM). Dans les commentaires ci-dessous, vous trouverez également les lignes correspondantes pour les distributions utilisant RPM et pour Solaris.

Remarque : conformément aux lignes de commande que vous avez incluses, les scripts d'installation sont enrichis de commandes supplémentaires par Checkmk. Par conséquent, pour vous assurer que toutes les commandes des scripts sont exécutées, ne terminez pas votre ensemble de commandes par un exit 0.

4.9. Le plug-in d'agent pour Linux

La configuration du plug-in d'agent pour Linux se présente comme suit. Veillez à convertir l'intervalle transmis en Integer, car le jeu de règles et Bakery utilisent des types de données différents.

~/local/lib/check_mk/base/cee/plugins/bakery/hello_world.py
def get_hello_world_plugin_files(conf: HelloWorldConfig) -> FileGenerator:
    interval = conf.get('interval')

    yield Plugin(
        base_os = OS.LINUX,
        source = Path('hello_world'),
        target = Path('hello_world'),
        interval = int(interval),
    )

    yield PluginConfig(
        base_os = OS.LINUX,
        lines = _get_linux_cfg_lines(conf['user'], conf['content']),
        target = Path('hello_world.json'),
        include_header = False)

    for base_os in [OS.LINUX]:
        yield SystemBinary(
            base_os = base_os,
            source = Path('some_binary'),
        )

def _get_linux_cfg_lines(user: str, content: str) -> List[str]:
    config = json.dumps({'user': user, 'content': content})
    return config.split('\n')
Copier le contenu du fichier dans le presse-papiers
Contenu du fichier copié avec succès dans le presse-papiers !
L'accès en écriture au presse-papiers a été refusé !

Dans la fonction get_hello_world_plugin_files, le fichier Python hello_world est d’abord défini comme un plugin, c’est-à-dire comme un fichier exécutable destiné à être exécuté par l’agent Checkmk en tant que plug-in d’agent. Ensuite, PluginConfig est utilisé pour spécifier le fichier de configuration hello_world.json à générer pour le plug-in d’agent Linux avec les entrées user et content.

La deuxième fonction _get_linux_cfg_lines permet d'écrire ces lignes au format JSON. Ici, le dictionnaire Python conf contient les valeurs définies avec l'ensemble de règles de l'interface graphique de configuration, qui sont ensuite regroupées dans un fichier JSON via un petit détour.

Enfin, le script shell supplémentaire some_binary à fournir doit être placé sous le nom SystemBinary sur le système cible, dans le répertoire des programmes utilisateur (par défaut /usr/bin).

4.10. Le fichier de plug-in pour notre scénario d'exemple

En rassemblant tous les éléments présentés jusqu’à présent — et en les complétant —, un plugin pour notre scénario d’exemple pourrait ressembler à ceci une fois terminé :

~/local/lib/check_mk/base/cee/plugins/bakery/hello_world.py
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# Shebang only needed for editor!

import json
from pathlib import Path
from typing import Iterable, TypedDict, List

from .bakery_api.v1 import (
    OS,
    DebStep,
    RpmStep,
    SolStep,
    Plugin,
    PluginConfig,
    SystemBinary,
    Scriptlet,
    WindowsConfigEntry,
    register,
    FileGenerator,
    ScriptletGenerator,
    WindowsConfigGenerator,
    quote_shell_string,
)

class HelloWorldConfig(TypedDict, total=False):
    interval: float
    user: str
    content: str

def get_hello_world_plugin_files(conf: HelloWorldConfig) -> FileGenerator:
    interval = conf.get('interval')

    yield Plugin(
        base_os = OS.LINUX,
        source = Path('hello_world'),
        target = Path('hello_world'),
        interval = int(interval),
    )
    yield Plugin(
        base_os  =OS.SOLARIS,
        source = Path('hello_world.solaris.ksh'),
        target = Path('hello_world'),
        interval = int(interval),
    )
    yield Plugin(
        base_os = OS.WINDOWS,
        source = Path('hello_world.cmd'),
        target = Path('hello_world.bat'),
        interval = int(interval),
    )

    yield PluginConfig(
        base_os = OS.LINUX,
        lines = _get_linux_cfg_lines(conf['user'], conf['content']),
        target = Path('hello_world.json'),
        include_header = False
    )
    yield PluginConfig(
        base_os = OS.SOLARIS,
        lines = _get_solaris_cfg_lines(conf['user'], conf['content']),
        target = Path('hello_world.cfg'),
        include_header = True
    )

    for base_os in [OS.LINUX, OS.SOLARIS]:
        yield SystemBinary(
            base_os = base_os,
            source = Path('some_binary'),
        )

def _get_linux_cfg_lines(user: str, content: str) -> List[str]:
    config = json.dumps({'user': user, 'content': content})
    return config.split('\n')

def _get_solaris_cfg_lines(user: str, content: str) -> List[str]:
    # To be loaded with 'source' in Solaris shell script
    return [
        f'USER={quote_shell_string(user)}',
        f'CONTENT={quote_shell_string(user)}',
    ]

def get_hello_world_scriptlets(conf: HelloWorldConfig) -> ScriptletGenerator:
    installed_lines = ['logger -p local3.info "Installed hello_world"']
    uninstalled_lines = ['logger -p local3.info "Uninstalled hello_world"']

    yield Scriptlet(step=DebStep.POSTINST, lines=installed_lines)
    yield Scriptlet(step=DebStep.POSTRM, lines=uninstalled_lines)
    yield Scriptlet(step=RpmStep.POST, lines=installed_lines)
    yield Scriptlet(step=RpmStep.POSTUN, lines=uninstalled_lines)
    yield Scriptlet(step=SolStep.POSTINSTALL, lines=installed_lines)
    yield Scriptlet(step=SolStep.POSTREMOVE, lines=uninstalled_lines)

def get_hello_world_windows_config(conf: HelloWorldConfig) -> WindowsConfigGenerator:
    yield WindowsConfigEntry(path=["hello_world", "user"], content=conf["user"])
    yield WindowsConfigEntry(path=["hello_world", "content"], content=conf["content"])

register.bakery_plugin(
    name = "hello_world",
    files_function = get_hello_world_plugin_files,
    scriptlets_function = get_hello_world_scriptlets,
    windows_config_function = get_hello_world_windows_config,
)
Copier le contenu du fichier dans le presse-papiers
Contenu du fichier copié avec succès dans le presse-papiers !
L'accès en écriture au presse-papiers a été refusé !

4.11. Mise à disposition des fichiers

Pour qu’un plug-in Bakery fonctionne correctement, tous les fichiers concernés doivent être placés ou écrits à l’emplacement approprié dans la structure locale du répertoire du site.

Il s'agit d'une part du fichier du plug-in lui-même et, d'autre part, des objets renvoyés par l'files_function. Ces objets décrivent soit des fichiers de configuration créés directement par le plug-in Bakery, soit des fichiers qui doivent être stockés correctement afin de pouvoir être retrouvés lors de la création des paquets d'agent.

Les objets des classes `Plugin` et `SystemBinary` désignent des fichiers existants qui doivent être stockés. Les fichiers décrits comme `PluginConfig` et `SystemConfig` doivent encore être générés en fonction de l’argument `lines` ; il n’est donc pas nécessaire de stocker de fichiers ici.

Enfin, l'ensemble des fichiers comprend également le fichier de règles du plug-in.

Dans le chapitre suivant et dernier, vous trouverez la liste de tous les répertoires.

5. Fichiers et répertoires

Les fichiers nécessaires au déploiement d'un plug-in Bakery doivent être placés dans les répertoires suivants. Comme toujours, toutes les spécifications indiquées ici sont relatives au répertoire du site (par exemple, /omd/sites/mysite).

Chemin d'accès au fichier Description

~/local/lib/check_mk/base/cee/plugins/bakery/

Répertoire du plug-in Bakery (dans notre exemple hello_world.py).

~/local/share/check_mk/agents/plugins/

Répertoire de stockage des plug-ins d'agent de type Unix.

~/local/share/check_mk/agents/windows/plugins/

Répertoire de stockage des plug-ins d'agent Windows.

~/local/share/check_mk/agents/

Répertoire contenant les programmes ou les scripts shell pour les systèmes d'exploitation de type Unix (some_binary dans l'exemple).

~/local/share/check_mk/agents/windows/

Répertoire contenant les programmes ou scripts shell fournis pour Windows.

~/local/lib/python3/cmk_addons/plugins/<family_name>/rulesets/

Répertoire contenant les fichiers de règles permettant de configurer le plug-in d'agent (ruleset_hello_world_bakery.py dans l'exemple) ainsi que le plug-in de vérification associé (par exemple, pour définir les seuils). Choisissez donc des noms significatifs afin de pouvoir distinguer les fichiers les uns des autres. Les noms des fichiers stockés ici doivent commencer par ruleset_, sinon Checkmk les ignorera.
Last modified: Wed, 25 Mar 2026 10:13:52 GMT via commit d7fa87218
Sur cette page