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 example:

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

Endpoints:

Commands:

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:

Hostgroups:

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.

Host-Templates:

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
}

Host:

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:

Service-Template:

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
}

Service-Group:

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

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

Service:

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

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

Icinga2-Director redeployment

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:

• Postman
• Icinga2
• Netways