We’re delighted to announce a ClusterControl Template for Zabbix, so Zabbix users can now get information about the status of their database clusters, backups and alarms. We have previously published integrations with other monitoring systems including Nagios and PagerDuty.

This template is built using the ClusterControl REST API to retrieve monitoring data. Thus, you need to have a ClusterControl API token and URL configured in the template’s configuration file. This simplifies the initial configuration, and allows users to extend the current monitoring data.

If you are running ClusterControl to manage and monitor your database servers/clusters, you don’t have to integrate each of the monitored hosts into Zabbix. Zabbix will be able to connect to ClusterControl and retrieve monitoring data for the database servers. Alerting can now also be integrated into the Zabbix infrastructure.


Monitoring Data


At the time of writing, the ClusterControl template returns the following monitoring data from multiple clusters:

  • Database cluster’s status - either active, failed, degraded and unknown
  • Backups status - Trigger an event if it finds at least one error on all backups
  • ClusterControl alarms (critical/warning) - Report the number of ClusterControl alarms based on severity

If you configured multiple cluster IDs in the Zabbix agent user parameter file, the template will report the statuses from all the clusters, and only return the worse event from any of the clusters. For example, if cluster 1 is up while cluster 2 fails, the template will trigger a failure event from cluster 2. 


Example Deployment


Consider the following example setup:

We have a Galera Cluster for MySQL, as well as a standalone MySQL server, managed by ClusterControl. The Zabbix agent will be installed on the ClusterControl node, and it uses some reporting scripts to talk to ClusterControl to retrieve monitoring data. The Zabbix server will use a ClusterControl template to talk to the Zabbix agent. 


Zabbix Agent

1. Installation instructions can be found on our GitHub repository page. To get the template, just clone the s9s-admin repository:

$ git clone


2. Create a template directory for ClusterControl under /var/lib/zabbix and copy the scripts directory into it:

$ mkdir -p /var/lib/zabbix/clustercontrol
$ cp -Rf ~/s9s-admin/plugins/zabbix/agent/scripts /var/lib/zabbix/clustercontrol


3. Copy the ClusterControl template user paramater file into /etc/zabbix/zabbix.agent.d/:

$ cp -f ~/s9s-admin/plugins/zabbix/agent/userparameter_clustercontrol.conf /etc/zabbix/zabbix.agent.d/


4. This template uses ClusterControl API to collect stats. Configure the value of ClusterControl API URL and token inside /var/lib/zabbix/clustercontrol/scripts/clustercontrol.conf, similar to example below:


** If you do not configure this correctly, the script will not work. You can retrieve the API token value at {Apache Document Root}/cmonapi/config/bootstrap.php on the ClusterControl node


5. Test the script by invoking a cluster ID and test argument:

$ /var/lib/zabbix/clustercontrol/scripts/ 1 test
Cluster ID: 1, Type: GALERA, Status: STARTED
Cluster ID: 2, Type: MYSQL_SINGLE, Status: STARTED

You should get an output of your database cluster summary, indicating the script is able to retrieve information using the provided ClusterControl API and token in clustercontrol.conf.


6. Finally, restart the Zabbix agent:

$ service zabbix-agent restart

Installation of the Zabbix agent is now complete.


Zabbix Server

1. Due to this bug, we need to manually create the value mapping for ClusterControl items in Zabbix server. Log into the Zabbix front-end UI and go to Administration > General > Value Mapping (the drop-down list) > Create Value Map as per below:

  • Name: ClusterControl DB Cluster Status
  • Value:
    • 0 = Failed
    • 1 = Active
    • 2 = Degraded
    • 3 = Unknown

  • Name: ClusterControl DB Backup Status
  • Value:
    • 0 = No error
    • 1 = Some backups got error

** Please follow the exact name/value as above. If you skip this step, the import will fail.


2. Download the Zabbix template file from here to your desktop.


3. Import the XML template using the Zabbix UI (Configuration > Templates > Import).


4. Create/edit hosts and link them to the template "ClusterControl Template" (Configuration > Hosts > choose a host > Templates tab):

You are done. The following is what you can expect to see in your Zabbix frontend UI:

That’s it! Please let us know if you have any suggestions for improvements.


Related Post