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

CEE Nelle edizioni commerciali puoi usare l'API Bakery per scrivere i tuoi plug-in Bakery, che includono funzioni nei pacchetti degli agenti provenienti dall'Agent Bakery. Nella maggior parte dei casi, queste funzioni sono plug-in degli agenti, cioè script aggiuntivi da eseguire tramite l'agente Checkmk, e i file di configurazione dei plug-in. Tuttavia, possono anche influire sulle funzioni del gestore di pacchetti se possono essere mappati includendo file, eseguendo scriptlet di pacchetti (per i formati di pacchetto RPM, DEB e Solaris PKG), o se definiscono voci di configurazione specifiche per l'agente Windows (in YAML). Tutti questi "artefatti" possono essere descritti nell'API Bakery utilizzando una sintassi uniforme.

Ad esempio, uno scenario applicativo reale è il seguente: Hai letto l'introduzione allo sviluppo di estensioni per Checkmk e, ispirandoti ad essa, hai scritto il tuo plug-in di controllo basato su agente con il relativo plug-in dell'agente. Hai poi combinato questi due in un unico pacchetto di estensione Checkmk (MKP).

Ora vuoi rendere configurabile il plug-in dell'agente (ad es. consentirne l'esecuzione solo da parte di determinati utenti o su determinati host) ed eseguire inoltre delle azioni durante l'installazione o la disinstallazione del pacchetto dell'agente. Per farlo, puoi utilizzare l'API Bakery — come ausilio per il packaging e la distribuzione, come mostreremo in questo articolo con uno scenario di esempio. Questo crea due nuovi file, che possono poi essere impacchettati insieme ai file del plug-in esistente per creare un nuovo MKP. Puoi anche trovare un esempio ben commentato di questa procedura su Checkmk Exchange: l’MKP Hello world! (disponibile su GitHub), che si basa strettamente sullo scenario di esempio presentato in questo articolo.

Nota che l’API Bakery non fornisce funzioni per configurare il plug-in Bakery, cioè per creare il set di regole associato, né per i contenuti dei file forniti con il plug-in, ad esempio i plug-in degli agenti.

Tip

Anche se l'Agent Bakery è incluso solo nelle edizioni commerciali, l'API Bakery è presente in tutte le edizioni a partire da Checkmk 2.3.0. Questo permette agli utenti di Checkmk Community di creare pacchetti di estensione che possono essere installati su tutte le edizioni. Se i pacchetti creati con l'API Bakery vengono installati su una Checkmk Community, le funzionalità aggiuntive vengono semplicemente ignorate.

2. Documentazione e gestione delle versioni dell'API

Il software e la documentazione dell'API Bakery provengono dalla stessa fonte. Questo garantisce che la documentazione dell'API corrisponda sempre al software e descriva esattamente ciò che l'API è in grado di fare, pertanto non è necessario descrivere la parte di riferimento delle funzioni, classi, parametri ecc. disponibili nella Guida utente di Checkmk. Puoi quindi trovare la documentazione API direttamente nel tuo sito Checkmk. Se al momento non hai un sito Checkmk attivo, puoi visualizzare una copia della documentazione dell'API Bakery all'indirizzo docs.checkmk.com/plugin-api.

2.1. Versioni

L'API e la sua documentazione sono versionate utilizzando un sistema di numerazione a due livelli basato sui principi fondamentali della specifica Semantic Versioning 2.x nel formato X.Y, dove X sta per una versione maggiore e Y per una versione minore. Una nuova versione minore contiene nuove funzionalità retrocompatibili. Una nuova versione maggiore, invece, può contenere modifiche che rendono l'API incompatibile con la versione maggiore precedente.

2.2. Cronologia delle versioni e prospettive

Ogni plug-in dichiara esplicitamente la versione dell'API su cui si basa quando accede all'API. A partire da Checkmk 2.0.0, la versione 1 è la versione attuale dell'API Bakery, descritta in questo articolo.

Checkmk 2.5.0 introduce la versione 2 dell'API Bakery, inizialmente con il suffisso unstable. Pertanto, le versioni 1 e 2 possono ancora essere utilizzate in parallelo in 2.5.0. Ciò significa che i plug-in creati in conformità con questo articolo funzioneranno ancora almeno in Checkmk 2.5.0, e molto probabilmente anche oltre.

Tip

Poiché alcuni percorsi di importazione per le API nelle edizioni commerciali sono stati spostati in Checkmk 2.5.0, potrebbe essere necessario apportare modifiche ai tuoi plug-in. Questo è il caso se, contrariamente alle nostre raccomandazioni, stai utilizzando importazioni assolute invece che relative. Modificale in importazioni relative prima di testare i tuoi plug-in Bakery con Checkmk 2.5.0.

L'API Rulesets utilizzata per la configurazione dei plug-in Bakery nella GUI di Checkmk segue una propria cronologia delle versioni. Per questa parte dei tuoi pacchetti di estensione, consulta il nostro articolo sullo sviluppo di plug-in di controllo basati su agenti.

3. Linee guida per i test

Se stai sviluppando plug-in Bakery, ti consigliamo di testarli regolarmente. Per rendere disponibili le modifiche in Checkmk, sono necessari due passaggi.

Per prima cosa, usa cmk-validate-plugins per assicurarti che tutti i plug-in siano sintatticamente corretti e possano essere caricati da 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
Copia i comandi negli appunti
Comandi copiati con successo negli appunti!
L'accesso in scrittura agli appunti è stato negato!

Quindi riavvia il tuo sito:

OMD[mysite]:~$ omd restart
Copia i comandi negli appunti
Comandi copiati con successo negli appunti!
L'accesso in scrittura agli appunti è stato negato!

Nel caso dei plug-in Bakery, Checkmk ora riconosce i nuovi file, ma non può determinare i requisiti di bake finché i numeri di versione MKP corrispondenti non vengono aggiornati. Dato che può essere molto noioso incrementare costantemente i numeri di versione mentre si programma un plug-in Bakery, ti consigliamo di passare alla riga di comando e di usare lì il comando `cmk`. L'opzione `-f` forza l'agent per myserver123 a essere sottoposto a bake:

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
...
Copia i comandi negli appunti
Comandi copiati con successo negli appunti!
L'accesso in scrittura agli appunti è stato negato!

Ora puoi copiare l'agente appena creato su un host e installarlo lì per testare le estensioni che hai aggiunto.

4. Utilizzo dell'API

4.1. Uno scenario di esempio

Ti mostreremo come usare l'API con il seguente scenario di esempio:

  • Per l'agente Checkmk è disponibile un plug-in chiamato hello_world.

  • Il plug-in dell'agente esiste in tre varianti — per Linux, Solaris e Windows — e deve essere incluso nei pacchetti dell'agente per questi tre sistemi operativi. Sono disponibili anche i file corrispondenti, denominatihello_world (per Linux),hello_world.solaris.ksh (per Solaris) ehello_world.cmd (per Windows).
    Gli script Python, shell e CMD sono solo esempi. Un plug-in dell'agente può essere qualsiasi file eseguibile sul sistema di destinazione.
    In questo contesto non ci interessa il contenuto effettivo dei file. La funzione dei plug-in dell'agente non è oggetto dell'API Bakery. Puoi saperne di più nell'introduzione allo sviluppo dei tuoi plug-in di controllo basati su agente .

  • Dovrebbe essere possibile configurare se l'output del plug-in debba essere memorizzato nella cache, ovvero in questo caso il plug-in verrà rieseguito dall'agente solo una volta trascorso il tempo configurato (intervallo di esecuzione).

  • Il plug-in va configurato nel menu Setup tramite le impostazioni di Agent Bakery con le variabiliuser econtent . Il plug-in per Linux legge la configurazione dal file di configurazionehello_world.json , mentre quello per Solaris la legge dal filehello_world.cfg . Il plug-in per Windows legge le vocihello_world.user ehello_world.content dal file di configurazione YAML nell'agente Windows.
    In ogni caso, l'accesso a queste risorse deve essere implementato nel plug-in dell'agente e non è gestito dall'API Bakery.

  • Per Linux e Solaris c'è un programma aggiuntivo some_binary, che dovrebbe essere incluso. Si tratta, ad esempio, di un piccolo script di shell con cui è possibile avviare un plug-in tramite un comando, indipendentemente dall'agente Checkmk.

  • Su Linux e Solaris, dopo aver installato l'agente, tramite una routine del gestore di pacchetti dovrebbe essere scritto nel syslog che hello_world è stato installato. Dopo aver disinstallato l'agente, analogamente, dovrebbe essere scritto nel syslog che hello_world è stato disinstallato.
    Comuni sotto Linux sono gli script postinst e prerm: nello script postinst crei ad esempio una cache e avvii un demone, nello script prerm puoi poi arrestare nuovamente il demone e cancellare la cache. Per ulteriori informazioni su come utilizzare maintainer scripts, consulta la documentazione di Debian.

4.2. Creazione di un set di regole

Per un plug-in Bakery deve esserci un set di regole per la configurazione, con cui il plug-in può essere configurato tramite la GUI. Nel caso più semplice, il set di regole si limita ad attivare un plug-in assegnandolo a determinati host. La creazione di un set di regole non fa parte dell'API di Bakery. Puoi trovare un'introduzione a questo argomento nell'articolo Sviluppare i propri plug-in di controllo basati su agenti. Lì vengono spiegate anche le convenzioni di percorso per la memorizzazione dei set di regole.

Tip

Se vuoi trasferire i set di regole supportati fino alla versione Checkmk 2.3.0 alle nuove interfacce di programmazione, apri questo articolo nella Guida utente per la versione 2.2.0 in una nuova scheda o finestra. Confrontalo fianco a fianco con la sezione corrispondente in questo articolo. La configurazione è talmente simile che il confronto può facilmente servire come aiuto per il trasferimento.

Un set di regole minimale

Un esempio di un tale set di regole minimale, che attiva solo la distribuzione di un plug-in, potrebbe apparire come segue. Le classi importate qui sono più estese del necessario per coprire anche l'esempio esteso. La differenza più evidente rispetto al set di regole per i plug-in di controllo basati su agente è l'uso della classe AgentConfig invece di 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,
)
Copia il contenuto del file negli appunti
Contenuto del file copiato con successo negli appunti!
L'accesso in scrittura agli appunti è stato negato!

Un set di regole esteso

Tuttavia, nello scenario di esempio, abbiamo specificato che deve essere scelto un intervallo di esecuzione e che devono essere impostate le due variabili user e content. Queste variabili sono definite come chiavi nell'Dictionary, che viene restituito dalla funzione specificata come 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,
)
Copia il contenuto del file negli appunti
Contenuto del file copiato con successo negli appunti!
L'accesso in scrittura agli appunti è stato negato!

Dopo aver salvato il set di regole, verifica che tutti i plug-in siano validi:

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
Copia i comandi negli appunti
Comandi copiati con successo negli appunti!
L'accesso in scrittura agli appunti è stato negato!

Quindi riavvia il tuo sito:

OMD[mysite]:~$ omd restart
Copia i comandi negli appunti
Comandi copiati con successo negli appunti!
L'accesso in scrittura agli appunti è stato negato!

Il set di regole sarà ora visibile nell'interfaccia di Checkmk. La GUI risultante da questo set di regole è mostrata nella seguente schermata:

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

4.3. Creazione di un file plug-in

Il file del plug-in "hello_world.py" è memorizzato nella parte locale della struttura delle directory del sito all'indirizzo ~/local/lib/check_mk/base/cee/plugins/bakery/s.

Un plug-in Bakery viene creato sotto forma di file che viene importato come modulo Python 3. Pertanto, seguendo la convenzione di Checkmk, anche i file dei plug-in iniziano con le seguenti righe:

~/local/lib/check_mk/base/cee/plugins/bakery/hello_world.py
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
Copia il contenuto del file negli appunti
Contenuto del file copiato con successo negli appunti!
L'accesso in scrittura agli appunti è stato negato!

Trattandosi di un modulo, tutte le classi e le funzioni necessarie devono essere importate all'inizio.

4.4. Accesso all'API

Tutti gli oggetti nell'API di Bakery sono disponibili all'indirizzo cmk.base.cee.plugins.bakery.bakery_api.vX, dove X indica il numero di versione dell'API, nell'esempio 1. Dato che il file del plug-in si trova nello spazio dei nomi cmk.base.cee.plugins.bakery, funzionerà anche un'importazione relativa da .bakery_api.v1:

~/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,
)
Copia il contenuto del file negli appunti
Contenuto del file copiato con successo negli appunti!
L'accesso in scrittura agli appunti è stato negato!

Nell'esempio sopra riportato, vengono importati solo i nomi necessari per lo scenario dell'esempio.

4.5. Gli oggetti disponibili nell'API

I nomi disponibili nell'API Bakery sono descritti in dettaglio nella documentazione dell'API. In questo capitolo, gli oggetti vengono comunque presentati brevemente, poiché ciò è utile per comprendere l'implementazione dello scenario di esempio.

Identificatori / Enumerazioni

Per la specifica dei singoli artefatti del plug-in sono disponibili delle enumerazioni (Enum), che possono essere utilizzate per specificare varie proprietà, solitamente sotto forma di argomento:

  • OS - Il sistema operativo nel contesto dell'API Bakery.

  • DebStep - Una fase di transazione per uno "script di manutenzione" DEB

  • RpmStep - Un passo di transazione per uno "scriptlet" RPM.

  • SolStep - Una fase di transazione per uno "script di installazione" PKG di Solaris.

Artefatti

I file e i contenuti dei file che costituiscono i componenti effettivi di un plug-in sono denominati artefatti. Questi sono descritti utilizzando classi appropriate, che possono essere suddivise nelle seguenti categorie:

  • File (Plugin, SystemBinary, PluginConfig, SystemConfig) - Ogni file da fornire all'agente Checkmk è descritto con un oggetto. Il tipo di file è descritto dalla classe. È necessario definire un oggetto separato per ogni sistema operativo su cui il file deve essere distribuito.

  • Scriptlet (Scriptlet) - Uno "script di manutenzione" DEB, uno "scriptlet" RPM o uno "script di installazione" Solaris PKG da eseguire durante l'installazione, la disinstallazione o l'aggiornamento del pacchetto dell'agente nella fase della transazione specificata (ad es. preinstall, postremove).

  • Voci di configurazione di Windows (WindowsConfigEntry, WindowsConfigItems, WindowsGlobalConfigEntry, WindowsSystemConfigEntry) - Anche le voci nel file di configurazione YAML per l'agente Windows sono descritte utilizzando classi appropriate.

Questi artefatti sono descritti nelle funzioni di callback corrispondenti alla loro categoria. Le singole funzioni vengono passate alla funzione register con gli argomenti files_function, scriptlets_function, windows_config_function. Si tratta di funzioni generatrici che restituiscono i singoli artefatti specificati. La valutazione viene eseguita da Agent Bakery.

Le funzioni ricevono come argomenti vari parametri che possono essere valutati per costruire e determinare gli artefatti restituiti. I parametri sono da un lato la configurazione GUI del rispettivo agente da "cuocere" (conf) e dall'altro l'hash della configurazione corrente dell'agente e dei file dei plug-in (aghash).

La funzione di registrazione

La registrazione viene eseguita con la funzione register, che viene chiamata quando si importa il plug-in Bakery come modulo.

La funzione riceve come argomenti i singoli componenti del plug-in Bakery: il nome del plug-in (name) e le sue funzioni (files_function, scriptlets_function, windows_config_function), ognuna delle quali restituisce una categoria di artefatto.

Annotazioni di tipo

I nomi delle annotazioni di tipo (FileGenerator, ScriptletGenerator, WindowsConfigGenerator, WindowsConfigContent) possono essere usati facoltativamente per identificare il tipo della funzione specificata, ad esempio in questo modo:

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)
Copia il contenuto del file negli appunti
Contenuto del file copiato con successo negli appunti!
L'accesso in scrittura agli appunti è stato negato!

Funzioni di supporto

È possibile utilizzare le seguenti funzioni di supporto:

  • quote_shell_string - Questa funzione può essere utilizzata per convertire un'espressione stringa in modo che venga correttamente riconosciuta come espressione dalla shell nel file risultante, senza dover mascherare manualmente le virgolette nel codice Python.

  • password_store - Questo modulo consente l'accesso alle password memorizzate nell'archivio password di Checkmk.

4.6. Registrazione

La registrazione del plug-in in Checkmk con un nome e le sue funzioni si effettua tramite la funzione `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,
)
Copia il contenuto del file negli appunti
Contenuto del file copiato con successo negli appunti!
L'accesso in scrittura agli appunti è stato negato!

Le funzioni get_hello_world_windows_config, get_hello_world_scriptlets e get_hello_world_plugin_files qui specificate sono spiegate più dettagliatamente nei capitoli seguenti.

4.7. Configurazione per l'agente Windows

Nel nostro esempio, è necessario definire l'intervallo di esecuzione e la configurazione del plug-in dovrebbe poter essere effettuata tramite due variabili. Assicurati di definire le chiavi e i tipi di dati come specificato nel set di regole creato in precedenza.

~/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"])
Copia il contenuto del file negli appunti
Contenuto del file copiato con successo negli appunti!
L'accesso in scrittura agli appunti è stato negato!

Nella funzione get_hello_world_windows_config, usiamo l'argomento conf per accedere alla configurazione impostata tramite il set di regole nella GUI di Setup: L'intervallo di tempo per la riesecuzione sull'output memorizzato nella cache (interval) e le due variabili che possono essere utilizzate per configurare il plug-in (user, content). Qui supponiamo che la configurazione del set di regole sia fornita come dict. Utilizzando l'TypedDict della classe HelloWorldConfig possiamo impostare un accesso standardizzato ad esso.

Quindi si usa WindowsConfigEntry per specificare le voci nel file di configurazione YAML dell'agente Windows da cui vengono letti i valori per user e content.

4.8. Script di installazione per Linux

Su Linux e Solaris, durante l'installazione e la disinstallazione dell'agente dovrebbero essere scritti dei messaggi syslog. Qui mostriamo solo un'implementazione della distribuzione 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)
Copia il contenuto del file negli appunti
Contenuto del file copiato con successo negli appunti!
L'accesso in scrittura agli appunti è stato negato!

Per prima cosa vengono definiti i comandi per i messaggi syslog, poi gli script di installazione per Debian (DebStep) che dovrebbero essere eseguiti dopo l'installazione (POSTINST) e dopo la disinstallazione (POSTRM). Nei commenti qui sotto troverai anche le righe corrispondenti per le distribuzioni che usano RPM e per Solaris.

Nota: in base alle righe di comando che hai inserito, gli script di installazione vengono caricati con comandi aggiuntivi da Checkmk. Pertanto, per assicurarti che tutti i comandi negli script vengano eseguiti, non terminare la tua serie di comandi con un exit 0.

4.9. Il plug-in dell'agente per Linux

La configurazione per il plug-in dell'agente Linux è la seguente. Assicurati di convertire l'intervallo passato in Integer poiché il set di regole e bakery utilizzano tipi di dati diversi.

~/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')
Copia il contenuto del file negli appunti
Contenuto del file copiato con successo negli appunti!
L'accesso in scrittura agli appunti è stato negato!

Nella funzione get_hello_world_plugin_files, prima viene definito il file Python hello_world come plugin, cioè come file eseguibile da lanciare dall'agente Checkmk come plug-in dell'agente. Poi si usa PluginConfig per specificare il file di configurazione hello_world.json da generare per il plug-in dell'agente Linux con le voci user e content.

Con la seconda funzione _get_linux_cfg_lines queste righe vengono scritte in formato JSON. Qui, il dizionario Python conf contiene i valori impostati con il set di regole della GUI di configurazione, che vengono poi inseriti in un file JSON tramite una piccola deviazione.

Infine, lo script di shell aggiuntivo some_binary da fornire va inserito come SystemBinary sul sistema di destinazione nella directory dei programmi utente (di default /usr/bin).

4.10. Il file del plug-in per il nostro scenario di esempio

Mettendo insieme tutte le parti presentate finora — e completandole — un plug-in per il nostro scenario di esempio potrebbe apparire così una volta finito:

~/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,
)
Copia il contenuto del file negli appunti
Contenuto del file copiato con successo negli appunti!
L'accesso in scrittura agli appunti è stato negato!

4.11. Rendere disponibili i file

Affinché un plug-in Bakery funzioni correttamente, tutti i file coinvolti devono essere collocati o scritti nella posizione corretta nella struttura locale della directory del sito.

Si tratta, da un lato, del file del plug-in stesso e, dall'altro, degli oggetti restituiti dall'files_function. Questi oggetti descrivono i file di configurazione creati direttamente dal plug-in Bakery oppure fanno riferimento a file che devono essere archiviati correttamente in modo da poter essere trovati durante il packaging dei pacchetti dell'agente.

Gli oggetti delle classi Plugin e SystemBinary indicano i file esistenti che devono essere memorizzati. I file descritti come PluginConfig e SystemConfig devono ancora essere generati in base all'argomento lines, quindi qui non è necessario memorizzare alcun file.

Infine, l'insieme dei file include anche il file delle regole per il plug-in.

Nel prossimo e ultimo capitolo troverai l'elenco di tutte le directory.

5. File e directory

I file per l'installazione di un plug-in Bakery devono essere inseriti nelle seguenti directory. Come sempre, tutte le indicazioni qui riportate sono relative alla directory del sito (ad es. /omd/sites/mysite).

Percorso del file Descrizione

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

Directory per il plug-in Bakery (nel nostro esempio hello_world.py).

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

Directory per l'archiviazione dei plug-in degli agenti di tipo Unix.

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

Directory per l'archiviazione dei plug-in dell'agente Windows.

~/local/share/check_mk/agents/

Directory per i programmi inclusi o gli script di shell per sistemi operativi di tipo Unix (some_binary nell'esempio).

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

Directory per i programmi forniti o gli script di shell per Windows.

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

Directory per i file dei set di regole per configurare il plug-in dell'agente (nell'esempio ruleset_hello_world_bakery.py) e anche il plug-in di controllo associato (ad es. per impostare le soglie). Scegli quindi nomi significativi per poter distinguere i file. I nomi dei file memorizzati qui devono iniziare con ruleset_, altrimenti Checkmk li ignorerà.
Last modified: Wed, 25 Mar 2026 10:13:52 GMT via commit d7fa87218
In questa pagina