Checkmk Conference #6: Benvenuti nel mondo delle API!

Il lancio di Checkmk 2.0 segnerà anche la fine dell'attuale Web-API. Con la nuova versione introdurremo la nostra nuova REST-API, che semplificherà le operazioni quotidiane di Checkmk, come spiegato da Christoph Rauch nel suo intervento alla Checkmk Conference #6. Tuttavia, l'attuale Web-API non scomparirà immediatamente con la 2.0, ma continuerà ad essere supportata fino a Checkmk 1.8.

A lungo termine vogliamo utilizzare la nuova REST-API per coprire tutte le funzioni attualmente disponibili in Checkmk, sia attraverso la GUI che attraverso la riga di comando. Il nostro obiettivo è quello di rendere la nuova API il più semplice possibile per l'utente. Questo per consentire anche agli utenti meno esperti di poter recuperare i propri valori dall'API, ad esempio attraverso messaggi di errore di facile comprensione e una documentazione completa dell'API - in sintesi, attraverso un'API di facile comprensione.

Con l'API vogliamo anche rendere l'automazione molto più semplice. Secondo Christoph, questo implica una documentazione perfetta, da aggiornare con regolarità. Per garantire ciò, genereremo automaticamente la documentazione e le specifiche direttamente dal codice sorgente. Attribuiamo inoltre grande importanza alla retrocompatibilità della nuova API.

Christoph ha anche sottolineato che la nuova API è conforme agli standard attuali. Questo ha il vantaggio che l'utente può fare affidamento su software esistente se desidera programmare o utilizzare il proprio client API. JSON si è affermato come formato per il trasporto dei dati. Utilizziamo anche la current OpenAPI Specification, OpenAPI 3.0 (OAS 3.0), per descrivere la nostra API, come ha spiegato ulteriormente Christoph. L'API si basa anche su HTTP/1.1. Inoltre, dovrebbe rispettare il terzo livello del Richardson Maturity Model. Questo consente, ad esempio, di inviare link nelle risposte dell'API contenenti ulteriori azioni.

In Checkmk 2.0 è prevista l'implementazione nella nuova API della Agent Bakery, della BI, della configurazione di cartelle, host, servizi e gruppi, nonché di set di regole. Tutto il resto sarà fornito con il tempo.

In una dimostrazione Christoph ha anche mostrato la documentazione generata automaticamente con la nuova API, e come funzioni la configurazione di nuovi host con la nuova API. La documentazione fornisce esempi concreti che dovrebbero facilitare all'utente l'esecuzione delle singole fasi della configurazione.

In arrivo la nuova Check-API

La nuova API REST non è tuttavia l'unica innovazione che stiamo apportando alle fondamenta di Checkmk. Lo sviluppatore Moritz Kiemer si sta occupando, ad esempio, della nuova Check-API. Sebbene oggi esistano quasi 2.000 plug-in ufficiali per Checkmk, la precedente Check-API risale a un periodo in cui le estensioni erano molto meno numerose. Inoltre, la Check-API non è cambiata nel corso degli anni. Per questo motivo abbiamo deciso che era urgentemente necessario procedere a una revisione. L'obiettivo è quello di trattare in futuro i plug-in di controllo come moduli che vengono importati da un'API definita in base alle versioni.

Moritz ha già presentato il nuovo assetto all'ultima conferenza. Per Checkmk 2.0, la trasformazione dei plug-in in moduli Python, l'auto-migrazione della maggior parte dei plug-in esistenti e il passaggio completo da Python 2 a Python 3 dovrebbero essere all'ordine del giorno.

Quest'anno Moritz ha presentato nel suo intervento alla conferenza i principi della nuova Check-API. Questi includono la definizione di convenzioni e la coerenza, soprattutto per quanto riguarda la denominazione, che a sua volta deve anche essere esplicativa. Un altro concetto alla base della nuova API, è che cose diverse che svolgono la stessa funzione dovrebbero avere lo stesso aspetto. Attualmente in Checkmk esistono diverse procedure che portano allo stesso risultato. Questo ha lo svantaggio che non esiste una best practice generalmente applicabile per questi casi, e può essere fonte di confusione guardare il codice corrispondente. Moritz ha promesso che questa situazione cambierà con la nuova Check-API.

Evitare le opzioni non necessarie

Un altro obiettivo della nuova Check-API è che le funzioni implicite funzionino come previsto originariamente dallo sviluppatore. Ciò include anche la riduzione delle opzioni non necessarie. Pertanto, non dovrebbero più essere necessarie due procedure diverse per eseguire esattamente la stessa funzione. Quindi, i check della versione 2.0 non agiranno più sia come funzioni che come generatori, ma solo come generatori, come ha spiegato Moritz.

Un altro vantaggio della nuova Check-API è che rende visibili gli errori di programmazione in una fase preliminare, e non quando sono in esecuzione. L'inserimento dei check nei moduli Python dovrebbe semplificare i test e consentire di eseguirli in modo indipendente.

In generale, la nuova API aiuta a semplificare lo sviluppo dei check. Allo stesso tempo, per gli utenti cambierà il meno possibile, poiché una migrazione automatica svolge la maggior parte del lavoro. Secondo Moritz, questa operazione è fallita solo in 63 dei 1.920 check plug-in, il che significa che ha funzionato per oltre il 96% (e questi 63 check plug-in erano piuttosto complessi). Nel Werk #10601 Moritz ha creato un elenco di cause che possono causare problemi con la migrazione automatica dei plug-in scritti in autonomia.

Abbiamo in programma di migrare i check rimanenti nelle prossime settimane, dopodiché vogliamo condividere con voi le nostre scoperte, e valutare le opzioni per assistere i nostri utenti durante la migrazione.

Nel prossimo articolo riceverete tutte le notizie sulla nostra nuova diagnostica di supporto e sulle opzioni che Checkmk 2.0 ha in serbo per voi per testare in anticipo nuove funzioni e release.