Checkmk Conference #6: Willkommen in der neuen API-Welt

Wenn wir Checkmk 2.0 launchen, wird das auch das Ende der aktuellen Web-API einläuten. Mit der neuen Version führen wir nämlich unsere neue REST-API ein, die den Alltagsbetrieb von Checkmk erleichtern soll, wie Christoph Rauch in seinem Vortrag auf der Checkmk Konferenz #6 erklärte. Die aktuelle Web-API wird jedoch mit 2.0 nicht gleich verschwinden, sondern noch bis Checkmk 1.8 unterstützt werden.

Langfristig wollen wir mit der neuen REST-API alle aktuellen Funktionen abdecken, die derzeit in Checkmk möglich sind – sei es über die GUI oder über die Kommandozeile. Dabei verfolgen wir das Ziel, die neue API möglichst einfach für den Anwender zu gestalten. Das bedeutet, dass auch weniger erfahrene Nutzer, ihre Werte aus der API schöpfen können, etwa durch leicht verständliche Fehlermeldungen, eine komplette Dokumentierung der API sowie ein nachvollziehbares Verhalten der API.

Ebenso wollen wir die Automatisierung mit der API deutlich einfacher gestalten. Dazu gehört laut Christoph eine perfekte Dokumentation, die außerdem immer aktuell sein sollte. Um dies sicherzustellen, werden wir die Dokumentation und die Spezifikationen automatisch direkt aus dem Quellcode generieren. Einen großen Wert legen wir auch auf die Rückwärtskompatibilität der neuen API.

Christoph betonte außerdem, dass die neue API gängigen Standards entspricht. Dies hat den Vorteil, dass der Anwender auf bestehende Software zurückgreifen kann, wenn er einen eigenen API-Client programmieren oder verwenden will. Für den Datentransport hat sich hier das JSON als Format durchgesetzt. Wir nutzen zudem die aktuelle OpenAPI Specification OpenAPI 3.0 (OAS 3.0), um unsere API zu beschreiben, wie Christoph weiter erläuterte. Außerdem basiert die API auf http/1.1. Sie soll zudem der dritten Stufe des Richardson Maturity Model gerecht werden. Damit lassen sich zum Beispiel Links in den Antworten der API versenden, die weitere Aktionen enthalten.

Mit Checkmk 2.0 sollen bereits die Agent Bakery, die BI sowie die Konfiguration von Ordnern, Hosts, Services und Gruppen sowie die Regel-Sets in die neue API implementiert sein. Ebenso wir bis dahin gewisse API-URLs den Livestatus von Services und Hosts liefern können. Alles weitere werden wir dann mit der Zeit nachliefern.

In einer Demo zeigte Christoph außerdem die automatisch generierte Dokumentation mit der neuen API und wie die Konfiguration von neuen Hosts mit der neuen API funktioniert. So liefert die Dokumentation direkt Beispiele, die es dem Nutzer erleichtern sollen, die einzelnen Schritte durchzuführen.

Die neue Check-API kommt

Die neue REST-API ist aber nicht die einzige Neuerung, die wir am Fundament von Checkmk vornehmen. Entwickler Moritz Kiemer kümmert sich beispielsweise um die neue Check-API. Obwohl es mittlerweile fast 2.000 offizielle Plugins für Checkmk gibt, stammt die bisherige Check-API noch aus einer Zeit, in der es noch deutlich weniger Erweiterungen gab. Auch hat sie hat sich über die Jahre nicht verändert. Daher war es nun dringend nötig, die Check-Plugins neu zu strukturieren. Ziel ist es, die Check-Plugins als Module zu behandeln, die von einer versionierten, klar definierten API importiert werden.

Wie das aussehen soll, hat Moritz bereits auf der letzten Konferenz vorgestellt. Für Checkmk 2.0 soll die Transformation der Plugins zu Python-Modulen, die Automigration der meisten existierenden Plugins und ein kompletter Wechsel von Python 2 zu Python 3 auf der Agenda stehen.

In diesem Jahr hat Moritz in seinem Vortrag die Prinzipien der neuen Check-API vorgestellt. Diese umfassen eine Etablierung von Konventionen und Konsistenz, was vor allem die Namensgebung betrifft, die wiederum nicht nur konsistent, sondern auch erklärend werden soll. Ein weiterer Punkt der neuen API sei außerdem, dass verschiedene Dinge, die die gleiche Funktion ausführen, auch gleich aussehen sollten. So gibt es in Checkmk derzeit verschiedene Wege, die zum gleichen Ergebnis führen. Dies hat den Nachteil, dass es für solche Fälle kein allgemeingültiges Best Practice gibt und es verwirrend sein kann, sich den entsprechenden Code anzuschauen. Dies soll sich nun mit der neuen Check-API ändern, versprach Moritz.

Unnötigen Optionen vermeiden

Ein weiteres Ziel der neuen Check-API ist es, dass implizierte Funktionen auch so arbeiten, wie sie vom Entwickler ursprünglich angedacht waren. Dies schließt auch die Reduzierung unnötiger Optionen ein. So soll man nun nicht mehr zwei verschiedene Dinge brauchen, um exakt das gleiche auszuführen. Das bedeutet, dass Checks ab 2.0 nicht mehr entweder als Funktion oder als Generator agieren, sondern nur noch als Generator, wie Moritz erläuterte.

Ein weiterer Vorteil der neuen Check-API sei zudem, dass sie Programmierfehler bereits in einem früheren Stadium sichtbar macht und nicht erst im laufenden Prozess. Dabei soll das Einfügen von Checks in Python-Modulen ein Testing vereinfachen und ihre unabhängige Durchführung ermöglichen.

In der Summe hilft die neue API dabei, Checks zu vereinfachen. Gleichzeitig ändert sich für die Nutzer möglichst wenig, da eine Auto-Migration die meiste Arbeit erledigt. Diese schlug laut Moritz lediglich bei 63 der 1.920 Checks fehl, was im Umkehrschluss bedeutet, dass sie bei über 96 Prozent funktioniert hat. Im Werk #10601 hat Moritz eine Liste mit Ursachen erstellt, die für Probleme bei der Auto-Migration von selbst geschriebenen Plugins sorgen können.

Wir haben in den nächsten Wochen vor, die verbleibenden Checks zu migrieren. Anschließend wollen wir unsere Erkenntnisse mit euch teilen und uns Optionen überlegen, wie wir unseren Nutzern bei der Migration zur Seite stehen können.

In unserem nächsten Beitrag erhaltet ihr alle Neuigkeiten rund um unsere neue Support-Diagnostik und was für Möglichkeiten Checkmk 2.0 für euch bereithält, um vorab neue Funktionen und Releases zu testen.