In my last article I focussed on Icinga 2 and the new configuration utility Icinga Director. I mentioned that Icinga Director can be used to link Icinga to pre-existing  Configuration Management Database (CMDB) systems to simplify data import. In this article we will create a little "dummy CMDB" with MySQL and automatically import and deploy host information.

Using Icinga Director we can automate maintaining the follow object types:

• Hosts and host groups
• Services and service groups
• Users and user groups
• Endpoints and zones
• Commands

Database preparation

The following example is a simple table with host information. A hostname and an appropriate IP address are essential for monitoring hosts with Icinga. This information can also be gathered from pre-existing CMDB systems - but collecting the data might be way more complex (e.g. reading multiple tables, etc.). Access to the approriate database is needed - a read-only account should be sufficient. Depending on your CMDB product this step might be complex - so prepare yourself for reading the database documentation (if applicable) and testing things for a couple of hours under the influence of coffein. 🙂

As example, a table with the following entries was created:

hosts

The particular columns are self-explanatory: beside a continuous number, hostnames, ip addresses and optional descriptions are defined. In MySQL, the table including a database and user is defined like this:

 1mysql> CREATE DATABASE cmdb CHARACTER SET 'utf8';
 2mysql> GRANT ALL ON cmdb.* TO 'cmdb'@'localhost' IDENTIFIED BY '...';
 3mysql> FLUSH PRIVILEGES;
 4$ mysql -u cmdb cmdb -p
 5mysql> CREATE TABLE hosts(
 6        host_id INTEGER PRIMARY KEY AUTO_INCREMENT,
 7        host_name TEXT NOT NULL,
 8        host_ip TEXT NOT NULL,
 9        host_desc TEXT NULL
10);
11mysql> INSERT INTO hosts (host_name, host_ip) VALUES ("dummyhost", "127.0.0.1");
12mysql> INSERT INTO hosts (host_name, host_ip, host_desc) VALUES ("dummyhost2", "127.0.0.2", "Test host");
13mysql> INSERT INTO hosts (host_name, host_ip, host_desc) VALUES ("dummyhost2", "127.0.0.2", "Test host 2");

Collecting the relevant information is done with the following SQL statement:

1SELECT host_name, host_ip, host_desc from hosts;

The goal is now to make Icinga Director to retrieve those information and convert them into valid host objects - fully automated. 🙂

Icinga Director customization

The first step is to create a resource for the external database. Click Configuration > Application > Resources and Create a New Resource. Select SQL as type, the dialog should look like this:

When clicking Validate Configuration, the connection is tested and stored as resource if no errors occured.

The next step is to populate the data source inside Icinga Director - click Icinga Director > Automation > Import Source and Add import source. Pick a useful name and select SQL as type again. In this example, the dialog should be filled like this:

• Key column name: host_name (column name that contains hostnames)
• Resource name: name of the SQL resource
• DB Query: SELECT host_name, host_ip, host_desc from hosts;

When using various CMDB products it might be necessary to manipulate information - e.g. to change casing or add domain names. Modifications like this can be implemented in the Modifiers tab. Once the data source has been configured, it can be tested by clicking Check for changes in the Import source tab. Click Trigger Import Run to import and retrieve data. After this process has finished, the data can be checked in the Preview pane. In our example, the table should look like this:

Nice - we can retrieve data! Using a synchronization job we can ensure that hosts are imported into the Icinga Director database. To define a job like this, move to the Sync rule pane and click Add sync rule. Define a useful name and select the object type Host. In the Update Policy pane we can control how Icinga Director handles imported data: locally defined information can be completely replaced (Replace) or merged (Merge). This setting depends on your CMDB product - I decided to merge data as I don't define services and notifications using the CMDB. Purge defines whether information deleted in the source are also removed from the Director database. Again, this depends on your workflow about various import sources. Basically, imported information are often extended with additions settings (e_.g. services, notifications,..._) - in my setup, I decided to remove hosts from the Director database.

Once the job was defined, you can test the synchronization by clicking Check for changes and Trigger this Sync in the first pane. If the job was executed without any errors, an entry like this can be found in the History pane:

When clicking on the entry, a more detailed log is displayed - for example:

Okay, we created an import source including synchronization. But it would be really cool if this can be done automatically - and with this requirement, jobs are coming into picture. By clicking Jobs and Add, another assistant is opened. If we want to automate what we have done before, we need to create two dedicated jobs:

1. Importing hosts from the database
2. Creating and deploying the configuration

Especially for the second jobs, opinions might vary heavily. In some environments it is not the best idea to automate rolling out configurations - e.g. to validate additional customizations. But in some development and testing environments, this might be pretty useful - you will decide on our own what's best for you. 🙂

Beside a useful name, the job type is defined. For the first job we will select Import, while picking Config for the second one. When importing information, the appropriate data source needs to be entered. For both jobs a time interval in seconds is defined - e.g. 86400 for a daily job. My job settings look like this:

Test it - you will see that configuration changes are documented in the Activity Log menu. By clicking an entry, even code changes can be seen:

Conclusion

I'm amazed how Icinga Director simplifies importing and configuring third-party information. It requires some testing, but especially in bigger environments plenty of workhours can be saved and even maintaining existing information is easier. You did a very good job, dear Icinga team! 🙂