content-sync - KNW-1968 done, pick-24

Author: thomaskoslowski

src/onprem/de/bakery_api.asciidoc

@@ -1,5 +1,6 @@
 // -*- coding: utf-8 -*-
-// IGNORE Paketierungs Scriptlet Instanzkontextes ausblick Portierungshilfe
+// IGNORE Paketierungs ausblick Portierungshilfe
+// NONASCII
 include::global_attr.adoc[]
 = Die Bakery-API
 :title: Die Bakery-API 
@@ -24,15 +25,13 @@ All diese „Artefakte“ können mit der Bakery-API in einer einheitlichen Synt
 Ein Anwendungsfall ist zum Beispiel der folgende: 
 Sie haben die Einführung in die xref:devel_intro#[Entwicklung von Erweiterungen für {CMK}] gelesen und davon inspiriert Ihr eigenes xref:devel_check_plugins#[agentenbasiertes Check-Plugin] mit zugehörigem Agentenplugin geschrieben.
 Beide haben Sie dann zu einem xref:mkps#[{CMK}-Erweiterungspaket (MKP)] zusammengefasst.
-// In der {CMK} Exchange haben wir für dieses Beispiel das MKP link:https://exchange.checkmk.com/p/hello-world[Hello world!^] als ein einfaches Template hinterlegt.
 
 Nun wollen Sie das Agentenplugin konfigurierbar machen (z.B. nur von bestimmten Benutzern oder auf bestimmten Hosts ausführen lassen) und zusätzlich Aktionen bei der Installation oder Deinstallation des Agentenpakets durchführen.
 Dazu können Sie die Bakery-API nutzen -- als Paketierungs- und Verteilungshilfe, wie wir in diesem Artikel an einem Beispielszenario zeigen werden. 
 Dabei werden zwei neue Dateien erstellt, die dann zusammen mit den vorhandenen Plugin-Dateien zu einem neuen MKP geschnürt werden können.
-// MFS: Nur noch ein MKP, das dafür besser dokumentiert:
 Dafür finden Sie in der {CMK} Exchange ein ausführlich kommentiertes Beispiel: das link:https://exchange.checkmk.com/p/hello-world[_Hello world!_ MKP^] (link:https://github.com/Checkmk/checkmk-docs/tree/{gitbranch}/examples/bakery_api[ausgepackt auf GitHub^]), welches eng an das in diesem Artikel vorgestellte Beispielszenario angelehnt ist.
 
-*Hinweis:* Die Bakery-API stellt keine Funktionen zur Verfügung für die Konfiguration des Bakery Plugins, d.h. für die Erstellung des zugehörigen Regelsatzes, und auch nicht für die _Inhalte_ der mit dem Plugin bereitgestellten Dateien, also z.B. die Agentenplugins.
+Beachten Sie, dass die Bakery-API keine Funktionen zur Verfügung stellt für die Konfiguration des Bakery Plugins, d.h. für die Erstellung des zugehörigen Regelsatzes, und auch nicht für die _Inhalte_ der mit dem Plugin bereitgestellten Dateien, also z.B. die Agentenplugins.
 
 [TIP]
 ====
@@ -45,39 +44,36 @@ Falls mit der Bakery-API erstellte Pakete auf {RE} installiert werden, wird die
 [#api_doc]
 == Die API-Dokumentation
 
-Die API-Dokumentation ist nicht Teil des Benutzerhandbuches, sondern Teil des Quellcodes von {CMK}.
-
-[#versioning]
-=== Versionierung
-
 Software und Dokumentation der Bakery-API stammen aus der gleichen Quelle. 
 Daher passt die API-Dokumentation stets zur Software und beschreibt genau das, was die API kann --
 und deshalb ist es auch nicht nötig, den Referenzteil der verfügbaren Funktionen, Klassen, Parameter etc. im {CMK}-Handbuch zu beschreiben.
 Stattdessen finden Sie die API-Dokumentation außerhalb dieses Handbuchs, direkt in Ihrer {CMK}-Instanz.
 
+
+[#versioning]
+=== Versionierung
+
 Die API mit ihrer Dokumentation ist versioniert und nutzt dabei eine zweistufige Nummerierung nach dem link:https://semver.org/lang/de/[Semantic Versioning 2.x^] Standard im Format `X.Y`, wobei `X` für eine _Major Version_ steht und `Y` für eine _Minor Version_. 
 Eine neue Minor Version enthält neue, rückwärtskompatible Funktionen. 
 Eine neue Major Version kann dagegen Änderungen enthalten, die die API inkompatibel mit der vorherigen Major Version machen.
 
+
 [#history]
 === Versionsgeschichte und -ausblick
 
 Jedes Plugin deklariert beim xref:access_api[Zugriff auf die API] explizit die API-Version, auf der es basiert.
-Version `1` ist die seit {CMK} {v20} aktuelle Version der Bakery-API, die in diesem Artikel beschrieben wird.
-
-{CMK} {v25} wird Version `2` der Bakery-API einführen, allerdings können die beiden Versionen `1` und `2` auch in {v25} noch parallel benutzt werden.
-Das heißt, diesem Artikel folgend erstellte Plugins werden wenigstens in {CMK} {v25} noch funktionieren, sehr wahrscheinlich auch mit {v26}.
-Darüber hinaus gehende Aussagen können zum Zeitpunkt der letzten Bearbeitung dieses Abschnittes nicht getroffen werden.
+Version 1 ist die seit {CMK} {v20} aktuelle Version der Bakery-API, die in diesem Artikel beschrieben wird.
 
-// Die API folgt einer anderen Versionierung als die {CMK}-Software. 
-// Trotzdem ist die Zuordnung der Versionen von API-Dokumentation und {CMK}-Software sehr einfach, wie Sie im nächsten Kapitel erfahren.
+{CMK} {v25} führt Version 2 der Bakery-API ein, allerdings können die beiden Versionen 1 und 2 auch in {v25} noch parallel benutzt werden.
+Das heißt, diesem Artikel folgend erstellte Plugins werden wenigstens in {CMK} {v25} noch funktionieren, sehr wahrscheinlich auch darüber hinaus.
 
 [TIP]
 ====
-Die zur xref:ruleset[Konfiguration] von Bakery-Plugins in der {CMK}-GUI verwendete Rulesets-API folgt einer eigenen Versionsgeschichte.
+Die zur xref:ruleset[Konfiguration] von Bakery Plugins in der {CMK}-GUI verwendete Rulesets-API folgt einer eigenen Versionsgeschichte.
 Bitte beachten Sie für diesen Teil Ihrer Erweiterungspakete unseren Artikel zur xref:devel_check_plugins#[Entwicklung von Check-Plugins].
 ====
 
+
 [#access_doc]
 === Zugriff auf die API-Dokumentation
 
@@ -86,9 +82,12 @@ Sie ist in jeder {CMK}-Site enthalten und kann über die {CMK}-GUI geöffnet wer
 
 image::bakeryapi_help_menu.png[alt="Help-Menü in der Navigationsleiste.",width=65%]
 
-Wenn Sie Plugins außerhalb eines Instanzkontextes entwickeln und testen wollen, was ab {CMK} {v24} möglich ist, können Sie auf eine link:https://docs.checkmk.com/plugin-api/{current-major}/cmk.base.plugins.bakery.bakery_api/[auf diesem Server gehostete Kopie^] zugreifen.
-In der mit  link:https://www.sphinx-doc.org/[Sphinx^] generierten Dokumentation wird die gesamte für die Entwicklung von {CMK}-Plugins relevante API-Dokumentation angezeigt, 
-d.h. Sie finden hier neben der Dokumentation zur Bakery-API auch die zur Check-API.
+[TIP]
+====
+Wenn Sie Plugins unabhängig von einer {CMK}-Instanz entwickeln und testen wollen, können Sie auf eine Kopie zugreifen, die auf link:https://docs.checkmk.com/plugin-api/{gitbranch}/cmk.base.plugins.bakery.bakery_api/[docs.checkmk.com/plugin-api^] bereitgestellt ist.
+In der mit link:https://www.sphinx-doc.org/[Sphinx^] generierten Dokumentation wird die gesamte für die Entwicklung von {CMK}-Plugins relevante API-Dokumentation angezeigt, 
+d.h. Sie finden hier neben der Dokumentation zur Bakery-API zum Beispiel auch die zur Check-API.
+====
 
 
 [#using]
@@ -116,12 +115,13 @@ Das Windows-Plugin liest die Einträge `hello_world.user` und `hello_world.conte
 Der Zugriff auf diese Ressourcen muss jeweils im Agentenplugin umgesetzt werden und ist nicht Gegenstand der Bakery-API.
 
 * Für Linux und Solaris gibt es zusätzlich ein Programm `some_binary`, das mit ausgeliefert werden soll.
-Das ist z.B. ein kleines Shell-Skript, um das Plugin auch per Kommando unabhängig vom {CMK}-Agenten starten zu können.
+Das ist z.B. ein kleines Shell-Skript, um das Plugin auch per Befehl unabhängig vom {CMK}-Agenten starten zu können.
 
 * Unter Linux und Solaris soll nach der Installation des Agenten per Paketmanager-Routine in das Syslog geschrieben werden, dass `hello_world` installiert wurde. 
 Nach der Deinstallation des Agenten soll analog in Syslog geschrieben werden, dass `hello_world` deinstalliert wurde. +
 Üblich sind unter Linux `postinst`- und `prerm`-Skripte: im `postinst`-Skript erstellt man beispielsweise einen Cache und startet einen Daemon, im `prerm`-Skript kann man dann den Daemon wieder stoppen und den Cache löschen. Weitere Informationen zur Verwendung von „Maintainer Scripts“ finden Sie in der link:https://www.debian.org/doc/debian-policy/ch-maintainerscripts.html[Debian-Dokumentation^].
 
+
 [#ruleset]
 === Regelsatz erstellen
 
@@ -133,7 +133,7 @@ Auch die Pfadkonventionen für das Ablegen von Regelsätzen sind dort beschriebe
 
 [TIP]
 ====
-Falls Sie Regelsätze, die noch bis {CMK} {v23} unterstützt wurden, auf die aktuellen Programmierschnittstellen portieren wollen, öffnen Sie link:https://docs.checkmk.com/2.2.0/de/bakery_api.html#ruleset[die Version dieses Artikels im Handbuch von {v22}^] in einem neuen Tab oder Fenster.
+Falls Sie Regelsätze, die noch bis {CMK} {v23} unterstützt wurden, auf die aktuellen Programmierschnittstellen portieren wollen, öffnen Sie link:https://docs.checkmk.com/2.2.0/de/bakery_api.html#ruleset[diesen Artikel im Handbuch der Version {v22}^] in einem neuen Tab oder Fenster.
 Vergleichen Sie diesen Seite an Seite mit dem entsprechenden xref:extended_ruleset[Abschnitt in diesem Artikel].
 Die vorgenommene Konfiguration ist so ähnlich, dass die Gegenüberstellung leicht als Portierungshilfe dienen kann.
 ====
@@ -238,14 +238,10 @@ Die aus diesem Regelsatz resultierende GUI zeigt der folgende Screenshot:
 
 image::bakeryapi_settings.png[alt="GUI des Regelsatzes zur Konfiguration des Plugins."]
 
-// Die Konfiguration findet über den Namen, unter dem der Regelsatz registriert wird, und dem Präfix `agent_config:` zum Bakery Plugin. 
-// Dabei muss der Regelsatz unter dem gleichen Namen wie das Bakery Plugin registriert werden, jedoch mit dem zusätzlichen Präfix `agent_config:`.
-
 
 [#create_plugin]
 === Plugin-Datei erstellen
 
-// MFS: umformuliert
 Die Plugin-Datei `hello_world.py` wird im lokalen Teil der Instanzverzeichnisstruktur unter `~/local/lib/check_mk/base/cee/plugins/bakery/` abgelegt.
 
 Ein Bakery Plugin wird in Form einer Datei angelegt, die als Python 3-Modul importiert wird.
@@ -258,7 +254,6 @@ Nach {CMK}-Konvention beginnen daher auch Plugin-Dateien mit den folgenden Zeile
 # -*- coding: utf-8 -*-
 ----
 
-// MFS: umformuliert
 Da es sich um ein Modul handelt, müssen alle benötigten Klassen und Funktionen zu Beginn importiert werden.
 
 
@@ -350,7 +345,6 @@ der Plugin-Name (`name`) und die Funktionen (`files_function`, `scriptlets_funct
 
 Namen für Typ-Annotationen (`FileGenerator`, `ScriptletGenerator`, `WindowsConfigGenerator`, `WindowsConfigContent`) können optional zur Typisierung der spezifizierten Funktionen verwendet werden, z.B. so: 
 
-// MFS: Fix indentation
 [{python}]
 ----
 def get_files(conf: dict) -> FileGenerator:
@@ -381,7 +375,6 @@ Die folgenden Hilfsfunktionen können verwendet werden:
 
 Die Registrierung des Plugins bei {CMK} mit Plugin-Namen und Funktionen erfolgt über die Funktion `register.bakery_plugin`:
 
-// MFS: Fix indentation
 .~/local/lib/check_mk/base/cee/plugins/bakery/hello_world.py
 [{python}]
 ----
@@ -400,10 +393,8 @@ Die hier festgelegten Funktionen `get_hello_world_windows_config`, `get_hello_wo
 === Konfiguration für den Windows-Agenten
 
 Im Beispiel soll das Intervall zur Ausführung festgelegt werden und die Konfiguration des Plugins über zwei Variablen erfolgen können.
-// MFS: hinzugefügt:
-Achten Sie darauf, Schlüssel und Datentypen wie im oben festgelegten Regelsatz zu definieren.
+Achten Sie darauf, Schlüssel und Datentypen wie im xref:ruleset[oben erstellten Regelsatz] zu definieren.
 
-// MFS: Fix indentation, change to float
 .~/local/lib/check_mk/base/cee/plugins/bakery/hello_world.py
 [{python}]
 ----
@@ -429,9 +420,7 @@ Anschließend werden mit `WindowsConfigEntry` die Einträge in der YAML-xref:age
 
 Unter Linux und Solaris soll bei der Installation und Deinstallation des Agenten Syslog-Meldungen geschrieben werden.
 Wir zeigen hier nur die Implementierung für die Linux-Distribution Debian:
-// Oder: Wir zeigen hier nun die Implementierung für DEB- und RPM-Pakete und Solaris:
 
-// MFS: Fix indentation, fix function name, remove priority
 .~/local/lib/check_mk/base/cee/plugins/bakery/hello_world.py
 [{python}]
 ----
@@ -457,10 +446,8 @@ Schließen Sie daher Ihren Befehlssatz nicht mit einem `exit 0` ab, damit auch a
 === Agentenplugin für Linux
 
 Die Konfiguration für das Linux-Agentenplugin sieht wie folgt aus.
-// MFS: Casting
 Achten Sie darauf, das übergebene Intervall nach `Integer` zu konvertieren, da Regelsatz und Bakery für Zeitspannen unterschiedliche Datentypen nutzen.
 
-// MFS: Fix indentation
 .~/local/lib/check_mk/base/cee/plugins/bakery/hello_world.py
 [{python}]
 ----
@@ -505,7 +492,6 @@ Schließlich soll das zusätzlich auszuliefernde Shell-Skript `some_binary` als
 
 Setzt man die bisher vorgestellten Teile zusammen -- und komplettiert sie, dann sieht ein mögliches, vollständiges Plugin für das xref:example[Beispielszenario] so aus:
 
-// MFS: Fix indentation
 .~/local/lib/check_mk/base/cee/plugins/bakery/hello_world.py
 [{python}]
 ----
@@ -638,12 +624,12 @@ Wie immer sind alle Angaben hier relativ zum Instanzverzeichnis (z.B. `/omd/site
 [cols="50,~",options="header"]
 |===
 |Pfad |Bedeutung
-|`local/lib/check_mk/base/cee/plugins/bakery/` |Verzeichnis für das Bakery-Plugin (im Beispiel `hello_world.py`).
-|`local/share/check_mk/agents/plugins/` |Verzeichnis zur Ablage der Unix-artigen Agentenplugins.
-|`local/share/check_mk/agents/windows/plugins` |Verzeichnis zur Ablage der Windows Agentenplugins.
-|`local/share/check_mk/agents/` |Verzeichnis für mitgelieferte Programme oder Shell-Skripte für Unix-artige Betriebssysteme (im Beispiel `some_binary`).
-|`local/share/check_mk/agents/windows/` |Verzeichnis für mitgelieferte Programme oder Shell-Skripte für Windows.
-//|`local/share/check_mk/web/plugins/wato` |Verzeichnis für die Regelsatzdateien zur Konfiguration des Agentenplugins (im Beispiel `hellobakery_bakery.py`) und auch des zugehörigen Check-Plugins (z.B. für die Festlegung von Schwellwerten). Wählen Sie daher aussagekräftige Namen, um die Dateien auseinanderhalten zu können.
-// MFS: Hint for prefix needed added:
-|`local/lib/python3/cmk_addons/plugins/<family_name>/rulesets` |Verzeichnis für die Regelsatzdateien zur Konfiguration des Agentenplugins (im Beispiel `ruleset_hello_world_bakery.py`) und auch des zugehörigen Check-Plugins (z.B. für die Festlegung von Schwellwerten). Wählen Sie daher aussagekräftige Namen, um die Dateien auseinanderhalten zu können. Namen hier abgelegter Dateien müssen mit `ruleset_` beginnen, andernfalls ignoriert {CMK} diese.
+|`~/local/lib/check_mk/base/cee/plugins/bakery/` |Verzeichnis für das Bakery Plugin (im Beispiel `hello_world.py`).
+|`~/local/share/check_mk/agents/plugins/` |Verzeichnis zur Ablage der Unix-artigen Agentenplugins.
+|`~/local/share/check_mk/agents/windows/plugins/` |Verzeichnis zur Ablage der Windows Agentenplugins.
+|`~/local/share/check_mk/agents/` |Verzeichnis für mitgelieferte Programme oder Shell-Skripte für Unix-artige Betriebssysteme (im Beispiel `some_binary`).
+|`~/local/share/check_mk/agents/windows/` |Verzeichnis für mitgelieferte Programme oder Shell-Skripte für Windows.
+|`~/local/lib/python3/cmk_addons/plugins/<family_name>/rulesets/` |Verzeichnis für die Regelsatzdateien zur Konfiguration des Agentenplugins (im Beispiel `ruleset_hello_world_bakery.py`) und auch des zugehörigen Check-Plugins (z.B. für die Festlegung von Schwellwerten).
+Wählen Sie daher aussagekräftige Namen, um die Dateien auseinanderhalten zu können.
+Namen hier abgelegter Dateien müssen mit `ruleset_` beginnen, andernfalls ignoriert {CMK} diese.
 |===