Icinga 2 API

Die Icinga 2 API ist die Standard-Schnittstelle, welche für die Integration von anderen Softwarelösungen und Technologien genutzt werden kann. Neben dem Erstellen von Downtimes, Acknowledgements und Kommentaren können direkt zur Laufzeit neue Objekte in Icinga 2 hinzugefügt und modifiziert werden.

Darüber hinaus können über sogenannte Event-Streams direkt Daten aus dem Core ausgelesen werden, was ideal für die Anbindung an Dashboard Lösungen wie bspw. Dashing geeignet ist. Treten neue Warning oder Critical Meldungen auf, können diese per einfachem URL Aufruf direkt angezogen werden. Komplexe Caching und Berechnungs-Plugins bzw. Skripte sind daher nicht notwendig.

Selbstverständlich bietet die API eine Authentifizierung mittels Benutzername und Passwort an, um sicherzustellen dass nur berechtigte Personen Zugriff erhalten. Mittels des Berechtigungsschemas kann in Ergänzung dazu noch eingeschränkt werden, welche Lese- bzw. Schreibrechte gestattet sind.

Im Folgenden gibt es einen groben Überblick über Abfragemöglichkeiten sowie exemplarisch die Ergebnisse der Aufrufe.

Host Informationen anzeigen

API-Call: https://icinga2.localhost:5665/v1/objects/hosts?host=test-host

Ergebnis:

results[
  {
    attrs:
    {
      __name"test-host",
      acknowledgement0,
      acknowledgement_expiry0,
      action_url"",
      activetrue,
      address"192.168.1.0",
      address6"",
      check_attempt1,
      check_command"hostalive",
      check_interval300,
      check_period"",
      check_timeoutnull,
      command_endpoint"",
      display_name"Test Host",
      ...
    }
  }
]

Host Objekt anlegen

API-Call: curl -k -s -u root:icinga -H 'Accept: application/json' -X PUT 'https://icinga2.localhost:5665/v1/objects/hosts/example.localdomain' -d '{ "templates": [ "generic-host" ], "attrs": { "address": "192.168.1.1", "check_command": "hostalive", "vars.os" : "Linux" } }'

Ergebnis:

results[
  {
     code: 200.0,
     status: "Object was created."
  }
]

Event Streams

API-Call: https://icinga2.localhost:5665/v1/events&types=CheckResult&filter=event.check_result.exit_status==2

Ergebnis:

results[
  {
     check_result:
     {
       ...
      },
     host: "example.localdomain",
     service: "ping4",
     timestamp: 1445421319.7226390839,
     type: "CheckResult"
  }
]