Checkmk 2.2 and Grafana
Checkmk 2.1 uses Web API; 2.2+ uses REST API. Using data source v2.0.3 after upgrading may cause issues.
LAST TESTED ON CHECKMK 2.4.0P1
If you're using Checkmk version 2.1, use data source release v2.0.3.
To avoid this, upgrade the data source to v3.0.0.
Data sources can be downloaded from: Grafana Checkmk Data sources
Getting Started
Background information regarding this subject is available in our Official documentation.
Web vs. Rest API
Checkmk version 2.1 and below use the Web API while 2.2 and greater uses REST API.
Checkmk Version | Data Source Version | Web or Rest API |
|---|---|---|
2.0.0p* | 2.0. beta3 | Web API |
2.1.0p* | 2.0.3 | Web API |
2.2.0p* | 3.0.0 | REST API |
You can verify which API Checkmk uses by going to Setup → Global Setting -> and searching for API at the top.
Web API Testing (checkmk 2.0 & 2.1)
If testing the Web API via Grafana is needed, you first want to open the Network Analyze with your internet browser. We can test the Web API using Curl, but we must form the API request first.
Start the Network Monitor
Ctrl + Shift + I
For Firefox, follow this manual: Firefox Network monitor
For Google Chrome, follow this manual: Chrome development tools
After you open the Network Analyzer tool, you will want to:
Click Network within the top bar
.Click Save & Test on the Grafana Data Source page
.Select webapi.py response on the left sidebar of the Inspector page
.Click Headers on the response bar
.Copy the Request URL line to your text editor so adjustments can be made. Copy everything from
HTTP://throughwebapi.py?i.e., "
http://localhost:3000/api/datasources/proxy/uid/BZ7iqAa4z/cmk/check_mk/webapi.py?"This provides us with the Unique ID "
BZ7iqAa4z" which will differ on every installation.
To create your API request, you will need several pieces of information that will be required.
Grafana Username & Password
URL Copied from Internet Inspector
Checkmk Automation User & Password
API commands for the information that you are trying to query
.
In the following example, we will request an API to list all known hosts currently added to our Checkmk instance.
bash-5.1$ curl "http://grafanaUsername:grafanaPassword@localhost:3000/api/datasources/proxy/uid/BZ7iqAa4z/cmk/check_mk/webapi.py?action=get_host_names&_username=checkmkAutomationUser&_secret=checkmkAutomationSecret&output_format=pythyon"
{"result_code": 0, "result": ["host001.domain.com", "host002.domain.com", "host003.domain.com", "host004.domain.com"]}
To break this command down, we used the following:
Grafana Username & Password
username:password
.URL Copied from Internet Inspector
@localhost:3000/api/datasources/proxy/uid/BZ7iqAa4z/cmk/check_mk/webapi.py?
.API Action or Command
?action=get_host_names
.Checkmk Username & Password
&_username=checkmkAutomationUser&_secret=checkmkAutomationSecret
.API Output (Python or JSON)
&output_format=pythyon
Visual understanding of the above API command:
REST API Testing (Checkmk 2.2 & above)
If testing the Web API via Grafana is needed, you first want to open the Network Analyze with your internet browser. We can test the Web API using Curl, but we must create the API request first.
Start the Network Monitor
Ctrl + Shift + I
For Firefox, follow this manual: Firefox Network monitor
For Google Chrome, follow this manual: Chrome development tools
After you open the Network Analyzer tool, you will want to:
Click Network within the top bar
.Click Save & Test on the Grafana Data Source page
.Select webapi.py response on the left sidebar of the Inspector page
.Click Headers on the response bar
Copy the Request URL line to your text editor so adjustments can be made. Copy everything from HTTP:// through /1.0/
i.e., "
http://localhost:3000/api/datasources/proxy/uid/BZ7iqAa4z/rest/check_mk/api/1.0/"This provides us with the Unique ID "
BZ7iqAa4z" which will differ on every installation.
To form your API request, you will need several pieces of information that will be required.
Grafana Username & Password
URL Copied from Internet Inspector
Checkmk Automation User & Password
API commands for the information that you are trying to query
In the following example, we will request an API to list all known hosts currently added to our Checkmk instance.
bash-5.1$ curl -X 'GET' 'http://grafanaUsername:grafanaPassword@localhost:3000/api/datasources/proxy/uid/BZ7iqAa4z/rest/check_mk/api/1.0/domain-types/host_config/collections/all?effective_attributes=false' -H 'accept: application/json'
{
"links": [
{
"domainType": "link",
"rel": "self",
"href": "http://localhost/sitename/check_mk/api/1.0/domain-types/host_config/collections/all",
"method": "GET",
"type": "application/json"
}
],
"id": "host",
"domainType": "host_config",
"value": [
{
"links": [
{
"domainType": "link",
"rel": "self",
"href": "http://localhost/sitename/check_mk/api/1.0/objects/host_config/host001_domain",
"method": "GET",
"type": "application/json"
},
...full response truncated
To break this command down, we used the following:
Grafana Username & Password
username:password
.URL Copied from Internet Inspector
@localhost:3000/api/datasources/proxy/uid/BZ7iqAa4z/rest/check_mk/api/1.0/
.API Action or Command
domain-types/host_config/collections/all?effective_attributes=false'
.API Output
-H 'accept: application/json'
A handy resource can be found within the help documentation on your Checkmk 2.2+ site
Visual understanding of the above API command:
Checkmk 2.1 using Data Source v2.0.3
With this example, you can see that the Data Source is saved and is working.
Checkmk 2.1 using Data Source v3.0.0
Fortunately, data source v3.0.0 is backward compatible with Checkmk 2.1. To use it, when configuring Checkmk in Grafana, change the version from ">= 2.2" to "< 2.2". See the example below:
Checkmk 2.2 using Data Source v2.0.3 (not supported)
Using this combination produces a "Could not read API response" error.
Checkmk 2.2 and above using Data Source v3.0.0 (recommended)
Recommended configuration for Checkmk 2.2.
SSL Configuration and Testing
During the configuration process, you may encounter errors related to a Bad Gateway. SSL issues between Checkmk and Grafana typically cause this. To prevent this, verifying that SSL communication is functioning correctly between the two sites is recommended.
Curl can be used to help troubleshoot SSL issues. If SSL works correctly, Curl should respond like the one below. This should be run on the Grafana server that you're using.
bash-5.1$ curl https://localhost/checkmksite/
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>302 Found</title>
</head><body>
<h1>Found</h1>
<p>The document has moved <a href="http://127.0.0.1:5008/checkmksite/check_mk/">here</a>.</p>
</body></html>
An unsuccessful attempt may look like the following:
bash-5.1$ curl https://localhost/checkmksite/
curl: (60) SSL certificate problem: self signed certificate in certificate chain
More details here: https://curl.se/docs/sslcerts.html
curl failed to verify the legitimacy of the server and therefore could not
establish a secure connection to it. To learn more about this situation and
how to fix it, please visit the web page mentioned above.
If you are using a Self Signed Certificate for your Checkmk server and receive an error of "Could not read API response" like the below:
You may need to copy your self-signed .crt file to /usr/local/share/ca-certificates/ and run update-ca-certificates on the Grafana server.
If you have no SSL certificates installed, you will want to review the Securing the Web interface with HTTPS document to create and install your certificates.