Icinga2 Director REST-API usage

Lately I found myself provisioning a cloud infrastructure. Doing so I chose to use Icinga2 as my infrastructure monitoring tool because it is widly accepted and I also have a few years experience on it. There are also a lot of check plugins which I could easily adopt using Icinga2.

Within this article I want to share my so-far experience using the Icinga2-Director REST-API. I will also share some usage examples and of course the endpoints.

Unfortunately Icinga2 and its contributors/community does not provide any kind of REST-API-Doc currently. Also denied with this GitHub-Issue for now.
I think they don’t let their community down and will provide it soon.

So I started my exploration using Postman and curl.

Picture by netways

NOTE:
To use the below examples I used Basic-Auth. May some of you can share their experience using any other authentication methode.

curl -k -s -u <BA-USER>:<BA-PW> -H 'Accept: application/json' -X POST ' https://{{ icingaweb2_url }}/icingaweb2/director/<ENDPOINT>' -d @<yourjson>.json

Endpoints:

URL: https://{{ icingaweb2_url }}/icingaweb2/director/command

{
"arguments": {
"-d": {
"value": "$host.display_name$"
},
"-m": {
"value": "$user.vars.mattermost_url$"
},
"-n": {
"value": "$host.name$"
},
"-o": {
"value": "$host.output$"
},
"-s": {
"value": "$host.state$"
}
},
"command": "mycommand",
"methods_execute": "PluginNotification",
"object_name": "cmd_my_check",
"object_type": "object",
"timeout": "30"
}

NOTE: arguments are not mandatory but useful when having a plugin expecting some arguments

Hosts:

URL: https://{{ icingaweb2_url }}/icingaweb2/director/hostGroup

{
"object_name": "myhostgroup",
"display_name": "My Host Group",
"object_type": "object"
}

NOTE: This can also be used for all other usergroups. Important is the Endpoint where the post refers to.

URL: https://{{ icingaweb2_url }}/icingaweb2/director/host

Example for a host-template:

{
"accept_config": true,
"check_command": "hostalive4",
"check_interval": "90",
"check_timeout": "30",
"enable_active_checks": true,
"enable_event_handler": true,
"enable_flapping": true,
"enable_notifications": true,
"enable_passive_checks": false,
"enable_perfdata": true,
"groups": [
"myhostgroup
],
"has_agent": true,
"master_should_connect": true,
"max_check_attempts": "5",
"object_name": "template_myhost",
"object_type": "template",
"retry_interval": "5",
"volatile": false
}

URL: https://{{ icingaweb2_url }}/icingaweb2/director/host

{
"address": "192.168.24.38",
"display_name": "myhostname.fritz.box",
"imports": [
"all"
],
"object_name": "myhostname",
"object_type": "object",
"vars": {
"users_cgreater": "1",
"users_wgreater": "0",
"disk_cfree": "5%",
"disk_wfree": "10%",
"disk_inode_cfree": "5%",
"disk_inode_wfree": "10%",
"load_cload1": "15",
"load_cload5": "5",
"load_cload15": "2",
"load_wload1": "14",
"load_wload5": "4",
"load_wload15": "1",
"os": "debian",
"system": "linux"
}
}

NOTE: vars are not required but useful if you have per host variables.

Service:

URL: https://{{ icingaweb2_url }}/icingaweb2/director/service

{
"check_command": "mycommand",
"check_interval": "90",
"check_timeout": "30",
"enable_active_checks": true,
"enable_event_handler": true,
"enable_flapping": true,
"enable_notifications": true,
"enable_passive_checks": true,
"enable_perfdata": true,
"max_check_attempts": "5",
"object_name": "template_my_service",
"object_type": "template",
"retry_interval": "10",
"use_agent": true,
"volatile": false
}

URL: https://{{ icingaweb2_url }}/icingaweb2/director/serviceGroup

{
"object_name": "myservicegroup",
"display_name": "My Service Group",
"object_type": "object"
}

URL: https://{{ icingaweb2_url }}/icingaweb2/director/service

{
"groups": [
"myservicegroup"
],
"host": "myhostname",
"imports": [
"template_my_service"
],
"object_name": "myservice",
"object_type": "object"
}

URL: https://{{ icingaweb2_url }}/icingaweb2/director/config/deploy

After putting a new or multiple new objects into your director, you can also redeploy the configuration using the above mentioned URL.

Credits to:

Working as a IT-Operations engineer at NeXenio, a spin-off by Hasso-Plattner-Institute for products around a digitial workspace.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store