Exactly 
placeholder
Yep. Because there is no new bakery API version. Nothing has changed there.
Wouldnāt it be nice to have all files belonging to a plugin in the same directory beneath local/lib/python3/cmk/plugins? Would enable using one git repo per plugin, for example; would also make development easier, not having to spread the files around the whole directory tree as much.
In general Iām pretty dissatisfied with the state of the API docs for 2.3.0. As far as I understood the 2.3.0 release notes all the older APIs will not be supported at all by 2.4.0 anymore. Therefore you expect us plugin developers to port everything to the 2.3.0 APIs within just a single release cycle ā while not even having finished said 2.3.0 API yet, not to mention not having the docs up to date at all.
As far as Iāve understood it, there is
- one Werk that talks in general terms about whatās going on
- this forum thread
- the built-in API docs in 2.3.0 installations
What there isnāt:
- in-depth guides on building SNMP-based & agent-based plugins converted to 2.3.0
- any documentation about building special-agent based plugins
- documented examples for the graphing API (formerly known as metrics)
- documented examples for the bakery that not only includes the WATO rulesets but also the rulesets for copying the agent itself (again, adjusted for 2.3.0; the existing docs still list pre 2.3.0 directories, for example)
- a status page collecting the links to the available 2.3.0 API documentation, the state of the 2.3.0 API, whatās still coming, what isnāt (I donāt consider having to read whole forum threads to be equivalent as I would have to manually piece together the picture of where youāre at from all the posts; having a single page thatās updated regularly with the status is much easier to consume)
I appreciate that these things take time. I also fully appreciate that there is information out there. I just find the combination of āall of the old APIs will be removed in 2.4.0ā & the rather unfinished & work-in-progress state of the new APIs & new API docs to be really frustrating.
To put it differently, if you search for ācheckmk plugin developmentā youāll only find resources talking about APIs that have already been deprecated and that will be removed in the next major release. This is bad.
The file spread has been massively reduced with 2.3. And yes, would be nicer if also the bakery stuff would be in cmk/plugins. Lets seeā¦
Can you clarify why you are not satisfied with the API docs? Your follow up comments have nothing to do with the docs, so would be helpful to understand what exactly you are missing? They seem to be quite complete and detailed and there are enough examples available to get productive. With concrete feedback, we can then improve the situation.
I do not know which APIs you talk about as well. Because for ruletsets, server-side calls and graphing: there were no APIs before. The agent based API was introduced in 2.0 and was removed in 2.3. We didnt deprecate any APIs afaik. Please be specific thus.
And, the API docs are up to date and complete. They are in product in the help section, next to the REST API docs.
The developer guide on docs.checkmk.com - something which we entirely rewrote just half a year ago and which is more extensive and better to use than ever before. As we only did minimal changes to the agent based plugins API, the existing in-depth guide on docs.checkmk.com on snmp based and agent based plugins are still largely fine, but will of course be updated soon.
This will be extended this year to cover the GUI extensions which now basically are covered via APIs. This is only now possible for special agent plugins and graphing API. Thus, please be patient. It only made sense once the api dev is complete.
We will do an entire presentation on the conference which includes all the things which you ask in your status page for.
Finally, i believe you mix up things. Which old APIs are you talking about? What are work in progress APIs? They are versioned with v1. We believe them to be in a decent state, but are happy to get feedback.
For the other things, be patient. The release is out since a week and we changed a LOT for the APIs and the docs team needs time to do as well their changes. We are aware of what needs to be done.
For these three points you can use my included mkp for Redfish.
At the moment this is the most ācompleteā example for the new API I think 
Here all stays the same. The first plugins on my GitHub that use agent bakery features are now converted to 2.3 and working.
From my point of view ist the biggest problem (after converting a whole special agent and all checks) the missing complete and simple examples. What I mean is that, it is not helpful to have some complex AWS or Azure checks as they use features and programming principles that no one should use if you want to write readable code.
The existing ported parts of code are only partially useable.
Last comment to this problem - donāt use Werks as basis for documentation. Please put all this distributed information in one structured document.
2 Likes
Thanks for both of your replies. I really appreciated them. Iāll try to write up a more to-the-point answer about concrete things Iād like to see improved. Andreas has already stated one of my most pressing issue: a concrete, well-documented example covering all cases (SNMP, agent-based, graphing, rulesets for check parameters, bakery WATO rules, bakery packaging rules) that isnāt too long & too involved. Basically whatās on docs.checkmk.com, but updated to 2.3.0 & extended to cover whatās currently not covered on docs.checkmk.com. Like I said, Iāll write something up later.
I do have patience. Iād just have even more patience if the official wording hadnāt been āall existing plugins must be migrated during 2.3.0 to the new API whose docs arenāt up to snuff yetā.
It will come. I will adapt the post here to reflect the status quo.
Agree. It will come. The docs team had to wait until the final pieces were hammered out during the beta phase, where there was quite some feedback. Didnāt make sense for them to start writing their examples before everything was settled.
It is a top priority for us.
In the meantime, we
a) already offered a developer office hour recently to ask questions and will likely do one after the conference again
b) will do a ālivestreamā of migrating a random plugin over to the new APIs
c) have a ādeveloper clinicā during our conference
I updated the initial thread to be more of a status page. If you have further input/questions for that, please let me know
Thatās great, thank you very much!
Is it possible, that currently the CheckParameters from the local rulesets are not loaded (2.3p1)?
I migrated my first check, the agent_based works fine (Checkmk-Checks/as400/src/as400 at master Ā· kuhn-ruess/Checkmk-Checks Ā· GitHub) , but the CheckParameters seam not be loaded. If I raise Exception() inside the file, I see the exception in the web.log. But when I put an exception into a parameter_form, there is no error in the log. I exactly followed the examples from cmk/plugins and have it basically same as there.
I think there is only a small typo in your file.
from cmk.rulesets.v1.form_sepcs import (
ā form_specs
Please donāt say that you also use some oldschool Emacs without syntax checking
After the fix, the rules are visible inside CMK
Damn, thank you very much. I was blind in the end.
No, I use vim and have autocompletion direct from the Checkmk repo so that I can check out different versions and always have the correct completion.
But right now, thatās not working since cmk.rulesets does not exist in that way inside the repo. Did not have the time yet to check where that path is and to fake it into my ENV. Which path are you using in your editor?
At the moment i use a modified version of the ācheckmk_templateā from @Jiuka.
this maps the āpluginsā folder to ā~/local/lib/python3/cmk/pluginsā
Under the āpluginsā folder i have one folder for each plugin (use a template folder to only copy and paste the folder structure).
With this setup my VSCode is running directly inside the site Python context.
2 Likes
Quick question: in your bakery exampleās _migrate function, shouldnāt the line shown above be the other way around wrt. to the interval? I mean that in cached mode there should be a value specifying how often to execute the plugin where as in sync mode itās always called. Meaning Iād expect that line to read like this:
"deployment": ("sync", None) if not iv else ("cached", float(iv - iv % 60.0)),
Or do I misunderstand the meaning of cached vs sync?
Sorry, I do not know. I merely posted the code by request.
Are dashlets included in this part?
Iām currently trying to figure out the new location.
~/local/share/check_mk/web/plugins/dashboard = Legacy GUI extensions (deprecated)
~/local/lib/python3/cmk/gui/plugins/dashboard = GUI extensions (deprecated)
~/local/lib/python3/cmk/gui/dashboard/dashlet/dashlets analog to e.g. ~/lib/python3/cmk/gui/dashboard/dashlet/dashlets/static_text.py = Does not load the dashlet
Reducing the path to
~/local/lib/python3/cmk/gui/dashboard/dashlet = Does not load the dashlet
or
~/local/lib/python3/cmk/gui/dashboard/ = Does not load the dashlet
Leaving the dashlets in ~/local/share/check_mk/web/plugins/dashboard or ~/local/lib/python3/cmk/gui/plugins/dashboard (and/or other extensions) currently prevent my update to 2.3.0p3.
There are no official external APIs for dashboards and dashlets.
Thus, there will be no documentation around it.
You are free to build stuff there, but we are constantly modernizing our code base. Thus, expect changes here.
As you are coming to the Checkmk conference, best to ask one of the developers there in the knowledge fair regarding this.
Why not disable the mkp before update and then enable it again?
Or install a version of your mkp that will only be used with 2.3 and is compatible with 2.3 before you upgrade.
Thatās the way i need to do it for nearly all my own extensions.
Hello Andreas
This will work as work-around, but I still would appreciate a GUI API (WATO, dashlets, metrics). There is more affected than just my corner-case. Even CSS/JS overrides and addons are/were located in these folders.
There is no compatible way. Both previous locations are deprecated and the (guessed) new location does not exit or is not included. But the deprecated locations are still loaded when I place my dashlets there. Even when I place a test dashlet in the original ~/lib/ location the additional dashlet is not loaded.
The other (agents/checks) extensions are not a problem. There I just have to migrate them to the API.
Greetings
Stefan
In time we will get there - not all the way, because for some areas we need quite a lot of flexibility to change (since we are doing an entire UI re-architecture in the background for quite some time).
2.3 has a big chunk of elements in this regard. But as bad news: we have not planned further APIs for 2.4 as we need to push out some features (e.g. monitoring plug-ins) now as well.
1 Like