olowe.co/icinga

package icinga provides a client to the Icinga2 HTTP API.

Send patches, questions or a friendly "hello" to the mailing list: ~otl/[e-mail] Or, read the archives.

Quick Start

See the package overview godoc for getting started examples.

Development

Some code is automatically generated. Ensure it's up-to-date before starting work:

go generate

Make some changes, then run the tests:

go test

Please send any patches to the mailing list:

git send-email --to="~otl/[e-mail]" HEAD^

For those unfamiliar with this workflow, see git-send-email.io.

Tests

Some tests use a fake, in-process Icinga server. Not all features of the API are implemented, but on any unsupported request it should report an error. The fake server uses an in-memory map to store Icinga2 objects, which maps object's path in the API request (e.g. "objects/hosts/text.example.com") to the object's attributes (e.g. check_command and display_name).

Some tests dial an instance of Icinga2 running on the loopback address and the standard Icinga2 port 5665 (::1:5665). If this fails, those tests are skipped. To run these tests, create the following API user:

object ApiUser "icinga" {
	password = name
	permissions = [ "*" ]
}

Getting data from the loopback interface to an Icinga server is left as an exercise to the reader!

Personally, I run an Alpine Linux virtual machine using qemu. You could also use the official Icinga2 container image.

Code generation

Source code for the basic lookup, create and delete operations of some Icinga2 object types, such as Host and Service, are generated automatically.

To generate the code, ensure the following tools are available:

• POSIX shell (/bin/sh)
• awk
• gofmt

The shell script crud.sh writes Go source code by reading a template file and doing some text substitution. It loops through object types, piping the template file crud.skel into the awk script crud.awk for each.

crud.sh writes code to the standard output by default:

./crud.sh

If the flag -o is set, code will be written to the file specified instead of to standard output:

./crud.sh -o crud.go

Code generation is used because the functions are trivial and call the exact same underlying methods on Client anyway. The only thing that differs is the type. Perhaps when Go gets type parameters then this will go away?

Why Another Package?

The icinga2 terraform provider uses the package github.com/lrsmith/go-icinga2-api/iapi. As I read the source code I felt I wasn't reading idiomatic Go as detailed in documents like Effective Go. Other properties of iapi felt unusual to me:

• The client to the API has the confusing name server.
• Every HTTP request creates a new http.Client.
• Types have superfluous names like HostStruct instead of just Host.
• Every response body from the API is decoded from JSON into one data strucutre, marshalled into JSON again, then unmarshalled back into another.
• Every error returned from a function has a new name, rather than reusing the idiomatic name err.

If I was being paid, I'd create a fork and contribute patches upstream to carefully avoid breaking functionality of existing users of iapi.

But I'm not being paid ;)