Important news regarding Development APIs

[martin.hirschvogel]

Dear Checkmk community, especially the coding fans among you,

on the Checkmk conference, we shared that we will be building new development APIs for some important areas, where there are currently no formal APIs. See also [Nov 2023] Checkmk 2.3 roadmap update

We recently shared updates on this on the Checkmk Partner Day and feedback was that we should also share further information here. This is an initial post, and I plan to add further info here once relevant.

What APIs are we talking about:

We are building these new APIs based on an analysis of all MKPs on the Checkmk Exchange.
Consequence: if you are doing something, which is not in there, we don’t know about this. Therefore, YOU definitely need to test the APIs early on.

Why will you benefit from these APIs?

Rulespec API

Scope:

• Rulesets in special agents, active checks, for check plug-ins, HW/SW inventory plug-ins.
• Maybe: Rulesets in notification plug-ins, host monitoring rules

You are affected, if you have … created a ruleset:

grep -Rl "rulespec_registry.register" ~/local 

(from within a site)

Example: checkmk/cmk/plugins/prism/rulesets/protection_domains.py at master · Checkmk/checkmk · GitHub

Status: Looking good. We have migrated a couple of simple rulesets already. There is still some work to do in the API.

Server-side calls API

Scope:

• Special agents
• Active checks

You are affected, if you have created one of:

grep -e 'active_check_info' -e 'special_agent_info' ~/local/share/check_mk/checks/*

(from within a site)

This is what it impacts.

Example: checkmk/cmk/plugins/elasticsearch/server_side_calls at master · Checkmk/checkmk · GitHub

Status: Looking very good. We already migrated a lot of our own code succesfully.

Graphing API
Scope:

• Metric definitions
• Graph definitions
• Perf-O-Meter definitions

You are affected, if you have created one of:

grep -e 'metric_info' -e 'graph_info' -e 'perfometer_info' ~/local/share/check_mk/web/plugins/metrics

(from within a site)

Currently in progress. Will add further info later here for this

New file locations!
My favorite change is this though, this however might still be subject to change. I can find now all plugins and the corresponding rulesets and checks in one place: checkmk/cmk/plugins at master · Checkmk/checkmk · GitHub
This is also where you can find all plug-ins which we already migrated!

Where is the API documentation?
You can find this inside a 2.3.0 site. For this please use a daily build. You can find them in the download archive for Checkmk daily builds. Keep in mind that the 2.3.0 daily builds are not stable. This is our development branch!
Go in the Checkmk site to “Help → Check plugin API reference”. Then you will find the current state of the API documentation.

Our migration plan:

• Rulesets and Metrics
  • Migrate a couple of simple and complex ones to cover all functionality
    • Won’t migrate all manually, not feasible
    • Migration of all will only be done, if it is scriptable. Then we will share the script.
• Special agents and active checks: Migrate all

Your To-Dos:

• Use Checkmk 2.3 to migrate all extensions to APIs
  • Must for Special Agents and active checks API as current methods will be removed in 2.4
  • Will (likely) save you any worries when upgrading to 2.4
  • Effort is reasonable as not a fundamental change as with agent-based API (for check plug-ins)
• If you can, migrate even before and let us know, if APIs are sufficient
• We only know our code and MKPs on exchange.checkmk.com

We are happy to also receive your feedback in this thread!
I will also update this thread based on feedback, new learnings and so.
Of course for Checkmk 2.3, we plan to provide more resources as well. This is basically a early hint into it.

This werk describes the new APIs comprehensively: New APIs for plugin development

The API documentation can be found within your Checkmk 2.3.0 site under Help → Plugin API references and looks like this:

[gismo (Stéphane Ludwig)]

You mean it’s now possible to pip install cmk and start the development ?

[andreas-doehler (Andreas)]

@gismo

You mean it’s now possible to pip install cmk and start the development ?

That is what is intended in the end, if i understood our meeting at the PartnerDay correctly.
If it could be done with pip directly from pypi or from a file is another topic i think.

[martin.hirschvogel]

The idea is that you only need the packages cmk-graphing , cmk-rulesets , cmk-server-side-calls and cmk-agent-based in the future for developing monitoring plug-ins.
However, we can not promise yet that this will work.

[martin.hirschvogel]

The API development is coming to a finish soon.
Please check out the location of migrated plugins to see how stuff now looks like.

[martin.hirschvogel]

The werk describing the changes has now been released:

New APIs for plugin development

We are planning a community call / developer hour as well to ask questions during the 2.3 beta phase. More details will follow.

[martin.hirschvogel]

I added where to find the API documentation incl. some screenshots in the original post

[Tom201023 (Tom)]

Will this all also apply to notification plugins? At the top it states ‘Maybe’ so this is unclear to me

[moritz]

Hi Tom,
There is no comparable API for the development of notification plugins themselves, but you can use the ruleset API to create NotificationParameters, i.e. the ruleset to configure them.

[mhoess]

Hi,

I was playing with new CheckParameters-API.

When adding a discovered Parameter (

yield Service(parameters={"x":..}

) to the plugins I got an error in the “Parameters of this service”-view because
of the additional/unknown parameter “x”.

Later I found out if I add an element “x” with DictElement.render_only=true
to my CheckParameter-ruleset, the error vanished.

I wonder if this is the intended/correct way to handle things in the future?

Thanks + Best regards
Micha

[moritz]

Hi Micha!

DL;DR: Yes, exactly.

This has been a problem “forever”. The rulespec is not only used to render the values configured by the user, but also to render the “effective parameters for this service” (which may include discovered parameters) and the discovered parameters themselves (during discovery).

If some of the discovered parameters are not known to the rulespec, the error you described will occur.
Often plugin developers don’t enable the “Parameters for this service”-view, and so this problem goes by unnoticed.

In the past there where only two solutions to this problem: Either just add the key to “ignored_keys” or implement it as “regular” part of the rulespec. In the former case you don’t get nice rendering, in the latter you make the value user configurable, which might not make sense (but keep the enforced service rule in mind!).

This is one of the intended use-cases of the render_only attribute.

Thanks for your feedback! (We’re also looking into some other issues you’ve raised.)

[mhoess]

Hi Moritz,

thanks for the clarification.
So is using the ignored_keys (which ist now called ignored_fields) also still a valid option to handle this?

Thanks,
Micha

[moritz]

ignored_elements? Yes, that is another option. But I (personally) would prefer “render only”. It’s more transparent.

[mhoess]

Hi Moritz,

yes, I also like the “render_only” more.
(also couldn’t get the “ignored_elements” to work, I will file a bug :-))

Best regards,
Micha

[moritz]

Wait for b6! Could be this.
EDIT: You where quicker …