 |
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. Introducción
En las ediciones comerciales puedes utilizar la Bakery API para escribir tus propios plugins, denominados Bakery, que incluyen funciones en los paquetes del agente procedentes de la Bakery del agente. En la mayoría de los casos, estas funciones son plugins del agente, es decir, scripts adicionales que ejecuta el agente Checkmk, y los archivos de configuración de los plugins. Sin embargo, también pueden afectar a las funciones del administrador de paquetes si se pueden mapear incluyendo archivos, ejecutando scriptlets de paquetes (para los formatos de paquetes RPM, DEB y Solaris PKG), o si definen entradas de configuración específicas para el agente de Windows (en YAML). Todos estos "artefactos" se pueden describir en la Bakery API utilizando una sintaxis uniforme.
Por ejemplo, un escenario de aplicación en el mundo real es el siguiente: leíste la introducción al desarrollo de extensiones para Checkmk e, inspirándote en ella, escribiste tu propio plugin de agente Checkmk con su plugin de agente asociado. A continuación, combinaste ambos en un único Paquete de extensión Checkmk (MKP).
Ahora quieres que el plugin de agente sea configurable (por ejemplo, permitir que sólo lo ejecuten determinados usuarios o en determinados host) y que, además, realice acciones al instalar o desinstalar el paquete de agente. Para ello, puedes utilizar la Bakery API, como ayuda para el empaquetado y la distribución, como mostraremos en este artículo con un escenario de ejemplo. Esto crea dos archivos nuevos, que luego pueden empaquetarse junto con los archivos de plugin existentes para crear un nuevo MKP. También puedes encontrar un ejemplo completamente comentado de este procedimiento en el Checkmk Exchange: el paquete ¡Hola mundo! MKP(desempaquetado en GitHub), que se basa estrechamente en el escenario de ejemplo presentado en este artículo.
Nota: La Bakery API no proporciona funciones para configurar el Plugin de agente, es decir, para crear el conjunto de reglas asociado, ni para el contenido de los archivos proporcionados con el Plugin, por ejemplo, los plugins de agente.
 |
Aunque el Agent bakery sólo se incluye en las ediciones comerciales, la Bakery API existe en todas las ediciones desde Checkmk 2.3.0. Esto permite a los usuarios de Checkmk Raw crear paquetes de extensión que se pueden instalar en todas las ediciones. Si los paquetes creados con la Bakery API se instalan en un Checkmk Raw, la funcionalidad adicional simplemente se ignora. |
2. La documentación de la API
2.1. Versionado
El software y la documentación de la Bakery API proceden de la misma fuente, por lo que la documentación de la API siempre coincide con el software y describe exactamente lo que la API puede hacer, y por tanto no es necesario describir la parte de referencia de las funciones, clases, parámetros, etc. disponibles en el Manual de usuario de Checkmk. En su lugar, puedes encontrar la documentación de la API fuera de este Manual de usuario, directamente en su site de Checkmk.
La API y su documentación se versionan utilizando una numeración de dos niveles conforme al estándar Semantic Versioning 2. x en el formato X.Y, donde X representa una versión mayor y Y una versión menor. Una nueva versión menor contiene nuevas funciones compatibles con versiones anteriores. Una nueva versión mayor, en cambio, puede contener cambios que hagan que la API sea incompatible con la versión mayor anterior.
La versión 1 es la versión actual de la Bakery API descrita en este artículo. Cada Plugin declara explícitamente la versión de la API en la que se basa en el acceso a la API.
La API sigue un esquema de versiones distinto al del software Checkmk. No obstante, mapear las versiones de la documentación de la API y del software Checkmk es muy sencillo, como aprenderás en el capítulo siguiente.
2.2. Acceso a la documentación de la API
La documentación de la Bakery API está disponible en formato HTML para su visualización en un navegador web y se puede abrir desde la GUI de Checkmk: desde la barra de navegación del menú Help > Developer resources > Plug-in API references:
La documentación de la API del Plugin se muestra en una nueva ventana (o pestaña) del navegador:
Esta ventana muestra la documentación de la API relevante para el desarrollo de los plugins de Checkmk, es decir, aquí encontrarás la documentación de la API de Check además de la documentación de la API de Bakery. La documentación de la API se genera y muestra con Sphinx.
Puedes encontrar la documentación de la Bakery API en las versiones compatibles con la versión de Checkmk instalada en tu site.
3. Uso de la API
3.1. Un escenario de ejemplo
Demostraremos el uso de la API con el siguiente escenario de ejemplo:
Se proporciona un Plugin con el nombre
hello_worldpara el agente Checkmk.El Plugin de agente existe en tres variantes -para Linux, Solaris y Windows- y debe incluirse también en los paquetes de agente para estos tres sistemas operativos.Los archivos correspondientes también están disponibles y se llaman
hello_world(para Linux),hello_world.solaris.ksh(para Solaris) yhello_world.cmd(para Windows).
Los scripts Python, shell y CMD son sólo ejemplos. Un Plugin de agente puede ser cualquier archivo ejecutable en el sistema de destino.
En este contexto, no nos interesa el contenido real de los archivos. La función de los plugins de agente no es objeto de la Bakery API. Puedes obtener más información al respecto en la introducción al desarrollo de tus propios plugins de check plugin basados en agentes.Debe poder configurarse si la salida del Plugin debe almacenarse en caché, es decir, en este caso el Plugin sólo será ejecutado de nuevo por el agente una vez transcurrido el tiempo configurado (intervalo de ejecución).
El Plugin debe configurarse en el Menú de configuración a través de los ajustes de Agent bakery con las variables
userycontent. El Plugin de Linux lee la configuración del archivo de configuraciónhello_world.json, y el Plugin de Solaris la lee del archivohello_world.cfg. El Plugin de Windows lee las entradashello_world.useryhello_world.contentdel archivo de configuración YAML del agente de Windows.
En cada caso, el acceso a estos recursos debe implementarse en el plugin de agente y no lo gestiona la Bakery API.Para Linux y Solaris existe un programa adicional
some_binary, que debe entregarse, por ejemplo, como un pequeño script shell, para poder iniciar también el plugin mediante un comando independiente del agente Checkmk.En Linux y Solaris, después de instalar el agente, debe escribirse en el syslog, mediante una rutina del administrador de paquetes, que se ha instalado
hello_world. Análogamente, después de desinstalar el agente, debe escribirse en el syslog que se ha desinstaladohello_world.
En Linux son habituales los scriptspostinstyprerm: en el scriptpostinstcreas, por ejemplo, una caché e inicias un daemon, en el scriptprermpuedes volver a detener el daemon y borrar la caché. Para más información sobre cómo utilizarmaintainer scripts, consulta la documentación de Debian.
3.2. Crear un conjunto de reglas
Para un plugin de Bakery debe haber un conjunto de reglas de configuración, con las que el plugin pueda configurarse a través de la GUI. En el caso más sencillo, el conjunto de reglas sólo activa un plugin asignándolo a determinados host. La creación de un conjunto de reglas no forma parte de la Bakery API. Puedes encontrar una introducción a este tema en el artículo Desarrolla tus propios plugins de check basados en agentes. Allí también se explican las convenciones de ruta para almacenar conjuntos de reglas.
Conjunto de reglas mínimo
Un ejemplo de este conjunto de reglas mínimo, que sólo activa la distribución de un plugin, podría tener el siguiente aspecto. Las clases importadas aquí son más extensas de lo necesario para cubrir también el ejemplo ampliado. La diferencia más notable con el conjunto de reglas para los plugins de check plugin basados en agentes es el uso de la clase AgentConfig en lugar de CheckParameters.
#!/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,
)Conjunto de reglas ampliado
Sin embargo, en el escenario del ejemplo, hemos especificado que debe elegirse un intervalo de ejecución y que deben establecerse las dos variables user y content. Estas variables se definen como claves en la función Dictionary, que es devuelta por la función especificada como parameter_form.
#!/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,
)La GUI resultante de este conjunto de reglas se muestra en la siguiente captura de pantalla:
3.3. Crear un archivo Plugin
El archivo Plugin de hello_world.py se almacena en la parte local de la estructura del directorio del site en local/lib/check_mk/base/cee/plugins/bakery/.
Un Plugin de Panadería se crea en forma de un archivo que se importa como un módulo de Python 3. Por lo tanto, siguiendo la convención de Checkmk, los archivos Plugin también empiezan con las siguientes líneas:
#!/usr/bin/env python3
# -*- coding: utf-8 -*-Como se trata de un módulo, todas las clases y funciones necesarias deben importarse al principio.
3.4. Acceder a la API
Todos los objetos de la Bakery API están disponibles en cmk.base.cee.plugins.bakery.bakery_api.vX, donde X denota el número de versión de la API, en el ejemplo 1. Puesto que el propio archivo Plugin se encuentra en el namespace cmk.base.cee.plugins.bakery, también funcionará una importación relativa desde .bakery_api.v1:
from .bakery_api.v1 import (
OS,
DebStep,
RpmStep,
SolStep,
Plugin,
PluginConfig,
SystemBinary,
Scriptlet,
WindowsConfigEntry,
register,
FileGenerator,
ScriptletGenerator,
WindowsConfigGenerator,
quote_shell_string,
)En el ejemplo anterior, sólo se importan los nombres necesarios para el escenario de ejemplo.
3.5. Los objetos disponibles en la API
Los nombres disponibles en la Bakery API se describen detalladamente en la documentación de la API. No obstante, en este capítulo se presentan brevemente los objetos, ya que es útil para poder entender la implementación del escenario de ejemplo.
Identificador / Enumeraciones
Para la especificación de los artefactos individuales del Plugin, se dispone de enumeraciones (Enum), que pueden utilizarse para especificar diversas propiedades, normalmente en forma de argumento:
OS- El sistema operativo en el contexto de la Bakery API.DebStep- Un paso de transacción para un 'script mantenedor' DEBRpmStep- Un paso de transacción para un 'scriptlet' RPM.SolStep- Un paso de transacción para un "script de instalación" PKG de Solaris.
Artefactos
Los archivos y el contenido de los archivos que son los componentes reales de un Plugin se denominan artefactos. Éstos se describen utilizando clases apropiadas, que pueden dividirse en las siguientes categorías:
Ficheros (
Plugin,SystemBinary,PluginConfig,SystemConfig) - Cada fichero que se va a proporcionar al agente Checkmk se describe con un objeto. El tipo de fichero se describe mediante la clase. Debe definirse un objeto distinto para cada sistema operativo en el que se vaya a distribuir el fichero.Scriptlets (
Scriptlet) - Un "script de mantenimiento" DEB, un "scriptlet" RPM o un "script de instalación" PKG Solaris que se ejecutará al instalar, desinstalar o actualizar el paquete del agente en el paso de transacción especificado (por ejemplo,preinstall,postremove).Entradas de configuración de Windows (
WindowsConfigEntry,WindowsConfigItems,WindowsGlobalConfigEntry,WindowsSystemConfigEntry) - Las entradas del archivo de configuración YAML para el agente de Windows también se describen utilizando clases apropiadas.
Cada uno de estos artefactos se describe en funciones de devolución de llamada correspondientes a su categoría. Las funciones individuales se pasan a la función de registro con los argumentos files_function, scriptlets_function, windows_config_function. Se trata de funciones generadoras que devuelven los artefactos individuales especificados. La evaluación la realiza el Agent bakery.
Las funciones reciben varios parámetros como argumentos que se pueden evaluar para construir y determinar los artefactos devueltos. Los parámetros son, por un lado, la configuración GUI del agente respectivo que se va a hornear (conf) y, por otro, el hash de la configuración actual del agente y los archivos Plugin (aghash).
La función de registro
El registro se realiza con la función register, a la que se llama al importar el Plugin Bakery como módulo.
La función recibe como argumentos los componentes individuales del Plugin Bakery: el nombre del Plugin (name) y sus funciones (files_function, scriptlets_function, windows_config_function), cada una de las cuales devuelve una categoría de artefacto.
Anotaciones de tipo
Los nombres de las anotaciones de tipo (FileGenerator, ScriptletGenerator, WindowsConfigGenerator, WindowsConfigContent) pueden utilizarse opcionalmente para identificar el tipo de la función especificada, por ejemplo, así:
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)Funciones helper
Se pueden utilizar las siguientes funciones helper:
quote_shell_string- Esta función puede utilizarse para convertir una expresión de cadena de modo que el intérprete de comandos la reconozca correctamente como una expresión en el archivo resultante, sin tener que enmascarar manualmente las comillas en el código Python.password_store- Este módulo permite acceder a las contraseñas almacenadas en el almacén de contraseñas de Checkmk.
3.6. Registro
Registrar el Plugin en Checkmk con un Nombre del plugin y sus funciones se realiza con la función register.bakery_plugin:
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,
)Las funciones get_hello_world_windows_config, get_hello_world_scriptlets y get_hello_world_plugin_files especificadas aquí se explican con más detalle en los capítulos siguientes.
3.7. Configuración para el agente de Windows
Asegúrate de definir las claves y los tipos de datos tal y como se definen en el conjunto de reglas creado anteriormente.
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"])En la función get_hello_world_windows_config, utilizamos el argumento conf para acceder al conjunto de reglas de configuración en la GUI de configuración: el intervalo de tiempo para la reejecución en la salida en caché (interval) y las dos variables que se pueden utilizar para configurar el Plugin (user, content). Aquí suponemos que la configuración del conjunto de reglas se suministra como dict. Utilizando TypedDict de la clase HelloWorldConfig podemos establecer un acceso normalizado a ella.
Entonces se utiliza WindowsConfigEntry para especificar las entradas en elarchivo de configuración del agente YAML-Windows del que se leen los valores de user y content.
3.8. Script de instalación para Linux
En Linux y Solaris, deben escribirse mensajes syslog al instalar y desinstalar el agente. Aquí sólo mostramos una implementación de la distribución Debian Linux:
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)Primero se definen los comandos para los mensajes syslog y luego los scripts de instalación para Debian (DebStep) que deben ejecutarse tras la instalación (POSTINST) y tras la desinstalación (POSTRM). En los comentarios de abajo también encontrarás las líneas correspondientes para las distribuciones que utilizan RPM y para Solaris.
Nota: Después de las líneas de comando que has incluido, Checkmk carga los script de instalación con comandos adicionales. Por lo tanto, para asegurarte de que se ejecutan todos los comandos de los script, no termines tu conjunto de comandos con exit 0.
3.9. El Plugin de agente para Linux
La configuración del plugin de agente para Linux tiene el siguiente aspecto. Asegúrate de convertir el intervalo pasado a Integer, ya que el conjunto de reglas y el bakery utilizan tipos de datos diferentes.
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')En la función get_hello_world_plugin_files, primero se define el archivo Python hello_world como plugin, es decir, como un archivo ejecutable que debe ejecutar el agente Checkmk como Plugin de agente. Después se utiliza PluginConfig para especificar el archivo de configuración hello_world.json que debe generarse para el Plugin de agente de Linux con las entradas user y content.
Con la segunda función _get_linux_cfg_lines estas líneas se escriben en formato JSON. Aquí, el diccionario Python conf contiene los valores establecidos con el conjunto de reglas de la GUI de configuración, que luego se empaquetan en un archivo JSON mediante un pequeño desvío.
Por último, el script shell adicional some_binary que debe entregarse se colocará como SystemBinary en el sistema de destino, en el directorio para programas de usuario (por defecto /usr/bin).
3.10. El archivo Plugin para nuestro escenario de ejemplo
Juntando todas las partes presentadas hasta ahora -y completándolas-, un Plugin para nuestro escenario de ejemplo podría tener este aspecto cuando esté terminado:
#!/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,
)3.11. Hacer que los archivos estén disponibles
Para que un Plugin de Panadería funcione correctamente, todos los archivos implicados deben estar colocados o escritos en el lugar correcto de la estructura local del directorio del site.
Se trata, por un lado, del propio archivo del plugin y, por otro, de los objetos devueltos por el files_function. Estos objetos describen archivos de configuración creados directamente por el plugin de Bakery, o bien hacen referencia a archivos que deben almacenarse correctamente para que puedan encontrarse al empaquetar los paquetes del agente.
Los objetos de las clases Plugin y SystemBinary denotan archivos existentes que deben almacenarse. Los archivos descritos como PluginConfig y SystemConfig aún no se han generado en base al argumento lines, por lo que no es necesario almacenar ningún archivo aquí.
Por último, el conjunto de archivos también incluye el archivo del conjunto de reglas del Plugin.
En el siguiente y último capítulo encontrarás la compilación de todos los directorios.
4. Archivos y directorios
Los archivos para distribuir un Plugin de Panadería deben colocarse en los siguientes directorios. Como siempre, todas las especificaciones aquí son relativas al directorio del site (por ejemplo, /omd/sites/mysite).
| Ruta del archivo | Descripción |
|---|---|
|
Directorio para el Plugin de Panadería (en nuestro ejemplo |
|
Directorio para almacenar los plugins de agente tipo Unix. |
|
Directorio para almacenar los Plugin de agente de Windows. |
|
Directorio para programas incluidos o scripts shell para sistemas operativos tipo Unix ( |
|
Directorio para los programas o scripts shell incluidos para Windows. |
|
Directorio para los archivos del conjunto de reglas para configurar el plugin de agente (en el ejemplo |