1. Introduzione
Con l'API REST di Checkmk come interfaccia di programmazione dell'applicazione (API), puoi trasmettere attività al server Checkmk tramite comandi o script con richieste HTTP e farle eseguire - attività che altrimenti eseguiresti in Checkmk tramite la GUI.
Il termine REST nel nome dell'API REST sta per REpresentational State Transfer (trasferimento di stato rappresentativo) e descrive un'architettura per lo scambio di dati su sistemi distribuiti, in particolare per i servizi web. Un'API implementata secondo l'architettura REST segue alcuni principi, ad es. il modello client-server, la comunicazione senza stato e un'interfaccia uniforme. In pratica, l'implementazione avviene preferibilmente tramite il protocollo HTTP, in base al quale le risorse vengono indirizzate tramite l'URI (Uniform Resource Identifier) e accedute tramite i metodi HTTP (GET, POST, PUT, DELETE).
I vantaggi di questi principi possono essere dimostrati dalle funzioni concrete fornite dall'API REST di Checkmk:
Protocollo |
Come sistema di trasporto per la comunicazione viene utilizzato l'Hypertext Transfer Protocol(HTTP/1.1). |
Codifica |
Il formato dei dati è la JavaScript Object Notation(JSON). Il payload delle risposte è serializzato con JSON e codificato in UTF-8. Le informazioni su data e ora sono codificate nel formato ISO-8601 con informazioni valide sul fuso orario. |
Lingua |
L'inglese è la lingua delle etichette, degli identificatori e della documentazione API. |
Autenticazione |
L'accesso all'API viene concesso a un client solo se ha dimostrato la propria autorizzazione tramite l'autenticazione HTTP, ad esempio "Bearer". |
Versione |
L'API è dotata di versioni e utilizza uno schema di numerazione conforme allo standard Semantic Versioning 2.x. Per maggiori dettagli, consulta la sezione sul versioning riportata di seguito. |
Documentazione |
L'API è documentata in una struttura leggibile dalla macchina e in un formato inglese leggibile dall'uomo e include tutte le risorse, i loro parametri di ingresso e di uscita e gli intervalli di valori associati. L'API è creata con la Specifica OpenAPI (OAS) 3.x, un formato della descrizione API destinato in particolare alle API REST. Il documento API creato con questa specifica viene visualizzato dall'utente con ReDoc, un design web reattivo per i documenti OpenAPI. |
Esempio di codice |
Per dimostrarne l'uso, per ogni richiesta viene fornito un codice di esempio per varie applicazioni, ad esempio curl e httpie. |
Visualizzazione degli errori |
In caso di errore, l'API invia codici di stato HTTP numerici e un messaggio diagnostico del problema, che aiuta a identificare le possibili cause delle richieste errate. |
Classificazione delle API REST |
L'API soddisfa tutti e quattro i livelli (da 0 a 3) del Richardson Maturity Model (RMM), che può essere utilizzato per valutare il grado di REST di un'API. Il livello 1 richiede l'introduzione di risorse per consentire la comunicazione tramite l'API a singoli endpoint piuttosto che a uno globale. Il livello 2 è soddisfatto se vengono utilizzati metodi HTTP per le richieste. Al livello 3 (il più alto), l'API è effettivamente auto-documentante, in quanto il server, quando risponde a una richiesta, comunica le possibili azioni successive e le risorse a cui rivolgersi, permettendo così al cliente di scoprire da solo le funzionalità disponibili. Questa fornitura di informazioni aggiuntive è nota anche come "Hypermedia as the Engine of Application State"(HATEOAS). |
Oltre a queste funzioni di utilità generale, l'API REST è destinata a coprire tutte le funzionalità che nelle versioni precedenti di Checkmk venivano fornite tramite GUI e interfaccia di comando.
Per le funzioni che esistono solo nelle edizioni commerciali, come l'accordo sul livello di servizio (SLA) o l'Agent bakery, i metodi API REST associati sono forniti solo in queste edizioni.
 |
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 documentazione dell'API
2.1. Il versionamento
Uno dei vantaggi dell'API REST è che sia il software che la sua documentazione provengono dalla stessa fonte: il documento OpenAPI. Pertanto, la documentazione dell'API corrisponde sempre al software e descrive esattamente ciò che l'API è in grado di fare. Per questo motivo non è necessario descrivere la parte di riferimento delle risorse, dei metodi, dei parametri, ecc. disponibili nella guida dell'utente Checkmk: la documentazione dell'API è disponibile separatamente da questa guida, direttamente nell'istanza Checkmk.
L'API e la sua documentazione sono soggette a versioni e utilizzano uno schema di numerazione a due livelli nel formato X.Y, dove X indica una versione maggiore e Y una versione minore. Una nuova versione minore contiene solo modifiche retroattive che non hanno effetto sulle funzioni esistenti.
Una nuova versione maggiore, invece, contiene modifiche che rendono l'API incompatibile con la versione maggiore precedente (le cosiddette modifiche di rottura). I numeri di versione della versione maggiore e minore fanno parte dell'URL con cui viene inviata una richiesta al server Checkmk. Attualmente l'API REST di Checkmk non utilizza il terzo livello (.Z) dello standard Semantic Versioning per una versione patch.
Si noti che l'API REST segue uno schema di versioning diverso da quello del software Checkmk. Poiché in caso di modifiche incompatibili all'API è necessaria una nuova major release dell'API, questa solitamente non corrisponde al ciclo di rilascio del software Checkmk.
Tuttavia, la correlazione tra le versioni della documentazione API e del software Checkmk è molto semplice, come imparerai nel prossimo capitolo.
2.2. Accesso
La documentazione dell'API REST è disponibile in formato HTML per la visualizzazione in un browser web.
Nella GUI di Checkmk, apri la documentazione dell'API dalla barra di navigazione tramite Help > Developer resources > REST API documentation. La documentazione dell'API viene visualizzata in una nuova finestra (o scheda) del browser. Ne parleremo più dettagliatamente nel prossimo capitolo.
 |
Avrai sicuramente notato che nel menu Help ci sono altre voci che riguardano l'API REST. Con REST API introduction puoi aprire questo articolo. Con REST API interactive GUI puoi aprire un'altra visualizzazione dell'API REST. La voce si chiama GUI perché non solo ti vengono mostrate le funzioni dell'API REST, ma perché puoi anche interagire con l'API direttamente dal browser, ad esempio inviando richieste al server. Introdurremo l'API REST GUI come alternativa all'esecuzione tramite script più avanti nel capitolo sull'API REST GUI. |
2.3. Struttura e contenuti
La documentazione dell'API utilizza un design web reattivo composto da tre sezioni:
La sezione di sinistra, Navigazione, è utilizzata per orientarsi, cercare e saltare rapidamente alla descrizione esatta delle voci della sezione centrale. L'indice contiene una voce per ogni endpoint dell'API. Un endpoint utilizza un URL per fare riferimento alla risorsa che l'API fornisce (es. host), insieme al metodo utilizzato per accedere alla risorsa (es. GET per visualizzare un host). Gli endpoint sono organizzati in diverse cartelle.
La sezione centrale, Content, contiene i dati essenziali della documentazione: tutte le informazioni per definire una richiesta (con parametri, intervalli di valori, valori predefiniti e descrizioni) e le risposte corrispondenti (anch'esse con tutti i dettagli). Le possibili risposte sono visualizzate in colori diversi, a seconda che il codice di stato HTTP restituito segnali un successo o un errore.
La sezione di destra, Request samples, mostra il metodo e l'URL dell'endpoint selezionato nella sezione dei contenuti, seguito da diversi esempi di richieste: il payload in formato JSON (se pertinente all'endpoint) ed esempi di codice, ad esempio per curl, httpie, Python Requests e Python Urllib. Seguono poi le risposte in base al codice di stato HTTP. Tutti gli esempi di codice possono essere copiati negli appunti con il pulsante Copy.
La sezione di navigazione è sincronizzata con le altre due sezioni, il che significa che se scorri verso l'alto o verso il basso nella sezione dei contenuti, la sezione di navigazione scorre automaticamente fino alla voce appropriata dell'indice.
Il responsive web design fa sì che la sezione degli esempi non venga visualizzata in una finestra del browser molto stretta (gli esempi vengono visualizzati sotto il metodo corrispondente) e la sezione di navigazione viene convertita in un menu.
In tutte le sezioni troverai contenuti che puoi mostrare e nascondere, ad esempio le voci degli endpoint nella sezione di navigazione e i parametri annidati nella sezione dei contenuti. Cliccando su > o Expand all puoi mostrare i contenuti nascosti, mentre con ∨ o Collapse all puoi nasconderli nuovamente.
Nel prossimo capitolo scoprirai come utilizzare la documentazione dell'API per creare richieste concrete a partire dalle informazioni, inviare queste richieste al server Checkmk, farle eseguire e monitorare l'esecuzione e i risultati.
3. Utilizzo dell'API
3.1. Autenticazione
Per utilizzare l'API REST nel server Checkmk da un client, quest'ultimo deve dimostrare la propria identità. L'API REST supporta i seguenti metodi di autenticazione: Bearer, server web e Cookie- in questo ordine di precedenza. Ciò significa, ad esempio, che se l'autenticazione con Bearer ha successo, nessuno degli altri metodi verrà controllato.
Autenticazione con Bearer o Header
Per "portatore" si intende il titolare di un'identità. Il client si autentica con le credenziali di un utente impostato sul server Checkmk. Idealmente, si tratta del cosiddetto utente automazione, che viene fornito in Checkmk per l'esecuzione di azioni tramite un'API. L'autenticazione con portatore è consigliata per l'uso negli script.
Per l'autenticazione, hai bisogno del nome utente e della corrispondente password di automazione per gli account macchina, cioè la password dell'utente automazione. Entrambi gli elementi devono essere trasmessi al server Checkmk nell'intestazione di ogni richiesta. In un sito appena creato, l'utente automation sarà già stato creato. Puoi trovarlo, come altri utenti, sotto Setup > Users > Users. Assicurati che i ruoli e i permessi associati all'utente automazione siano impostati in modo da permetterti di eseguire le tue richieste.
Per gli script presentati in questo articolo, l'utente automazione viene sempre utilizzato come esempio predefinito.
Autenticazione del server web
Per l'autenticazione del server web, l'API REST utilizza l'autenticazione HTTP configurata per il server web ("Basic" o "Digest").
Questo metodo di autenticazione è destinato a grandi installazioni di Checkmk con requisiti speciali che si realizzano utilizzando e configurando moduli software per l'autenticazione del server web Apache. Se vuoi utilizzare l'autenticazione del server web, devi riconfigurare il server web Apache del sito Checkmk stesso.
Autenticazione tramite cookie
L'autenticazione tramite cookie è un caso particolare di autenticazione tramite chiave API. Ogni utente di Checkmk che ha effettuato il log in e a cui è stato assegnato un cookie HTTP può utilizzare l'API REST. L'autenticazione tramite cookie viene utilizzata per provare e testare l'API REST GUI. L'esecuzione delle richieste dipende dal fatto che l'account utente di Checkmk disponga dei permessi appropriati.
3.2. Codice di stato HTTP
L'API REST restituisce il codice di stato HTTP per ogni richiesta, che puoi utilizzare per verificare se la richiesta è andata a buon fine. Tutti i possibili codici di stato HTTP per la richiesta sono elencati nella documentazione dell'API.
Nota che il codice di stato HTTP fornisce solo informazioni sull'avvenuta trasmissione della richiesta, ma non sull'avvenuta esecuzione. I comandi vengono eseguiti sul server Checkmk con Livestatus. Per essere sicuro che la richiesta tramite l'API REST faccia davvero ciò che volevi, devi verificare tu stesso il successo. La documentazione dell'API, che puoi aprire con Help > Developer resources > REST API interactive GUI, contiene un esempio di script per questo compito nella sezione "Interrogazioni tramite l'API REST".
3.3. Testare l'API in locale
Per testare l'API REST, è consigliabile effettuare le richieste direttamente dal server Checkmk: in questo esempio, il client che invia la richiesta e il server che la riceve si trovano sullo stesso computer. Se stai lavorando come utente dell'istanza, puoi anche utilizzare variabili locali come $OMD_SITE, che si riferisce al nome del sito.
Nei semplici esempi che seguono, utilizziamo il codice di esempio contenuto nella documentazione API del programma a riga di comando curl, che consente di trasferire dati da o verso un server senza l'interazione dell'utente, ad esempio tramite HTTP.
|
Soprattutto per le richieste complesse, gli esempi di curl possono contenere delle incongruenze e quindi non sempre sono affidabili. Con httpie è disponibile un'alternativa coerente, facile da capire e ben suite per l'uso negli script. |
Il comando curl viene eseguito all'interno di uno script bash. Per la preparazione, crea un file script per ciascuna delle richieste che verranno eseguite nella prossima sezione, nel quale verrà poi copiato il codice di esempio:
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.shL'API REST emette tutte le risposte in un formato JSON a riga singola. Poiché l'output formattato è molto più facile da leggere, gli esempi seguenti mostrano l'output a riga singola formattato in più righe. Esistono diversi siti web e strumenti per il processo del formato JSON, ad esempio il processore JSON a riga di comando jq.
Prima di iniziare, raccogli alcune informazioni di base specifiche per la tua configurazione di Checkmk:
| Variabile | Esempio di valore | Significato |
|---|---|---|
|
|
Il nome dell'host del server Checkmk |
|
|
Il nome dell'istanza Checkmk |
|
|
Il nome dell'utente automazione |
|
|
La password dell'utente dell'automazione |
Queste variabili sono utilizzate nel codice di esempio e devono essere modificate da te prima di inviare una richiesta. Nella tabella precedente troverai anche i valori di esempio utilizzati nel seguito.
3.4. Fare richieste con gli script
Con un esempio semplice dimostreremo ora come utilizzare l'API REST. Crea un host con i suoi servizi utilizzando un totale di quattro richieste. In linea di massima, procedi come faresti con la GUI di Checkmk:
Creare un host
Eseguire una scoperta del servizio sull'host.
Mostra le modifiche in sospeso.
Attiva le modifiche
Creare un host
Apri la documentazione dell'API e seleziona la voce per la creazione di un host (Create a host) nell'area di navigazione sinistra:
Nella parte centrale del pannello puoi vedere i dettagli della richiesta selezionata, l'autenticazione HTTP richiesta (è identica per tutte le richieste tramite API REST) e i parametri obbligatori e opzionali. Il nome dell'host e la cartella in cui deve essere creato sono obbligatori. Per impostazione predefinita, l'host viene creato nella cartella Main. Se vuoi creare l'host in un'altra cartella, devi prima effettuare un'altra richiesta API (Show all folders) per visualizzare le cartelle esistenti e determinare l'ID di quella che vuoi utilizzare.
Nel nostro esempio, l'host myhost123 deve essere creato con l'indirizzo IP 192.168.0.42 nella cartella Main.
Nella documentazione API, clicca sul pulsante curl nell'area degli esempi a destra e poi su Copy per copiare il codice di esempio di curl negli appunti. Apri lo script preparato create_host.sh e incollaci il contenuto degli appunti:
#!/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"Nella prima parte del codice di esempio troverai le variabili d'ambiente, poi viene eseguito il comando curl con il metodo POST sulla risorsa il cui URL è riportato nell'ultima riga. Infine, l'opzione -write-out produce una riga con il codice di stato HTTP. Le righe di header (una delle quali definisce il codice dell'Authenticator) sono seguite dalla sezione dati in cui vengono definiti i parametri per il nuovo host.
Nota che il codice di esempio di curl potrebbe contenere più parametri di quelli necessari per una situazione specifica. Nel nostro esempio non è questo il caso e devi modificare solo i due parametri esistenti, host_name e ipaddress.
Ora modifica il codice di esempio in modo che il risultato sia simile a questo:
#!/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"Esegui lo 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
Promemoria: La singola riga in formato JSON delimitata dalle parentesi graffe viene visualizzata qui in più righe.
L'API restituisce sotto links una selezione di richieste (abbreviate nell'esempio precedente), che possono essere applicate all'host appena creato - come si addice a un'API REST. Infine, l'API restituisce l'ID e il nome (title) del nome host creato, il nome folder (/ per la cartella Main) e il attributes assegnato all'host, compreso l'indirizzo IP.
Infine, viene visualizzata la riga con il codice di stato HTTP. 200 sta per OK e significa che l'azione è stata eseguita con successo.
Eseguire una scoperta del servizio sull'host
Una volta creato l'host myhost123, è possibile scoprire i suoi servizi. Per assicurarsi che la scoperta del servizio fornisca effettivamente i servizi previsti, sugli host Linux e Windows devi prima installare e registrare i rispettivi agenti.
Per eseguire la scoperta del servizio tramite API REST, seleziona la voce appropriata nella documentazione API (Execute a service discovery on a host), copia il codice di esempio nel file di script creato a questo scopo e adattalo.
Puoi copiare la prima parte con le variabili d'ambiente 1:1 dall'esempio precedente. Nel comando curl, cambia il nome dell'host in myhost123 e, se necessario, utilizza il parametro mode per cambiare il tipo di scoperta del servizio.
#!/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"Esegui anche questo script:
OMD[mysite]:~$ ./service_discovery.sh
xxx-status_code=302Il codice di stato HTTP 302 significa che il lavoro in background per la scoperta del servizio è stato inizializzato.
Mostra le modifiche in sospeso
Prima di attivare le modifiche, è necessario un passaggio intermedio: la visualizzazione delle modifiche in sospeso con la richiesta Show all pending changes. Oltre alle modifiche accumulate, l'API REST fornisce anche l'ETag HTTP(entity tag) necessario per attivare le modifiche. Un oggetto non viene modificato tramite l'API REST utilizzando l'ID o il titolo dell'oggetto. Invece, l'ETag generato viene utilizzato per evitare che più richieste concorrenti sovrascrivano i valori dello stesso oggetto.
L'ETag viene restituito nell'intestazione della risposta. Per visualizzare questa intestazione, estendi il codice di esempio per questa richiesta chiamando curl con l'opzione -i (per includere le intestazioni della risposta). Le righe modificate sono contrassegnate nuovamente anche nell'esempio seguente:
#!/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"Dopo l'esecuzione dello script, le linee di intestazione vengono mostrate per prime nell'output:
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
Per chiarezza, l'output è stato abbreviato e sono state contrassegnate solo le righe importanti: la riga dell'header con l'ETag, gli attributi dell'unica modifica in sospeso per creare un host e il codice di stato HTTP per OK. L'ETag ti servirà nel prossimo e ultimo passaggio.
Attiva le modifiche
Infine, è necessario attivare le modifiche. La richiesta appropriata si chiama Activate pending changes.
Nel comando curl, modifica l'header sezioni If-Match e inserisci l'ETag letto nella sezione precedente. Nella sezione dati, modifica il parametro sites e impostalo sul nome del sito su cui attivare le modifiche:
#!/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"Esegui questo 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
Il testo title indica che l'attivazione è stata avviata. Ancora una volta, l'API REST suggerisce due utili richieste di follow-up sotto links: per interrogare lo stato di questa attivazione e per attendere il suo completamento.
3.5. Effettuare richieste tramite la GUI dell'API REST
Con la GUI dell'API REST ottieni una nuova prospettiva sull'API. Con questa GUI puoi interagire direttamente con l'API dal browser inviando richieste al server tramite comandi curl e vedere immediatamente le risposte. Per fare questo, devi fare a meno degli esempi di codice della documentazione dell'API REST nella GUI dell'API: entrambe le visualizzazioni sono ottimizzate per le rispettive funzioni.
La GUI dell'API REST è generata dalla stessa fonte della documentazione dell'API REST - il documento OpenAPI - e quindi fornisce sempre funzioni che corrispondono all'API.
Puoi aprire la GUI API nella GUI Checkmk dalla barra di navigazione, dal menu Help > Developer resources > REST API interactive GUI. La GUI API viene visualizzata in una nuova finestra (o scheda) del browser:
Di seguito ti spieghiamo come puoi eseguire la prima richiesta dell'esempio precedente (creare un host) con l'API REST GUI invece di utilizzare uno script:
Autenticare: la GUI dell'API REST offre una finestra di dialogo per inserire le informazioni di autenticazione dopo aver cliccato sul pulsante Authorize (a destra, sopra la voce relativa alla prima cartella endpoint). Tuttavia, se hai effettuato l'accesso come utente dell'istanza Checkmk, non è necessario inserire alcuna voce, in quanto sei autorizzato a utilizzare l'API REST come utente dell'istanza.
Selezionare l'endpoint: nella cartella Hosts, seleziona l'endpoint Create a host e clicca su Try it out.
Inserisci i valori dei parametri: in Request body sovrascrivi i valori di esempio per
host_nameeipaddress.Invia una richiesta: clicca su Execute.
Controlla la risposta: in Responses vedrai prima il comando curl inviato e l'URL dell'endpoint, poi in Server response verrà visualizzata la risposta con il codice di stato HTTP e in Responses la risposta (formattata su più righe) dell'API REST.
L'API REST GUI ti offre quindi l'opportunità di provare le funzioni dell'API in modo semplice e veloce e di familiarizzare con le funzioni dei valori di input e con le risposte concrete.
3.6. Correzione degli errori
A differenza dell'output di comandi riusciti tramite script mostrato finora, l'API REST mostra gli errori nel modo seguente:
{
"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=401A seconda dell'errore, i parametri visualizzati nell'output possono variare, ma in status viene indicato il codice di stato HTTP e in title viene sempre fornita una breve descrizione della causa dell'errore.
Nella maggior parte dei casi, detail mostrerà informazioni dettagliate, come suggerisce il nome. Nell'esempio precedente, puoi vedere che ci sono modifiche in sospeso in Checkmk, ma che sono state avviate da un altro utente. Per impostazione predefinita, solo le modifiche che sono state effettuate anche tramite l'API possono essere attivate tramite l'API.
Nell'esempio successivo, i messaggi utili si trovano anche nelle informazioni dettagliate:
{
"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=400Il problema nell'esempio precedente è che il valore di un parametro non rientra nell'intervallo di valori validi perché il nome host contiene una barra.
Il numero di errori possibili è ovviamente molto più ampio dei due che abbiamo presentato qui; tuttavia, puoi vedere dagli esempi mostrati che nel suo output l'API REST di solito fornisce informazioni sufficienti sulla causa e quindi ti dà indizi per iniziare l'analisi e la risoluzione dei problemi.
4. Proteggere l'API
Poiché durante l'accesso tramite l'API REST possono essere trasferiti dati sensibili e, a seconda dell'autorizzazione dell'utente automazione, potrebbero essere apportate modifiche considerevoli a Checkmk, è necessario proteggere l'accesso di conseguenza. Qui troverai alcune delle opzioni disponibili:
Checkmk su HTTPS: utilizza l'API esclusivamente su Hypertext Transfer Protocol Secure (HTTPS), altrimenti i nomi degli utenti, le password e i dati di configurazione saranno trasmessi in chiaro sulla rete.
Assegna all'utente automazione una password di lunghezza sufficiente. Dato che la password viene solitamente archiviata solo in uno script, puoi facilmente assegnarne una molto lunga.
Assicurati di prestare molta attenzione al concetto di autorizzazione per gli script che utilizzi per effettuare le richieste all'API. Gli script possono contenere dati sensibili come dati di configurazione, password, ecc.
5. Esempi con le richieste dell'API REST
In questo capitolo troverai degli esempi che mostrano come eseguire le azioni più comuni utilizzando l'API REST. Gli esempi si basano ancora una volta sul codice di esempio del programma a riga di comando curl. A differenza della procedura descritta nel capitolo Usare l'API, però, qui le richieste vengono effettuate come comandi curl a riga di comando anziché tramite script. Questo ti permette di provare subito i nostri esempi, dopo averli personalizzati per adattarli al tuo ambiente.
Per presentare i comandi in modo chiaro, abbiamo mostrato solo le linee del codice di esempio che sono assolutamente necessarie per l'esecuzione del comando.
Come per il codice di esempio nella documentazione delle API, gli esempi di questo capitolo contengono variabili per assemblare l'URL di base dell'API REST sul tuo server Checkmk e per impostare le credenziali dell'utente dell'automazione per l'autenticazione Bearer utilizzata:
| Variabile | Valore di esempio | Descrizione |
|---|---|---|
|
|
Nome del server Checkmk |
|
|
Nome dell'istanza Checkmk |
|
|
URL di base dell'API REST |
|
|
Nome dell'utente di automazione |
|
|
Password dell'utente automazione |
Prima di inviare i comandi di curl, puoi adattare le variabili d'ambiente utilizzando i seguenti comandi di 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. Host e cartelle
Le richieste descritte in questo capitolo si trovano nella documentazione API nelle sottocartelle Hosts e Folders. I titoli dei rispettivi endpoint contenuti nella documentazione API sono i seguenti.
Mostra tutte le cartelle
Qui vengono visualizzate tutte le cartelle del Setup - ricorsivamente a partire dalla cartella Main -senza elencare gli host che contengono:
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"Mostra tutti gli host in una cartella
Qui vengono richiesti gli host della sottocartella Main > Linux:
user@host:~$ curl \
--request GET \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \
"$API_URL/objects/folder_config/~linux/collections/hosts"Creare una cartella
Qui viene creata una sottocartella Production Hosts in Main > Linux- nel file system come la directory production_hosts. Alla nuova cartella viene quindi assegnato il tag host Productive system dal gruppo di tag host predefinito 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"Creare un host
Qui, nella cartella Main > Linux > Production Hosts, viene creato l'host mylinuxserver con l'indirizzo IP 192.168.0.123 e il tag 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"Mostrare un host
Visualizzando un host, riceverai un elenco degli attributi ad esso assegnati. Questo fornisce anche l'ETag HTTP(tag entità) che ti serve per poter modificare un host. Puoi trovare maggiori informazioni sull'ETag nella sezione Mostra le modifiche in sospeso.
L'ETag viene restituito nell'intestazione della risposta. Per visualizzare questa intestazione, chiama curl con l'opzione -v (per verbose). In questo caso viene interrogato l'host mylinuxserver e dalla risposta viene mostrata solo la riga contenente l'ETag:
user@host:~$ curl -vG \
--request GET \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \
"$API_URL/objects/host_config/mylinuxserver"
...
< ETag: "57db3792f23bd81ca7447ba4885fa2865d0c78aed4753229b29e179e539da48b"
...Aggiornare un host
Prima di effettuare la modifica, ottieni l'ETag dell'host come descritto nella sezione precedente Mostra un host. Inserisci quindi l'ETag nell'header della richiesta sotto If-Match. In questo caso, il tag host del gruppo Piggyback specificato al momento della creazione dell'host viene eliminato e il tag predefinito API integrations if configured, else Checkmk agent viene specificato per sostituirlo:
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"Esecuzione di una scoperta del servizio su un host
Per assicurarti che la scoperta del servizio fornisca effettivamente i servizi previsti, sugli host Linux e Windows devi prima installare e registrare i rispettivi agenti di monitoraggio.
In questo caso, la scoperta del servizio viene eseguita sull'host mylinuxserver con l'opzione refresh, che corrisponde al pulsante Full service scan nella GUI di 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"Creazione massiccia di host
Qui vengono creati due host nella cartella Main > Linux > Production Hosts: il primo host con solo un indirizzo IP e il secondo host con un host padre e due etichette oltre all'indirizzo 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"Attiva le modifiche in sospeso
Prima di affrontare la complessa azione di rinominare un host, è necessario attivare tutte le modifiche che si sono accumulate nel suo ambiente di configurazione. Qui vengono attivate le modifiche per il sito mysite in un'unica azione:
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"Rinominare un host
Un nuovo nome cambierà anche l'host. Pertanto, per prima cosa ottieni l'ETag attuale dell'host, ad es. da mylinuxserver, come descritto nella sezione Mostrare un host, e inseriscilo nell'header sezioni della richiesta sotto If-Match. Qui l'host viene rinominato come 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"