Referencing Icinga (ITL) objects from Director

Icinga Director
,
1

First of all, my apologies. I am sure this question has been asked somewhere else, I just cannot figure out which keywords to use to search for it.

From my understanding, Icinga2 has different “configuration spaces”, which are as far as I know:

  • Config files
  • Icinga2 API
  • Director

Where each “space” contains an independent (and unique) set of objects (hosts, templates, …).

For example, if I create a host on director, I can’t assign the default hostgroup “generic-host” to it, because it does not exist on Director’s “configuration space”. I need to create a new “generic-host-director” template (on Director’s configuration space), in order to be able to reference it in the Director’s hosts.

The question is: Is there a way to create some fixed objects on files and reference them from the Director’s hosts?

The idea is to define the “static” stuff that doesn’t change much, like service/command/applys/notifications/… in files under /etc/icinga2/conf.d or /etc/icinga2/zones.d/ , and just create the host objects on Director.

2

Hi,

generally speaking, the CheckCommand objects provided inside the Icinga Template Library are provided by the Icinga 2 package. These command objects cannot be modified by the user, they serve as ready-to-use templates. These are maintained and updated by community members and developers, and each new Icinga feature release updates these commands in a non-breaking way.

That being said, each Icinga installation has these command definitions on its own, so it is not necessary to redistribute them to cluster zones. Also, it is not necessary to re-create them inside the Director and deploy them.

In order to work with these CheckCommand objects inside the Director, it imports them via the REST API inside the kickstart wizard. The import marks them as external objects being read-only. This allows you to define fields used in templates, objects, apply rules and service sets inside the Director.

In terms of external templates, this unfortunately doesn’t work. Mainly for two reasons - the Icinga 2 API cannot return these non-objects at runtime in full scope, and the Director also builds a template inheritance tree where all of them need to exist in the Director backend.

That being said, the Director pre-validates the configuration before deployments, and only allows to import templates it knows about (and all of its attributes).

I don’t know whether these templates can be created with the CLI or API inside the Director, but if such do not change much, it is common best practice to define them inside the Director.

In terms of apply rules, they can be managed outside the Director in their respective static config files. The Director doesn’t know about them, so each rule needs to match conditions defined and changed in the Director. This creates an overload in maintenance with editing two locations in the worst case.

It works e.g. with writing a rather complex notification rule which just notifies a ticket system instead of users, or other scenarios where advanced DSL code is necessary. Before going this route, you should ask yourself though whether this problem really cannot be solved in another way fitting into the Director’s scope.

Cheers,
Michael

1 Like
3

Thanks @dnsmichi!

Hmm… so, I’m gonna try to wrap up some facts:

  1. After installing Icinga2 we get a default set of object and variable definitions, which are “hard-coded” and also called “Icinga Template Library” (ITL).
    The CheckCommand definitions for the ITL are located by default at:
    /usr/share/icinga2/include/command-plugins.conf
    and it includes all the classics like: hostalive, http, disk, …

  2. The ITL is present in any Icinga2 installation, and can be imported/referenced anywhere*, because they are in a global … namespace?
    (*) With anywhere, I mean config files, Icinga2 API or Director

  3. The object definitions at /etc/icinga2/conf.d/ are known as “external templates”, and cannot be used within the Director’s namespace.

  4. Thereby, if I’m going to use Director for the host definition, I need to (re)define the whole environment in the Director namespace(?)

  5. As a consequence, if I want to juggle hosts between “external templates”, Icinga2 API and Director I need to take care of having identical Apply Rules but with slightly different names, in order to avoid conflicts.

Practical example:

Let’s juggle a basic host between namespaces:

Config file:

Create file /etc/icinga2/conf.d/myhost.conf with the content:

object Host "myhost" {
  import "generic-host"
  address = "192.168.0.2"
}

Check config and reload daemon:

icinga2 daemon -C
systemctl reload icinga2

Director (CLI):

Create a “generic-host” equivalent service:

icingacli director host create 'generic-host-d' \
  --object_type template \
  --check_command hostalive

Create the host object in Director:

icingacli director host create 'myhost' \
  --imports generic-host-d \
  --address 192.168.0.2

Deploy config:

icingacli director config deploy

Conclusion

If I want to juggle hosts between “config files” and Director in an automatic way, there’s no other way than to redefine all the dependency objects (templates, …) on Director and figure out a way to map their names somehow between both environments. For example, by appending “-d” to the Director objects.

4

The default configuration of Icinga 2 has several includes inside icinga2.conf. One of them is include <itl> followed by include <plugins> and others. This ensures that these objects are compiled by the config compiler and are available as configuration objects e.g. referenced in host/service objects.

These are examples and should help you with the first start with Icinga 2. Originally there was no Director or a Puppet module to manage configuration in a different way. If you are using a different method than the static configuration, it is strongly advised to remove the conf.d inclusion in icinga2.conf.

The node wizard setup CLI commands do that by default, allowing the Director to deploy into an “empty” Icinga. If you keep conf.d enabled and deploy a Host object from the Director which matches the local node name, you will receive duplicated object errors.

That being said, I strongly advise against mixing different configuration sources, unless you exactly know what consequences are involved here. Imho you should use the Director as trust source, and use nothing else.
The ITL objects as external reference are there for user convenience reasons. You can of course drop the include and create everything by hand by yourself. Still the Commands found inside the ITL contain years of best practice, time you save when starting with Icinga.

Not sure what “environment” and “namespace” mean here. The things you need inside the Director to create a host object is a host template, and following the host object(s). Same applies to service templates and objects/apply rules/sets.

It doesn’t hurt to understand the static DSL before diving into the Director though. This helps to understand configuration deployment errors better for instance.

Apply rules generate objects. If you change e.g. the service apply rule name, this generates a different object. Still, you now have two objects with the same purpose - and doubled checks, possible notifications, etc.

Well, with the example I still don’t know where you’re heading. What is the idea behind defining the apply rules externally? Do you have a concrete example for such a rule which cannot be built with the Director?

Cheers,
Michael

1 Like
5

@dnsmichi: Hmm… I start to understand this much better now.

I already played with Director and managed to build pretty much everything we needed fully within Director.

But the main idea behind this question, which I now realize it’s not so good, was the following:
To try to implement the option to have co-existing Director and file configurations in order to provide, how would I put it… “backwards compatibility” or “legacy (OP) support”.

Now I see that it is not such a good idea, or at least something to handle very very carefully, and aware of the headaches it will produce. I’ll try to get some support on ditching the whole file config support.

Thank you very much!

1 Like
6

One thing which also comes to mind, if you are looking for additional data feeds: The Director has a great way of using import sources and automatically sync objects and properties from external data sources. This can be a simple csv file, database, AD, or anything else. There’s also the possibility to create your own module as import source, the certificate monitoring (x509) module provides such, or just the AWS module for instance.

With that, e.g. your developers and admins can focus on their stuff, and new services are added automatically.

Cheers,
Michael

1 Like