1. Introduzione
Con l'API REST di Checkmk come interfaccia di programmazione dell'applicazione (API), puoi inviare attività al server Checkmk tramite comandi o script con richieste HTTP e farle eseguire — attività che altrimenti dovresti eseguire in Checkmk tramite la GUI.
Il termine REST nel nome dell'API REST sta per REpresentational State Transfer 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 determinati principi, ad esempio il modello client-server, la comunicazione stateless e un'interfaccia uniforme. In pratica l'implementazione avviene preferibilmente tramite il protocollo HTTP, in cui le risorse vengono indirizzate tramite l'Uniform Resource Identifier (URI) e vi si accede utilizzando i metodi HTTP (GET, POST, PUT, DELETE).
Questo per quanto riguarda i principi del REST. I vantaggi di questi principi possono essere dimostrati dalle caratteristiche 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 |
Come formato dati viene utilizzato il JavaScript Object Notation (JSON). Il payload delle risposte viene serializzato con JSON e codificato in UTF-8. Le informazioni relative a data e ora sono codificate nel formato ISO-8601 con informazioni valide sul fuso orario. |
Lingua |
L'inglese è la lingua utilizzata per le etichette, gli identificatori e la documentazione dell'API. |
Autenticazione |
L'accesso all'API è concesso a un client solo se ha dimostrato la propria autorizzazione tramite autenticazione HTTP, ad esempio "Bearer". |
Versioni |
L'API è versionata e utilizza uno schema del versionamento conforme allo standard Semantic Versioning 2.x. Per i dettagli, consulta la sezione sul versioning qui sotto. |
Documentazione |
L'API è documentata in una struttura leggibile da computer e in un formato leggibile dall'uomo, in inglese, e include tutte le risorse, i loro parametri di input e output e i relativi intervalli di valori. L'API è creata con la specifica OpenAPI (OAS) 3.x, un formato della descrizione API pensato appositamente per le API REST. Il documento API creato con questa specifica viene mostrato all'utente tramite ReDoc, un web design 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 relativo al 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 quanto REST contenga 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 per le richieste vengono utilizzati metodi HTTP. Al livello 3 (il più alto), l'API è di fatto autodocumentante, in quanto il server, quando risponde a una richiesta, comunica tutte le possibili azioni successive e le risorse a cui rivolgersi, consentendo così al client di scoprire autonomamente le funzionalità disponibili. Questa fornitura di informazioni aggiuntive è nota anche come "Hypermedia as the Engine of Application State" (HATEOAS). |
Oltre a queste funzioni generali di comodità, l'API REST è pensata per coprire tutte le funzionalità che nelle versioni precedenti di Checkmk erano fornite tramite la GUI e un'interfaccia a comandi.
Per le funzionalità presenti solo nelle edizioni commerciali, come l'accordo sul livello di servizio (SLA) o l'agent bakery, anche i metodi API REST associati sono disponibili 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. Gestione delle versioni
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. Non è quindi necessario descrivere la parte di riferimento delle risorse disponibili, dei metodi, dei parametri ecc. nel manuale dell'utente di Checkmk: troverai invece la documentazione dell'API separatamente da questo manuale, direttamente nel tuo sito Checkmk.
L'API con la sua documentazione è versionata e utilizza uno schema del versionamento a due livelli nel formato X.Y, dove X sta per una versione maggiore e Y per una versione minore.
Una nuova versione minore contiene solo modifiche retrocompatibili che non hanno alcun 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 delle versioni maggiori e minori fanno parte dell'URL con cui viene inviata una richiesta al server.
L'API REST di Checkmk attualmente non utilizza il terzo livello (.Z) dello standard di versionamento semantico per una versione patch.
Tieni presente che l'API REST segue uno schema del versionamento diverso da quello del software Checkmk. Poiché è necessaria una nuova versione maggiore dell'API in caso di modifiche incompatibili all'API, questa di solito non corrisponde al ciclo di rilascio del software Checkmk.
Tuttavia, la correlazione tra le versioni della documentazione dell'API e del software Checkmk è molto semplice, come vedrai 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 del browser (o scheda del browser). Ne parleremo più nel dettaglio nel prossimo capitolo.
 |
Avrai sicuramente notato che nel menu Help ci sono altre voci relative all'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 poiché non solo ti vengono mostrate le funzioni dell'API REST, ma puoi anche interagire con l'API direttamente dal browser, ad esempio inviando richieste al server. Introdurremo la GUI dell'API REST come alternativa all'esecuzione tramite script più avanti nel capitolo dedicato alla GUI dell'API REST. |
2.3. Struttura e contenuto
La documentazione dell'API utilizza un web design reattivo composto da tre sezioni:
La sezione a sinistra, Navigazione, serve per orientarsi, effettuare ricerche e passare rapidamente alla descrizione esatta delle voci nella sezione centrale. L'indice contiene una voce per ogni endpoint API. Un endpoint utilizza un URL per fare riferimento alla risorsa fornita dall'API (ad es. host), insieme al metodo utilizzato per accedere alla risorsa (ad es. GET per visualizzare un host). Gli endpoint sono organizzati in diverse cartelle.
La sezione centrale, Contenuto, contiene i dati concreti della documentazione: tutte le informazioni per definire una richiesta (con parametri, intervalli di valori, valori predefiniti e descrizioni) e le risposte corrispondenti (anche con tutti i dettagli). Le possibili risposte sono visualizzate in colori diversi, a seconda che il codice di stato HTTP restituito indichi un esito positivo o un errore.
La sezione a destra, "Request samples", mostra il metodo e l'URL per l'endpoint selezionato nella sezione "Content", seguiti da diversi esempi di richieste: il payload in formato JSON (se rilevante per l'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 lo scorrimento delle 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 alla voce corrispondente nell'indice.
Il responsive web design fa sì che la sezione degli esempi non appaia in una finestra del browser molto stretta (gli esempi vengono quindi visualizzati sotto il metodo corrispondente) e che la sezione di navigazione si trasformi in un menu.
In tutte le sezioni troverai contenuti che puoi mostrare e nascondere, ad esempio le voci relative agli endpoint nella sezione di navigazione e i parametri nidificati 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 imparerai come utilizzare la documentazione API per creare richieste concrete a partire dalle informazioni, inviare queste richieste al server Checkmk, farle eseguire e monitorarne l'esecuzione e i risultati.
3. Utilizzo dell'API
3.1. Autenticazione
Per poter utilizzare l'API REST nel server Checkmk da un client, il client 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 va a buon fine, nessuno degli altri metodi verrà verificato.
Autenticazione Bearer o Header
"Bearer" significa il possessore di un'identità. Il client si autentica con le credenziali di un utente configurato sul server Checkmk. Idealmente, si tratta del cosiddetto utente automazione, fornito in Checkmk per l'esecuzione di azioni tramite un'API. L'autenticazione Bearer è consigliata per l'uso negli script.
Per l'autenticazione, hai bisogno del nome utente e della password di automazione corrispondente per gli account macchina, ovvero la password dell'utente automazione. Entrambi gli elementi di informazione devono essere trasmessi al server Checkmk nell'intestazione di ogni richiesta.
Puoi trovare gli utenti automazione, come gli altri utenti, all'indirizzo Setup > Users > Users. Assicurati che i ruoli e i permessi associati all'utente automazione siano impostati in modo da consentirti di eseguire le tue richieste.
Per gli script presentati in questo articolo, viene sempre utilizzato come esempio un utente automazione chiamato automation.
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 Checkmk con requisiti speciali che vengono realizzati 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 dell'istanza Checkmk stessa.
Autenticazione tramite cookie
L'autenticazione tramite cookie è un caso speciale di autenticazione tramite chiave API. Ogni utente Checkmk che ha effettuato l'accesso a Checkmk 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 tramite la GUI. La possibilità di eseguire le richieste dipende dal fatto che il tuo account utente 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. L'elenco dei possibili codici di stato HTTP per la richiesta è riportato nella documentazione dell'API.
Tieni presente che il codice di stato HTTP fornisce solo informazioni sulla trasmissione riuscita della richiesta, ma non sull'esecuzione riuscita. 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 questa attività nella sezione "Query tramite l'API REST".
3.3. Testare l'API localmente
Per testare l'API REST, è consigliabile effettuare le richieste direttamente dal server Checkmk, ovvero, 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 fa riferimento al nome dell’istanza.
Nei seguenti semplici esempi utilizziamo il codice di esempio contenuto nella documentazione API per il programma da 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 potrebbero contenere incongruenze e quindi non essere sempre affidabili. Con httpie è disponibile un'alternativa coerente, facile da capire e particolarmente adatta all'uso negli script. |
Il comando curl viene eseguito all'interno di uno script bash.
Per prepararti, crea un file di script per ciascuna delle richieste da eseguire nella sezione successiva, in cui verrà successivamente copiato il codice di esempio:
L'API REST restituisce tutte le risposte in un formato JSON su una singola riga.
Poiché l'output formattato rende la lettura molto più semplice, gli esempi seguenti mostrano l'output su una singola riga formattato su più righe.
Esistono vari siti web e strumenti per elaborare il formato JSON, ad esempio il processore JSON da riga di comando jq.
Prima di iniziare, raccogli alcune informazioni di base specifiche della tua configurazione Checkmk:
| Variabile | Valore di esempio | Significato |
|---|---|---|
|
|
Il nome host del server Checkmk |
|
|
Il nome dell'istanza Checkmk |
|
|
Il nome dell'utente automazione |
|
|
La password dell'utente automazione |
Queste variabili sono usate nel codice di esempio e devono essere modificate da te prima di inviare una richiesta. Nella tabella qui sopra troverai anche i valori di esempio usati di seguito.
3.4. Effettuare richieste utilizzando gli script
Con un semplice esempio ti mostreremo ora come utilizzare l'API REST. Crea un host con i relativi servizi utilizzando un totale di quattro richieste. In linea di principio, procedi allo stesso modo che faresti con la GUI di Checkmk:
Crea un host
Esegui la scoperta del servizio sull'host
Mostra le modifiche in sospeso
Attiva le modifiche
Creazione di un host
Apri la documentazione API e seleziona la voce per la creazione di un host (Create a host) nell'area di navigazione a sinistra:
Nella parte centrale del pannello puoi vedere i dettagli della richiesta selezionata, quale autenticazione HTTP è richiesta (è la stessa per tutte le richieste tramite l'API REST) e i parametri obbligatori e facoltativi. 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, potrebbe essere necessario prima effettuare un'altra richiesta API (Show all folders) per effettuare la visualizzazione delle cartelle esistenti e determinare l'ID di quella che desideri utilizzare.
Nel nostro esempio, l'host myhost123 deve essere creato con l'indirizzo IP 192.168.0.42 nella cartella Main.
Nella documentazione dell'API, clicca sul pulsante curl nell'area degli esempi a destra e poi clicca su Copy per copiare il codice di esempio curl negli appunti.
Apri lo script preparato create_host.sh e incolla il contenuto degli appunti al suo interno:
Nella prima parte del codice di esempio troverai le variabili d'ambiente, poi segue il comando curl con il metodo POST sulla risorsa il cui URL si trova nell'ultima riga.
L'opzione -write-out infine restituisce una riga con il codice di stato HTTP.
Le righe di intestazione (una delle quali definisce l'autenticazione HTTP) sono seguite dalla sezione dati in cui sono definiti i parametri per il nuovo host.
Tieni presente che il codice di esempio di curl potrebbe contenere più parametri di quelli che ti servono in una situazione specifica.
Nel nostro esempio non è così e devi solo modificare i due parametri esistenti, host_name e ipaddress.
Ora modifica il codice di esempio in modo che il risultato sia simile a questo:
Esegui lo script:
Promemoria: la singola riga in formato JSON delimitata dalle parentesi graffe viene visualizzata qui su più righe.
L'API restituisce sotto links una selezione di richieste (abbreviate nel nostro esempio sopra), 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) dell'host creato, il nome dell'folder (/ per la cartella Main) e l'attributese assegnata 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'operazione è stata eseguita con successo.
Esegui la scoperta del servizio sull'host
Una volta creato l'myhost123 dell'host, è possibile individuare i suoi servizi.
Per assicurarti che una 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, usa il parametro mode per modificare il tipo di scoperta del servizio.
Esegui anche questo script:
In questo caso, il codice di stato HTTP 303 significa che il processo in background per la scoperta del servizio è stato inizializzato.
Mostra le modifiche in sospeso
Prima di attivare le modifiche, è necessario un passaggio intermedio: visualizzare le modifiche in sospeso con la richiesta Show all pending changes. Oltre alle modifiche accumulate, l'API REST fornisce anche l'HTTP ETag (entity tag) necessario per attivare tali modifiche. Un oggetto non viene modificato tramite l'API REST utilizzando l'ID o il titolo dell'oggetto. Viene invece utilizzato l'ETag generato per impedire 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:
Dopo l'esecuzione dello script, le righe dell'intestazione vengono mostrate per prime nell'output:
Per chiarezza, l'output è stato abbreviato e sono state evidenziate solo le righe importanti: la riga di intestazione con l'ETag, gli attributi dell'unica modifica in sospeso per creare un host e il codice di stato HTTP per OK.
Avrai bisogno dell'ETag nel prossimo e ultimo passaggio.
Attiva le modifiche
Infine, le modifiche devono essere attivate. La richiesta appropriata si chiama Activate pending changes.
Nel comando curl, modifica la riga di intestazione If-Match e inserisci l'ETag letto nella sezione precedente.
Nella sezione dati modifica il parametro sites e impostalo sul nome dell'istanza su cui devono essere attivate le modifiche:
Esegui questo script:
Il testo "title" indica che l'attivazione è stata avviata.
Anche in questo caso, l'API REST suggerisce due utili richieste successive alla voce "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 l'interfaccia grafica dell'API REST ottieni una nuova prospettiva sull'API. Con questa interfaccia puoi interagire direttamente con l'API dal browser inviando richieste al server tramite comandi curl e vedere immediatamente le risposte. Per farlo, devi fare a meno degli esempi di codice della documentazione dell'API REST nell'interfaccia grafica dell'API: entrambe le visualizzazioni sono ottimizzate per le rispettive funzioni.
L'interfaccia GUI dell'API REST viene generata dalla stessa fonte della documentazione dell'API REST — il documento OpenAPI — e quindi fornisce sempre funzioni che corrispondono all'API.
Puoi aprire l’API GUI nella GUI di Checkmk dalla barra di navigazione, menu “Help > Developer resources > REST API interactive GUI”. L’API GUI viene visualizzata in una nuova finestra del browser (o scheda del browser):
Di seguito ti spieghiamo come eseguire la prima richiesta dell'esempio sopra riportato (creare un host) con la GUI dell'API REST invece di usare uno script:
Autenticazione: L'interfaccia grafica dell'API REST offre una finestra di dialogo per inserire le informazioni di autenticazione dopo aver cliccato sul pulsante "Authorize" (sul lato destro sopra la voce della prima cartella endpoint). Tuttavia, se hai effettuato l'accesso come utente dell’istanza, non devi inserire nulla lì, poiché sei autorizzato a utilizzare l'API REST come utente Checkmk tramite autenticazione tramite cookie.
Seleziona 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 viene visualizzata la risposta con il codice di stato HTTP e in Responses con la risposta dell'API REST (formattata su più righe).
La GUI dell'API REST 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 dei comandi riusciti tramite script mostrati finora, l'API REST ti 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.
Tuttavia, in status il codice di stato HTTP e in title ricevi sempre una breve descrizione della causa dell'errore.
Nella maggior parte dei casi, detail ti mostrerà informazioni dettagliate, come suggerisce il nome.
Nell'esempio sopra, puoi vedere che ci sono modifiche in sospeso in Checkmk, ma queste 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 seguente, i messaggi di aiuto 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 sopra riportato è che il valore di un parametro non rientra nell'intervallo di valori validi perché il nome host contiene una barra.
Il numero di possibili errori è ovviamente molto maggiore dei due che abbiamo presentato qui. Tuttavia, dagli esempi mostrati puoi vedere che nell'output l'API REST fornisce solitamente informazioni sufficienti sulla causa e quindi ti dà indizi per iniziare l'analisi e la risoluzione dei problemi.
4. Protezione dell'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 significative a Checkmk, è necessario proteggere tale accesso in modo adeguato. Qui trovi alcune delle opzioni disponibili:
Checkmk su HTTPS: Utilizza l'API esclusivamente tramite Hypertext Transfer Protocol Secure (HTTPS), altrimenti nomi utente, password e anche i dati di configurazione verranno trasmessi in chiaro sulla rete.
Assegna all’utente automazione una password di lunghezza sufficiente. Poiché la password viene solitamente memorizzata solo in uno script, puoi facilmente assegnarne una molto lunga.
Assicurati di prestare particolare attenzione al concetto di autorizzazione per gli script che utilizzi per inviare richieste all'API. Gli script potrebbero contenere dati sensibili come dati di configurazione, password, ecc. Assicurati quindi che solo gli utenti e i gruppi autorizzati possano leggere questi script.
5. Esempi con richieste API REST
In questo capitolo troverai esempi che mostrano come eseguire le azioni più comuni utilizzando l'API REST.
Gli esempi si basano ancora una volta sul codice di esempio per il programma da riga di comando curl.
A differenza della procedura descritta nel capitolo Utilizzo dell'API, tuttavia, qui le richieste vengono effettuate come comandi curl dalla riga di comando anziché tramite script.
Questo ti permette di provare subito i nostri esempi, dopo averli personalizzati in base al tuo ambiente.
Per presentare i comandi in modo chiaro, abbiamo riportato solo le righe del codice di esempio che sono assolutamente necessarie per l'esecuzione del comando.
Come per il codice di esempio nella documentazione dell'API, gli esempi in questo capitolo contengono variabili per assemblare l'URL di base per l'API REST sul tuo server Checkmk e per impostare le credenziali dell'utente 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 automazione |
|
|
Password dell'utente automazione |
Prima di eseguire i comandi curl, puoi personalizzare le variabili in base al tuo ambiente utilizzando i seguenti comandi shell:
5.1. Host e cartelle
Le richieste descritte in questo capitolo sono disponibili nella documentazione API nelle sottocartelle Hosts e Folders. I titoli dei rispettivi endpoint contenuti nella documentazione API corrispondono alle seguenti intestazioni.
Mostra tutte le cartelle
Qui vengono visualizzate tutte le cartelle presenti nel Setup — in modo ricorsivo a partire dalla cartella Main — senza creare un elenco degli host che contengono:
Mostra tutti gli host in una cartella
Qui vengono richiesti gli host nella sottocartella Main > Linux:
Crea una cartella
Qui viene creata una sottocartella Production Hosts in Main > Linux — nel file system come directory production_hosts.
Alla nuova cartella viene quindi assegnato il tag host Productive system dal gruppo di tag host predefinito Criticality:
Crea 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:
Mostra un host
Visualizzando un host ricevi un elenco degli attributi ad esso assegnati. Questo fornisce inoltre l'HTTP ETag (entity tag) necessario per poter modificare un host. Puoi trovare ulteriori informazioni sull'ETag nella sezione Mostra modifiche in sospeso.
L'ETag viene restituito nell'intestazione della risposta.
Per visualizzare questa intestazione, chiama curl con l'opzione -v (per la modalità verbosa).
Qui viene interrogato l'host mylinuxserver e dalla risposta viene mostrata solo la riga contenente l'ETag:
Aggiorna un host
Prima di apportare la modifica, ottieni l'ETag di quell'host come descritto nella sezione precedente Mostra un host.
Inserisci quindi l'ETag nell'intestazione della richiesta sotto If-Match.
Qui, il tag host del gruppo Piggyback specificato al momento della creazione dell'host viene eliminato e viene specificato il tag predefinito API integrations if configured, else Checkmk agent per sostituirlo:
Esegui la 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.
Qui viene eseguita la scoperta del servizio sull'host mylinuxserver con l'opzione tabula_rasa, che corrisponde al pulsante Remove all and find new nella GUI di Checkmk:
Crea host in modo massivo
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 al suo indirizzo IP:
Attiva le modifiche in sospeso
Prima di poter affrontare l'operazione complessa di rinominare un host, è necessario attivare tutte le modifiche che si sono accumulate nel suo ambiente di configurazione.
Qui le modifiche per l'istanza mysite vengono tutte attivate con un'unica operazione:
Rinomina un host
Anche un nuovo nome cambierà l'host.
Pertanto, ottieni prima l'ETag attuale dell'host, ad esempio da mylinuxserver, come descritto nella sezione Mostra un host, e inseriscilo nell'intestazione della richiesta sotto If-Match.
Qui l'host viene rinominato come mylinuxserver01: