The document discusses Icinga 2's new API which aims to unify its existing interfaces and integration points. The API provides a RESTful interface with JSON requests and responses to enable creating, querying, modifying and deleting objects as well as performing actions. It establishes requirements like authentication, endpoints, error handling and supports use cases such as configuration management, status queries and event streaming. A demo is provided and next steps are outlined.

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/
puppetlabs.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/
icinga2/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