The document discusses the Icinga 2 API which aims to unify existing interfaces and integrate Icinga 2 with other tools. The API provides a RESTful interface using JSON and allows for creating, modifying, deleting and querying of objects as well as performing actions. It includes authentication, configuration and status endpoints, and supports managing configuration packages and event streams. The API helps satisfy integration requirements and allows configuration and monitoring from external applications.

1. www.icinga.org
Icinga 2: Apify them all
Icinga Camp - Portland - 10/10/2015

2. • Michael Friedrich
• Core Developer
• 6+ years #icingalove
• @dnsmichi

3. ICINGA 2: INTRODUCTION

4. • Icinga 2 configuration DSL
• Apply, conditions, functions, …
• Features (Graphite, DB IDO, …)
• Standalone or Cluster with Clients
• Already there – what’s missing?

5. ICINGA 2: INTEGRATION

6. • Many existing interfaces
• Integration with other tools
• Can they satisfy my requirements?

7. • File based (status.dat, config files)
• Database (IDO)
• Unixsocket (Livestatus)
• FIFO (External Command Pipe)

8. ICINGA 2 API – UNIFY THEM ALL

9. • Snmp traps as check results
• Metrics as event streams
• External command actions
• Status Queries
• Inventory: Use $tool to create objects
at runtime

10. API – REQUIREMENTS

11. • RESTful url schema
• HTTP protocol, status codes
• JSON for requests & responses
• Version safety (/v1/…)
• Url endpoints (/v1/status,
/v1/objects, …)

12. {
"results": [
{
"code": 500.0,
"errors": [
"Error: Validation failed for object
'google.com' of type 'Host'; Attribute 'check_command':
Attribute must not be empty."
],
"status": "Object could not be created."
}
]
}

13. • Authentication & Authorization
• HTTPS only via port 5665
• Basic Auth and/or
• Client certificates
• Permissions (query, modify, actions,
…)

14. API – USE CASES

15. • Create, modify & delete objects
• At runtime, no reload
• Static Apply-Rules evaluated at
runtime
• Dependency tracking of objects
• Cluster zone sync

16. curl -u root:icinga -k –s
'https://localhost:5665/v1/objects/hosts/puppetlab
s.com'
-X PUT
-d '{ "attrs": {
"address": "52.10.10.141”,
"check_command": "hostalive”,
"vars.os" : "Linux”
}
}'

17. • Object Queries
• Configuration & Status
• Access e.g. command line from
checks
• Filter by attributes (same filters as
in config DSL)
• Implicit joins

18. $ curl -u root:icinga -k -s
'https://localhost:5665
/v1/objects/hosts/puppetlabs.com'

19. • Actions
• Schedule downtimes
• Reschedule checks
• Acknowledge problems
• Multiple objects w/ filters, e.g. all
services in a NOT-OK state

20. $ curl -u root:icinga -k -s –X POST
'https://localhost:5665
/v1/actions/reschedule-check
?filter=service.state!=0
&type=Service'

21. • Status
• Global feature statistics
• /v1/status

22. $ curl -k -s -u root:icinga
'https://localhost:5665/v1/status'

23. • Manage configuration packages
• Stages & Validation
• Active runtime stage
• Direct file access over the API
• Used by Icinga Web 2 Config Tool

24. $ curl -k -s -u root:icinga -X POST
https://localhost:5665/v1/config/packages/puppet
$ curl -k -s -u root:icinga -X POST
https://localhost:5665/v1/config/stages/puppet
-d '{
"files": {
"conf.d/test.conf": "object Host "cfg-mgmt" {
check_command = "dummy" }”
}
}'

25. • Event Streams
• Subscribe to (filtered) core events
• Forward data to external apps
• Same filters as in config DSL
• Work-in-progress

26. 2 API
Query, Create, Modify,
Delete Objects
Config
Packages
Status Actions
Event
Streams

27. CALL TO ACTION

28. Demo

29. CONCLUSION

34. • Open Tasks
• Event Streams missing
• History API in 2016 (?)
• v2.4 Release date: 11.11.2015
• More at OSMC:
https://www.netways.de/en/events
_trainings/osmc/program/

35. • Install Icinga 2 snapshot packages
• Docker, Vagrant
• http://docs.icinga.org/icinga2/snapshot/doc/module/icing
a2/chapter/icinga2-api#icinga2-api
• Connect to
https://localhost:5665/v1/status

36. THANK YOU!
www.icinga.org
dev.icinga.org
git.icinga.org
@icinga
/icinga
+icinga