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