icinga

Icinga2 API client in Go
git clone https://git.olowe.co/icinga
Log | Files | Refs | README | LICENSE

README.md (3818B)

      1 package icinga provides a client to the Icinga2 HTTP API.
      2 
      3 [![godoc](http://pkg.go.dev/badge/olowe.co/icinga)](http://pkg.go.dev/olowe.co/icinga)
      4 
      5 Send patches, questions or a friendly "hello" to the mailing list: [~otl/public-inbox@lists.sr.ht](mailto:~otl/public-inbox@lists.sr.ht)
      6 Or, read [the archives][list].
      7 
      8 ## Quick Start
      9 
     10 See the [package overview godoc][godocs] for getting started examples.
     11 
     12 [godocs]: https://godocs.io/olowe.co/icinga
     13 
     14 ## Development
     15 
     16 Some code is automatically generated. Ensure it's up-to-date before starting work:
     17 
     18 	go generate
     19 
     20 Make some changes, then run the tests:
     21 
     22 	go test
     23 
     24 Please send any patches to the [mailing list][list]:
     25 
     26 	git send-email --to="~otl/public-inbox@lists.sr.ht" HEAD^
     27 
     28 For those unfamiliar with this workflow, see [git-send-email.io][sendemail].
     29 
     30 [list]: https://lists.sr.ht/~otl/public-inbox
     31 [sendemail]: https://git-send-email.io
     32 
     33 ### Tests
     34 
     35 Some tests use a fake, in-process Icinga server. Not all features of
     36 the API are implemented, but on any unsupported request it should
     37 report an error. The fake server uses an in-memory map to store
     38 Icinga2 objects, which maps object's path in the API request (e.g.
     39 "objects/hosts/text.example.com") to the object's attributes (e.g.
     40 `check_command` and `display_name`).
     41 
     42 Some tests dial an instance of Icinga2 running on the loopback address
     43 and the standard Icinga2 port 5665 (`::1:5665`). If this fails, those
     44 tests are skipped. To run these tests, create the following API user:
     45 
     46 	object ApiUser "icinga" {
     47 		password = name
     48 		permissions = [ "*" ]
     49 	}
     50 
     51 Getting data from the loopback interface to an Icinga server is left
     52 as an exercise to the reader!
     53 
     54 Personally, I run an Alpine Linux virtual machine using qemu. You
     55 could also use the [official Icinga2 container image][image].
     56 
     57 [image]: https://hub.docker.com/r/icinga/icinga2
     58 
     59 ### Code generation
     60 
     61 Source code for the basic lookup, create and delete operations of some
     62 Icinga2 object types, such as Host and Service, are generated
     63 automatically.
     64 
     65 To generate the code, ensure the following tools are available:
     66 
     67 * POSIX shell (/bin/sh)
     68 * awk
     69 * gofmt
     70 
     71 The shell script crud.sh writes Go source code by reading a template
     72 file and doing some text substitution. It loops through object types,
     73 piping the template file crud.skel into the awk script crud.awk for
     74 each.
     75 
     76 crud.sh writes code to the standard output by default:
     77 
     78 	./crud.sh
     79 
     80 If the flag `-o` is set, code will be written to the file
     81 specified instead of to standard output:
     82 
     83 	./crud.sh -o crud.go
     84 
     85 Code generation is used because the functions are trivial and call the exact
     86 same underlying methods on Client anyway. The only thing that differs is the type.
     87 Perhaps when Go gets type parameters then this will go away?
     88 
     89 ## Why Another Package?
     90 
     91 The [icinga2 terraform provider][tf] uses the package [github.com/lrsmith/go-icinga2-api/iapi][lrsmith].
     92 As I read the source code I felt I wasn't reading idiomatic Go as detailed in documents like [Effective Go][effectivego].
     93 Other properties of `iapi` felt unusual to me:
     94 
     95 * The client to the API has the  confusing name `server`.
     96 * Every HTTP request creates a new http.Client.
     97 * Types have superfluous names like `HostStruct` instead of just `Host`.
     98 * Every response body from the API is decoded from JSON into one data strucutre, marshalled into JSON again, then unmarshalled back into another.
     99 * Every error returned from a function has a new name, rather than reusing the idiomatic name `err`.
    100 
    101 If I was being paid, I'd create a fork and contribute patches upstream to carefully avoid breaking functionality of existing users of `iapi`.
    102 
    103 But I'm not being paid ;)
    104 
    105 [effectivego]: https://go.dev/doc/effective_go
    106 [tf]: https://registry.terraform.io/providers/Icinga/icinga2/latest
    107 [lrsmith]: https://godocs.io/github.com/lrsmith/go-icinga2-api/iapi