1. Introducción
Con la API-REST de Checkmk como interfaz de programación de aplicaciones, puedes transmitir tareas al servidor Checkmk mediante un comando o script con peticiones HTTP y hacer que se ejecuten, tareas que de otro modo realizarías en Checkmk mediante la GUI.
REST en el nombre de la API-REST significa REpresentational State Transfer, y describe una arquitectura para el intercambio de datos en sistemas distribuidos, especialmente para servicios web. Una API implementada según la arquitectura REST sigue ciertos principios, como el modelo cliente-servidor, la comunicación sin estado y una interfaz uniforme. En la práctica, la implementación se lleva a cabo preferentemente mediante el protocolo HTTP, por el que se accede a los recursos a través del Identificador Uniforme de Recursos (URI) y mediante métodos HTTP (GET, POST, PUT, DELETE).
Hasta aquí los principios del REST. Las ventajas de estos principios pueden demostrarse con las funciones concretas que ofrece la API-REST de Checkmk:
Protocolo |
Se utiliza el Protocolo de Transferencia de Hipertexto(HTTP/1.1) como sistema de transporte para la comunicación. |
Codificación |
Se utiliza la Notación de Objetos JavaScript(JSON) como formato de datos. La carga útil de las respuestas se serializa con JSON y se codifica en UTF-8. La información de fecha y hora se codifica en el formato ISO-8601 con información válida de zona horaria. |
Idioma |
El inglés es el idioma de las etiquetas, los identificadores y la documentación de la API. |
Autenticación |
El acceso a la API sólo se concede a un cliente si ha demostrado su autorización mediante autenticación HTTP- 'Portador', por ejemplo. |
Versionado |
La API está versionada y utiliza un esquema de numeración conforme a la norma Semantic Versioning 2.x. Para más detalles, consulta la sección sobre versionado más abajo. |
Documentación |
La API está documentada en una estructura legible por máquinas y en un formato en inglés legible por humanos, e incluye todos los recursos, sus parámetros de entrada y salida y sus rangos de valores asociados. La API está creada con la Especificación OpenAPI (OAS) 3.x, un formato de descripción de la API pensado especialmente para las API REST. El documento de la API creado con esta especificación se muestra al usuario con ReDoc, un diseño web responsivo para documentos OpenAPI. |
Ejemplo de código |
Para demostrar su uso, se proporciona código ejemplo de varias aplicaciones para cada solicitud: curl y httpie, por ejemplo. |
Visualización de errores |
En caso de error, la API envía códigos de estado HTTP numéricos y un mensaje de diagnóstico del problema, que ayuda a identificar las posibles causas de las solicitudes incorrectas. |
Clasificación de la API-REST |
La API cumple los cuatro niveles (de 0 a 3) del Modelo de Madurez de Richardson (RMM), que puede utilizarse para evaluar el grado de REST de una API. El nivel 1 requiere la introducción de recursos que permitan la comunicación a través de la API con endpoints individuales en lugar de con uno global. El nivel 2 se cumple si se utilizan métodos HTTP para las solicitudes. En el (más alto) nivel 3, la API es efectivamente autodocumentada, en el sentido de que el servidor, al responder a una solicitud, comunica las posibles acciones siguientes y los recursos a los que debe dirigirse, permitiendo así al cliente descubrir por sí mismo la funcionalidad disponible. Este suministro de información adicional también se conoce como "hipermedia como motor del estado de la aplicación"(HATEOAS). |
Además de estas funciones de comodidad general, la API-REST pretende cubrir toda la funcionalidad que en versiones anteriores de Checkmk se proporcionaba mediante la GUI y una interfaz de comandos.
Para las funciones que sólo existen en las ediciones comerciales, como service level agreement (SLA) o Agent bakery, los métodos API-REST asociados también se proporcionan sólo en estas ediciones.
 |
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. |
2. La documentación de la API
2.1. Versionado
Una de las ventajas de la API-REST es que tanto el software como su documentación proceden de la misma fuente: el documento OpenAPI. Por lo tanto, la documentación de la API siempre coincide con el software y describe exactamente lo que la API puede hacer. Por lo tanto, no es necesario describir la parte de referencia de los recursos disponibles, métodos, parámetros, etc. en el Manual de usuario de Checkmk; en su lugar, encontrarás la documentación de la API por separado de este manual, directamente en tu site de Checkmk.
La API y su documentación están versionadas y utilizan un esquema de numeración de dos niveles en formato X.Y, en el que X representa una versión mayor y Y una versión menor. Una nueva versión menor sólo contiene cambios compatibles con versiones anteriores que no afectan a las funciones existentes.
En cambio, una nueva versión mayor contiene cambios que hacen que la API sea incompatible con la versión mayor anterior (los llamados cambios de ruptura). Los números de versión de las versiones mayor y menor forman parte de la URL con la que se envía una solicitud al servidor. Actualmente, la API-REST de Checkmk no utiliza el tercer nivel (.Z) del estándar de Versionado Semántico para una versión de parche.
Ten en cuenta que la API-REST sigue un esquema de versionado distinto al del software Checkmk. Dado que es necesario crear una nueva major release de la API si se producen cambios incompatibles en la API, ésta no suele coincidir con el ciclo de versiones del software Checkmk.
No obstante, la correlación entre las versiones de la documentación de la API y el software Checkmk es muy sencilla, como aprenderás en el capítulo siguiente.
2.2. Accede a
La documentación de la API-REST está disponible en formato HTML para su vista en un navegador web.
En la GUI de Checkmk, abre la documentación de la API desde la barra de navegación a través de Help > Developer resources > REST API documentation. La documentación de la API se muestra en una nueva ventana del navegador (o pestaña del navegador). Hablaremos de ello con más detalle en el próximo capítulo.
 |
Seguramente te habrás dado cuenta de que hay más entradas que cubren la API-REST en el menú Help. Con REST API introduction puedes abrir este artículo. Con REST API interactive GUI puedes abrir otra vista de la API-REST. La entrada se llama GUI porque no sólo se te muestran las funciones de la API-REST, sino porque también puedes interactuar con la API directamente desde el navegador, enviando peticiones al servidor, por ejemplo. Presentaremos la GUI de la API-REST como alternativa a la ejecución por script más adelante, en el capítulo sobre la GUI de la API-REST. |
2.3. Estructura y contenido
La documentación de la API utiliza un diseño web adaptable que consta de tres secciones:
La sección de la izquierda, Navegación, se utiliza para la orientación, la búsqueda y un salto rápido a la descripción exacta de las entradas de la sección central. El índice contiene una entrada para cada endpoint de la API. Un endpoint utiliza una URL para referirse al recurso que proporciona la API (por ejemplo, hosts), junto con el método utilizado para acceder al recurso (por ejemplo, GET para mostrar un host). Los endpoints están organizados en varias carpetas.
La sección central, Contenido, contiene los datos concretos de la documentación: toda la información para definir una solicitud (con parámetros, rangos de valores, valores por defecto y descripciones) y las respuestas correspondientes (también con todos los detalles). Las posibles respuestas se muestran en diferentes colores, dependiendo de si el código de estado HTTP devuelto indica éxito o error.
La sección de la derecha, Request samples, muestra el método y la URL del endpoint seleccionado en la sección de contenido, seguidos de varios ejemplos de peticiones: la carga útil en formato JSON (si es relevante para el endpoint) y ejemplos de código, por ejemplo para curl, httpie, Python Requests y Python Urllib. A continuación siguen las respuestas según el estado HTTP. Todos los ejemplos de código pueden copiarse al portapapeles con el botón Copy.
La sección de navegación está sincronizada con las otras dos secciones, lo que significa que si te desplazas hacia arriba o hacia abajo en la sección de contenidos, la sección de navegación se desplaza automáticamente a la entrada correspondiente del índice.
El diseño web con capacidad de respuesta garantiza que la sección de ejemplos no aparezca en una ventana de navegador muy estrecha (los ejemplos se muestran entonces debajo del método correspondiente), y la sección de navegación se convierte en un menú.
En todas las secciones encontrarás contenidos que puedes mostrar y ocultar, por ejemplo, las entradas de los endpoints en la sección de navegación, y los parámetros anidados en la sección de contenidos. Haciendo clic en > o Expand all puedes mostrar los contenidos ocultos, y con ∨ o Collapse all puedes ocultarlos de nuevo.
En el próximo capítulo aprenderás cómo puedes utilizar la documentación de la API para crear solicitudes concretas a partir de la información, enviar estas solicitudes al servidor Checkmk, hacer que se ejecuten y monitorizar esa ejecución y los resultados.
3. Uso de la API
3.1. Autenticación
Para utilizar la API-REST en el servidor Checkmk desde un cliente, éste debe demostrar su identidad. La API-REST admite los siguientes métodos de autenticación: Portador, Servidor web y Cookie- en este orden de precedencia. Esto significa, por ejemplo, que si la autenticación con Portador tiene éxito, no se comprobará ninguno de los otros métodos.
Autenticación de portador o encabezado
Por "portador" se entiende el titular de una identidad. El cliente se autentifica con las credenciales de un usuario configurado en el servidor Checkmk. En el mejor de los casos, se trata del llamado usuario de automatización, que se proporciona en Checkmk para la ejecución de acciones a través de una API. Se recomienda utilizar la autenticación por portador en los scripts.
Para la autenticación, necesitas el nombre de usuario y el denominado secreto de automatización correspondiente para las cuentas de máquina, es decir, la contraseña del usuario de automatización. Ambos items de información deben transmitirse al servidor Checkmk en la cabecera de cada solicitud. En un site recién creado, el usuario automation ya habrá sido creado. Puedes encontrarlo, como otros usuarios, en Setup > Users > Users. Asegúrate de que los roles y permisos asociados para el usuario de automatización están configurados para permitirte ejecutar tus solicitudes.
Para los scripts presentados en este artículo, se utiliza siempre el usuario de automatización como ejemplo por defecto.
Autenticación del servidor web
Para autentificar el servidor web, la API-REST utiliza la autentificación HTTP configurada para el servidor web ("Básica" o "Digerir").
Este método de autenticación está pensado para grandes instalaciones de Checkmk con requisitos especiales que se realizan utilizando y configurando módulos de software para la autenticación del servidor web Apache. Si quieres utilizar la autenticación del servidor web, tienes que volver a configurar el servidor web Apache del propio site de Checkmk.
Autenticación de cookies
La autenticación por cookies es un caso especial de autenticación por clave API. Todos los usuarios de Checkmk que hayan iniciado sesión en Checkmk y tengan asignada una cookie HTTP pueden utilizar la API-REST. La autenticación por cookie se utiliza para probar y hacer pruebas con la GUI de la API-REST. La ejecución de las solicitudes depende de si tu cuenta de usuario de Checkmk tiene los permisos adecuados.
3.2. Código de estado HTTP
La API-REST devuelve el código de estado HTTP de cada solicitud, que puedes utilizar para comprobar si la solicitud se ha realizado correctamente. En la documentación de la API se enumeran todos los posibles códigos de estado HTTP de la solicitud.
Ten en cuenta que el código de estado HTTP sólo proporciona información sobre el éxito de la transmisión de la solicitud, pero no sobre el éxito de su ejecución. Los comandos se ejecutan en el servidor Checkmk con Livestatus. Para estar seguro de que la solicitud a través de la API REST realmente hace lo que pretendías, debes verificar tú mismo el éxito. La documentación de la API, que puedes abrir con Help > Developer resources > REST API interactive GUI, contiene un ejemplo de script para esta tarea en la sección "Consultas a través de la API REST".
3.3. Probar la API localmente
Para probar la API-REST, es aconsejable realizar las solicitudes directamente desde el servidor Checkmk, es decir, en este ejemplo, el cliente que envía la solicitud y el servidor que la recibe se encuentran en el mismo ordenador. Si trabajas como usuario del site, también puedes utilizar variables locales como $OMD_SITE, que hace referencia al nombre del site.
En los siguientes ejemplos sencillos, utilizamos el código ejemplo contenido en la documentación de la API para el programa de línea de comandos curl, que permite transferir datos a o desde un servidor sin interacción del usuario, por ejemplo, a través de HTTP.
|
Especialmente en el caso de peticiones complejas, los ejemplos de curl pueden contener incoherencias y, por tanto, no ser siempre fiables. Con httpie se dispone de una alternativa coherente, fácil de entender y muy adecuada para su uso en scripts. |
El comando curl se ejecuta dentro de un script bash. Para la preparación, crea un archivo script para cada una de las peticiones que se van a ejecutar en la siguiente sección, en el que luego se copiará el código ejemplo:
OMD[mysite]:~$ touch create_host.sh service_discovery.sh show_pending_changes.sh activate_changes.sh
OMD[mysite]:~$ chmod +x create_host.sh service_discovery.sh show_pending_changes.sh activate_changes.shLa API-REST da salida a todas las respuestas en formato JSON de una sola línea. Dado que la salida formateada facilita mucho su lectura, los siguientes ejemplos muestran la salida de una sola línea formateada en varias líneas. Existen varios sitios web y herramientas para procesar el formato JSON, por ejemplo el procesador JSON de línea de comandos jq.
Antes de empezar, reúne alguna información básica específica de tu configuración de Checkmk:
| Variable | Valor de ejemplo | Significado |
|---|---|---|
|
|
El nombre de host del servidor Checkmk |
|
|
El nombre del site de Checkmk |
|
|
El nombre del usuario de automatización |
|
|
La contraseña del usuario de automatización |
Estas variables se utilizan en el código ejemplo y debes editarlas tú antes de enviar una solicitud. En la tabla anterior también encontrarás los valores de ejemplo que se utilizan a continuación.
3.4. Realizar solicitudes utilizando scripts
Con un ejemplo sencillo vamos a demostrar ahora cómo utilizar la API-REST. Crea un host con sus servicios utilizando un total de cuatro peticiones. En principio, procede del mismo modo que con la GUI de Checkmk:
Crear un host
Realiza un descubrimiento de servicios en el host
Mostrar los cambios pendientes
Activa los cambios
Crear un host
Abre la documentación de la API y selecciona la entrada para crear un host (Create a host) en el área de navegación de la izquierda:
En la parte central del panel puedes ver los detalles de la solicitud seleccionada, qué autenticación HTTP se requiere (esto es idéntico para todas las solicitudes a través de la API-REST), y los parámetros obligatorios y opcionales. Se requiere el nombre del host y la carpeta en la que debe crearse. Por defecto, el host se crea en la carpeta Main. Si quieres crear el host en otra carpeta, es posible que primero tengas que hacer otra solicitud a la API (Show all folders) para ver las carpetas existentes y determinar el ID de la que quieres utilizar.
En nuestro ejemplo, el host myhost123 se creará con la dirección IP 192.168.0.42 en la carpeta Main.
En la documentación de la API, haz clic en el botón curl del área de ejemplos de la derecha y, a continuación, haz clic en Copy para copiar el código ejemplo de curl en el portapapeles. Abre el script preparado create_host.sh y pega en él el contenido del portapapeles:
#!/bin/bash
# NOTE: We recommend all shell users to use the "httpie" examples instead.
# `curl` should not be used for writing large scripts.
# This code is provided for debugging purposes only.
HOST_NAME="localhost"
SITE_NAME="mysite"
PROTO="http" #[http|https]
API_URL="$PROTO://$HOST_NAME/$SITE_NAME/check_mk/api/1.0"
USERNAME="automation"
PASSWORD="test123"
curl \
--request POST \
--write-out "\nxxx-status_code=%{http_code}\n" \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '{
"attributes": {
"ipaddress": "192.168.0.123"
},
"folder": "/",
"host_name": "example.com"
}' \
"$API_URL/domain-types/host_config/collections/all"En la primera parte del código de ejemplo encontrarás las variables del entorno, después viene el comando curl con el método POST sobre el recurso cuya URL está en la última línea. Por último, la opción -write-out muestra una línea con el código de estado HTTP. Las líneas de encabezado (una de las cuales define la autenticación HTTP) van seguidas de la sección de datos en la que se definen los parámetros para el nuevo host.
Ten en cuenta que el código ejemplo de curl puede contener más parámetros de los que puedas necesitar para una situación concreta. En nuestro ejemplo no es éste el caso y sólo tienes que cambiar los dos parámetros existentes, host_name y ipaddress.
Ahora edita el código ejemplo para que el resultado sea algo parecido a esto:
#!/bin/bash
# NOTE: We recommend all shell users to use the "httpie" examples instead.
# `curl` should not be used for writing large scripts.
# This code is provided for debugging purposes only.
HOST_NAME="myserver"
SITE_NAME="mysite"
PROTO="http" #[http|https]
API_URL="$PROTO://$HOST_NAME/$SITE_NAME/check_mk/api/1.0"
USERNAME="automation"
PASSWORD="theautomationsecret"
curl \
--request POST \
--write-out "\nxxx-status_code=%{http_code}\n" \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '{
"attributes": {
"ipaddress": "192.168.0.42"
},
"folder": "/",
"host_name": "myhost123"
}' \
"$API_URL/domain-types/host_config/collections/all"Ejecuta el script:
OMD[mysite]:~$ ./create_host.sh
{
"links":[
{
"domainType":"link",
"rel":"self",
"href":"http://myserver/mysite/check_mk/api/1.0/objects/host_config/myhost123",
"method":"GET",
"type":"application/json"
},
...
{
"domainType":"link",
"rel":"urn:com.checkmk:rels/folder_config",
"href":"http://myserver/mysite/check_mk/api/1.0/objects/folder_config/~",
"method":"GET",
"type":"application/json",
"title":"The folder config of the host."
}
],
"domainType":"host_config",
"id":"myhost123",
"title":"myhost123",
"members":{
},
"extensions":{
"folder":"/",
"attributes":{
"ipaddress":"192.168.0.42",
"meta_data":{
"created_at":"2024-07-03T12:55:29.165920+00:00",
"updated_at":"2024-07-03T12:55:29.174520+00:00",
"created_by":"automation"
}
},
"effective_attributes":null,
"is_cluster":false,
"is_offline":false,
"cluster_nodes":null
}
}
xxx-status_code=200
Recordatorio: La línea única en formato JSON delimitada por las llaves se muestra aquí en varias líneas.
La API devuelve en links una selección de solicitudes (abreviadas en nuestro ejemplo anterior), que pueden aplicarse al host que se acaba de crear, como corresponde a una API REST. Por último, la API devuelve el ID y el nombre (title) del host creado, el nombre folder (/ para la carpeta principal) y el attributes asignado al host, incluida la dirección IP.
Por último, se muestra la línea con el código de estado HTTP. 200 significa OK y significa que la acción se ha realizado correctamente.
Realizar un descubrimiento de servicios en el host
Una vez creado el host myhost123, se pueden descubrir sus servicios. Para asegurarte de que un descubrimiento de servicios realmente proporciona los servicios esperados, en los host Linux y Windows primero debes instalar y registrar sus respectivos agentes.
Para ejecutar un descubrimiento de servicios a través de la API-REST, selecciona la entrada adecuada en la documentación de la API (Execute a service discovery on a host), copia el código ejemplo en el archivo script creado a tal efecto y adáptalo.
Puedes copiar la primera parte con las variables del entorno 1:1 del ejemplo anterior. En el comando curl, cambia el nombre del host a myhost123 y, si es necesario, utiliza el parámetro mode para cambiar el tipo de descubrimiento de servicios.
#!/bin/bash
# NOTE: We recommend all shell users to use the "httpie" examples instead.
# `curl` should not be used for writing large scripts.
# This code is provided for debugging purposes only.
HOST_NAME="myserver"
SITE_NAME="mysite"
PROTO="http" #[http|https]
API_URL="$PROTO://$HOST_NAME/$SITE_NAME/check_mk/api/1.0"
USERNAME="automation"
PASSWORD="theautomationsecret"
curl \
--request POST \
--write-out "\nxxx-status_code=%{http_code}\n" \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '{
"host_name": "myhost123",
"mode": "refresh"
}' \
"$API_URL/domain-types/service_discovery_run/actions/start/invoke"Ejecuta también este script:
OMD[mysite]:~$ ./service_discovery.sh
xxx-status_code=302El código de estado HTTP 302 significa que se ha inicializado el trabajo en segundo plano para el descubrimiento de servicios.
Mostrar cambios pendientes
Antes de activar los cambios, es necesario un paso intermedio: mostrar los cambios pendientes con la solicitud Show all pending changes. Además de los cambios acumulados, la API-REST también proporciona la ETag HTTP(etiqueta de entidad) que necesitas para activar estos cambios. Un objeto no se modifica a través de la API-REST utilizando el ID o el título del objeto, sino que la ETag generada se utiliza para evitar que varias solicitudes concurrentes sobrescriban valores del mismo objeto.
El ETag se devuelve en la cabecera de respuesta. Para mostrar esta cabecera, amplía el código de ejemplo de esta solicitud llamando a curl con la opción -i (para incluir cabeceras de respuesta). Las líneas modificadas también se vuelven a marcar en el siguiente ejemplo:
#!/bin/bash
# NOTE: We recommend all shell users to use the "httpie" examples instead.
# `curl` should not be used for writing large scripts.
# This code is provided for debugging purposes only.
HOST_NAME="myserver"
SITE_NAME="mysite"
PROTO="http" #[http|https]
API_URL="$PROTO://$HOST_NAME/$SITE_NAME/check_mk/api/1.0"
USERNAME="automation"
PASSWORD="theautomationsecret"
curl \
-i \
--request GET \
--write-out "\nxxx-status_code=%{http_code}\n" \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \
"$API_URL/domain-types/activation_run/collections/pending_changes"Una vez ejecutado el script, las líneas de cabecera se muestran primero en la salida:
OMD[mysite]:~$ ./show_pending_changes.sh
HTTP/1.1 200 OK
Date: Wed, 03 Jul 2024 13:23:26 GMT
...
ETag: "2156db7032754ec778c75123ec12cdd897592b0a574760fa0963a1782c22472c"
...
Content-Type: application/json
{
...
"domainType":"activation_run",
"value":[
{
"id":"8cb85882-cdae-4d43-b5af-362b4c1cb717",
"user_id":"automation",
"action_name":"create-host",
"text":"Created new host myhost123.",
"time":"2024-07-03T13:05:07.466406+00:00"
}
]
}
xxx-status_code=200
Para mayor claridad, aquí se acorta la salida y sólo se marcan las líneas importantes: la línea de cabecera con el ETag, los atributos del único cambio pendiente para crear un host y el código de estado HTTP para OK. Necesitarás el ETag en el siguiente y último paso.
Activar cambios
Por último, hay que activar los cambios. La petición adecuada se llama Activate pending changes.
En el comando curl, cambia la línea de cabecera If-Match e inserta el ETag leído en la sección anterior. En la sección de datos, cambia el parámetro sites y ajústalo al nombre del site en el que deben activarse los cambios:
#!/bin/bash
# NOTE: We recommend all shell users to use the "httpie" examples instead.
# `curl` should not be used for writing large scripts.
# This code is provided for debugging purposes only.
HOST_NAME="myserver"
SITE_NAME="mysite"
PROTO="http" #[http|https]
API_URL="$PROTO://$HOST_NAME/$SITE_NAME/check_mk/api/1.0"
USERNAME="automation"
PASSWORD="1234567890"
curl -L \
--write-out "\nxxx-status_code=%{http_code}\n" \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \
--header "If-Match: "2156db7032754ec778c75123ec12cdd897592b0a574760fa0963a1782c22472c"" \
--header "Content-Type: application/json" \
--data '{
"force_foreign_changes": false,
"redirect": false,
"sites": [
"mysite"
]
}' \
"$API_URL/domain-types/activation_run/actions/activate-changes/invoke"Ejecuta este script:
OMD[mysite]:~$ ./activate_changes.sh
{
"links":[
{
"domainType":"link",
"rel":"self",
"href":"http://myserver/mysite/check_mk/api/1.0/objects/activation_run/eddbef05-438b-4108-9a02-0d010da2b290",
"method":"GET",
"type":"application/json"
},
{
"domainType":"link",
"rel":"urn:com.checkmk:rels/wait-for-completion",
"href":"http://myserver/mysite/check_mk/api/1.0/objects/activation_run/eddbef05-438b-4108-9a02-0d010da2b290/actions/wait-for-completion/invoke",
"method":"GET",
"type":"application/json"
}
],
"domainType":"activation_run",
"id":"eddbef05-438b-4108-9a02-0d010da2b290",
"title":"Activation status: In progress.",
"members":{
},
"extensions":{
"sites":[
"mysite"
],
"is_running":true,
"force_foreign_changes":false,
"time_started":"2024-07-03T13:45:07.031741+00:00",
"changes":[
{
"id":"8cb85882-cdae-4d43-b5af-362b4c1cb717",
"user_id":"automation",
"action_name":"create-host",
"text":"Created new host myhost123.",
"time":"2024-07-03T13:05:07.466406+00:00"
}
]
}
}
xxx-status_code=200
El texto title indica que se ha iniciado la activación. De nuevo, la API-REST sugiere dos útiles peticiones de seguimiento en links: para consultar el estado de esta activación y para esperar a que finalice.
3.5. Realizar solicitudes a través de la GUI de la API-REST
Con la GUI de la API-REST obtienes una nueva perspectiva de la API. Con esta GUI puedes interactuar directamente con la API desde el navegador enviando solicitudes al servidor mediante comandos curl, y ver inmediatamente las respuestas. Para ello, tienes que prescindir de los ejemplos de código de la documentación de la API-REST en la GUI de la API: ambas vistas están optimizadas para sus respectivas funciones.
La GUI de la API-REST se genera a partir de la misma fuente que la documentación de la API-REST -el documento OpenAPI- y, por tanto, siempre proporciona funciones que coinciden con la API.
Puedes abrir la GUI de la API en la GUI de Checkmk desde la barra de navegación, menú Help > Developer resources > REST API interactive GUI. La GUI de la API se muestra en una nueva ventana del navegador (o pestaña del navegador):
A continuación te explicamos cómo puedes ejecutar la primera solicitud del ejemplo anterior (crear un host) con la GUI de la API-REST en lugar de utilizar un script:
Autentificar: La GUI de la API-REST ofrece una caja de diálogo para introducir información de autentificación tras hacer clic en el botón Authorize (a la derecha, encima de la entrada de la carpeta del primer endpoint). Sin embargo, si has iniciado sesión como usuario del site, no necesitas hacer ninguna entrada ahí, ya que estás autorizado a utilizar la API-REST como usuario del Checkmk mediante la autentificación por cookies.
Selecciona el endpoint: En la carpeta Hosts, selecciona el endpoint Create a host y haz clic en Try it out.
Introduce los valores de los parámetros: En Request body sobrescribe los valores de ejemplo de
host_nameyipaddress.Envía una solicitud: Haz clic en Execute.
Comprueba la respuesta: En Responses verás primero el comando curl enviado y la URL del endpoint. A continuación, en Server response se muestra la respuesta con el código de estado HTTP y en Responses con la respuesta (formateada en varias líneas) de la API-REST.
Por tanto, la GUI de la API-REST te ofrece la oportunidad de probar las funciones de la API de forma rápida y sencilla, y de familiarizarte con las funciones de los valores de entrada, así como con las respuestas concretas.
3.6. Corrección de errores
A diferencia de la salida de comandos con éxito mediante script mostrada hasta ahora, la API-REST te muestra los errores de la siguiente manera:
{
"title": "The operation has failed.",
"status": 401,
"detail": "There are changes from other users and foreign changes are not allowed in this API call."
}
xxx-status_code=401Dependiendo del error, los parámetros mostrados en la salida pueden variar. Sin embargo, en status el código de estado HTTP, y en title siempre reciben una breve descripción de la causa del error.
En la mayoría de los casos, detail te mostrará información detallada, como su nombre indica. En el ejemplo anterior, puedes ver que hay cambios pendientes en Checkmk, pero que fueron iniciados por otro usuario. Por defecto, sólo se pueden activar a través de la API los cambios que también se hayan realizado a través de la API.
En el siguiente ejemplo, los mensajes de ayuda también están en la información detallada:
{
"title":"Bad Request",
"status":400,
"detail":"These fields have problems: host_name",
"fields":{
"host_name":[
"'my/host123' does not match pattern '^[-0-9a-zA-Z_.]+\\\\Z'."
]
}
}
xxx-status_code=400El problema en el ejemplo anterior es que el valor de un parámetro no se ajusta al rango de valores válidos porque el nombre del host contiene una barra.
El número de errores posibles es, por supuesto, mucho mayor que los dos que hemos presentado aquí. Sin embargo, puedes ver en los ejemplos mostrados que, en su salida, la API-REST suele proporcionar información suficiente sobre la causa y, por tanto, te da pistas para iniciar el análisis y la resolución de problemas.
4. Asegurar la API
Puesto que durante el acceso a través de la API-REST se pueden transferir datos confidenciales y -dependiendo de la autorización del usuario de automatización- se podrían realizar alteraciones considerables en Checkmk, debes asegurar dicho acceso en consecuencia. Aquí encontrarás algunas de las opciones disponibles:
Checkmk sobre HTTPS: Utiliza la API exclusivamente sobre el Protocolo Seguro de Transferencia de Hipertexto (HTTPS); de lo contrario, los nombres de usuario, las contraseñas y también los datos de configuración se transmitirán en texto claro por la red.
Asigna al usuario de automatización una contraseña de longitud suficiente. Como la contraseña suele almacenarse sólo en un script, puedes asignarle fácilmente una muy larga.
Presta mucha atención al concepto de autorización para los scripts que utilices para hacer solicitudes a la API. Los scripts pueden contener datos sensibles, como datos de configuración, contraseñas, etc. Por tanto, asegúrate de que sólo los usuarios y grupos autorizados puedan leer estos scripts.
5. Ejemplos con solicitudes a la API-REST
En este capítulo encontrarás ejemplos que muestran cómo realizar las acciones más habituales utilizando la API-REST. Los ejemplos se basan, una vez más, en el código ejemplo del programa de línea de comandos curl. Sin embargo, a diferencia del procedimiento del capítulo Utilización de la API, aquí las solicitudes se realizan como comandos curl en la línea de comandos y no mediante script. Esto te permite probar nuestros ejemplos de inmediato, después de haberlos personalizado para adaptarlos a tu propio entorno.
Para presentar aquí los comandos con claridad, sólo hemos mostrado las líneas del código ejemplo que son absolutamente necesarias para la ejecución del comando.
Al igual que el código de ejemplo de la documentación de la API, los ejemplos de este capítulo contienen variables para ensamblar la URL base de la API-REST en tu servidor Checkmk y para establecer las credenciales del usuario de automatización para la autenticación Bearer utilizada:
| Variable | Valor de ejemplo | Descripción |
|---|---|---|
|
|
Nombre del servidor Checkmk |
|
|
Nombre del site de Checkmk |
|
|
URL base de la API-REST |
|
|
Nombre del usuario de automatización |
|
|
Contraseña del usuario de automatización |
Antes de emitir los comandos curl, puedes adaptar las variables a tu entorno utilizando los siguientes comandos del shell:
user@host:~$ HOST_NAME="myserver"; SITE_NAME="mysite"; API_URL="http://$HOST_NAME/$SITE_NAME/check_mk/api/1.0"; \
USERNAME="automation"; PASSWORD="theautomationsecret";5.1. Hosts y carpetas
Las solicitudes descritas en este capítulo se pueden encontrar en la documentación de la API en las subcarpetas Hosts y Folders. Los títulos de los respectivos endpoints contenidos en la documentación de la API son los siguientes.
Mostrar todas las carpetas
Aquí se muestran todas las carpetas de la Configuración -recursivamente a partir de la carpeta Main -sin listar los host que contienen:
user@host:~$ curl -G \
--request GET \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \
--data-urlencode 'parent=~' \
--data-urlencode 'recursive=true' \
--data-urlencode 'show_hosts=false' \
"$API_URL/domain-types/folder_config/collections/all"Mostrar todos los hosts de una carpeta
Aquí se solicitan los hosts de la subcarpeta Main > Linux:
user@host:~$ curl \
--request GET \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \
"$API_URL/objects/folder_config/~linux/collections/hosts"Crear una carpeta
Aquí se crea una subcarpeta Production Hosts en Main > Linux- en el sistema de archivos como el directorio production_hosts. A la nueva carpeta se le asigna el tag del host Productive system del grupo de tags de host predefinido Criticality:
user@host:~$ curl \
--request POST \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '{
"attributes": {
"tag_criticality": "prod"
},
"name": "production_hosts",
"parent": "~linux",
"title": "Production Hosts"
}' \
"$API_URL/domain-types/folder_config/collections/all"Crear un host
Aquí, en la carpeta Main > Linux > Production Hosts, se crea el host mylinuxserver con la dirección IP 192.168.0.123 y el tag del host Use piggyback data from other hosts if present:
user@host:~$ curl \
--request POST \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '{
"attributes": {
"ipaddress": "192.168.0.123",
"tag_piggyback": "auto-piggyback"
},
"folder": "~linux~production_hosts",
"host_name": "mylinuxserver"
}' \
"$API_URL/domain-types/host_config/collections/all"Mostrar un host
Al mostrar un host recibes una lista de los atributos que tiene asignados. Además, te proporciona el ETag HTTP(etiqueta de entidad) que necesitas para poder modificar un host. Puedes obtener más información sobre el ETag en la sección Mostrar cambios pendientes.
El ETag se devuelve en la cabecera de la respuesta. Para mostrar esta cabecera, llama a curl con la opción -v (para verbosidad). Aquí se consulta el host mylinuxserver - y de la respuesta sólo se muestra la línea que contiene el ETag:
user@host:~$ curl -vG \
--request GET \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \
"$API_URL/objects/host_config/mylinuxserver"
...
< ETag: "57db3792f23bd81ca7447ba4885fa2865d0c78aed4753229b29e179e539da48b"
...Actualizar un host
Antes de realizar el cambio, obtén el ETag de ese host como se describe en la sección anterior Mostrar un host. A continuación, introduce el ETag en la cabecera de la solicitud en If-Match. Aquí, se elimina el tag del host del grupo Piggyback que se especificó cuando se creó el host, y se especifica el tag predefinido API integrations if configured, else Checkmk agent para sustituirlo:
user@host:~$ curl \
--request PUT \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \
--header "If-Match: "57db3792f23bd81ca7447ba4885fa2865d0c78aed4753229b29e179e539da48b"" \
--header "Content-Type: application/json" \
--data '{
"remove_attributes": [
"tag_piggyback"
],
"update_attributes": {
"tag_agent": "cmk-agent"
}
}' \
"$API_URL/objects/host_config/mylinuxserver"Ejecutar un descubrimiento de servicios en un host
Para asegurarte de que un descubrimiento de servicios presta realmente los servicios esperados, en los host Linux y Windows primero debes instalar y registrar sus respectivos agentes de monitorización.
Aquí se realiza un descubrimiento de servicios en el host mylinuxserver con la opción refresh, que corresponde al botón Full service scan de la GUI de Checkmk:
user@host:~$ curl \
--request POST \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '{
"host_name": "mylinuxserver",
"mode": "refresh"
}' \
"$API_URL/domain-types/service_discovery_run/actions/start/invoke"Creación masiva de host
Aquí se crean dos hosts en la carpeta Main > Linux > Production Hosts: el primer host sólo con una dirección IP, y el segundo host con un host padre y dos labels además de su dirección IP:
user@host:~$ curl \
--request POST \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '{
"entries": [
{
"attributes": {
"ipaddress": "192.168.0.130"
},
"folder": "~linux~production_hosts",
"host_name": "mylinuxserver02"
},
{
"attributes": {
"ipaddress": "192.168.0.131",
"parents": [ "router01" ],
"labels": {
"color": "blue-metallic",
"admin": "Fozzie Bear"
}
},
"folder": "~linux~production_hosts",
"host_name": "mylinuxserver03"
}
]
}' \
"$API_URL/domain-types/host_config/actions/bulk-create/invoke"Activar cambios pendientes
Antes de abordar la compleja acción de renombrar un host, es necesario activar todos los cambios acumulados en su entorno de configuración. Aquí se activan todos los cambios del site mysite en una sola acción:
user@host:~$ curl \
--request POST \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '{
"force_foreign_changes": false,
"redirect": false,
"sites": [
"mysite"
]
}' \
"$API_URL/domain-types/activation_run/actions/activate-changes/invoke"Cambiar el nombre de un host
Un nuevo nombre también va a cambiar el host. Por lo tanto, primero obtén el ETag actual del host, por ejemplo de mylinuxserver, como se describe en la sección Mostrar un host, e introdúcelo en la cabecera de la solicitud en If-Match. Aquí se está renombrando el host como mylinuxserver01:
user@host:~$ curl \
--request PUT \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \
--header "If-Match: "a200832df1b3c5ebe8f30809177630abbdcf8f7cbd9d0f69bd9f229b359f4d00"" \
--header "Content-Type: application/json" \
--data '{
"new_name": "mylinuxserver01"
}' \
"$API_URL/objects/host_config/mylinuxserver/actions/rename/invoke"