Migrating to Icinga DB

Although Icinga DB has been around for some time and many customers and users are already using it, there may still be some who are wondering how to upgrade/migrate to Icinga DB.
This post will briefly explain the components of the Icinga DB and how to install them in a reasonable order. Note that it is assumed that all components are installed on the Icinga primary node(s) using a MySQL/MariaDB database.

First, there is the Icinga DB feature of Icinga 2, which publishes all monitoring data to a Redis server. The feature is built into Icinga 2 in newer versions. So make sure to upgrade Icinga 2. The default configuration of the feature will publish the data to localhost:6380. The configuration file is located at /etc/icinga2/features-available/icingadb.conf, with no changes required. To install a Redis server in a current version that matches the default configuration of Icinga 2, there is the icingadb-redis package. After installing the Redis server, you can enable the icingadb feature and restart Icinga 2.

To sum it up, for the Icinga 2 part you need to

• update Icinga 2 via packages
• install the icingadb-redis package
• run icinga2 feature enable icingadb
• and restart Icinga 2.

Note that the ido-mysql or ido-pgsql feature does not need to be disabled (yet), as Icinga DB and IDO can run in parallel.
If you have a second Icinga node, please repeat the above steps for that node.

Next there is the Icinga DB daemon which synchronizes the data between the Redis server and a database. Please install the icingadb package first. After that, please create a database and a user for Icinga DB:

CREATE DATABASE icingadb;
CREATE USER icingadb@'%' IDENTIFIED BY 'CHANGEME';
GRANT ALL ON icingadb.* TO icingadb@'%';

Then you need to import the schema which is located at /usr/share/icingadb/schema/mysql/schema.sql. After that you need to customize the Icinga DB configuration in /etc/icingadb/config.yml for the database and credentials you set up before. Now Icinga DB is ready to use and can be started and activated via systemctl enable --now icingadb.

To summarize, for the Icinga DB daemon itself you need to

• install the icingadb package
• create a database and a user and import the schema
• customize the configuration
• and start Icinga DB

If you have a second Icinga node, please repeat the above steps for that node. Note that both Icinga DB instances must use the same database connection.

The last part is Icinga Web with the Icinga DB web module that connects to both Redis and the Icinga DB database. We provide packages for the web module called icingadb-web. Please upgrade Icinga Web first and then install the icingadb-web package.
For the Icinga DB database connection you have to configure a resource in Icinga Web with the credentials you set up earlier via the Configuration → Application → Resources menu:

After that please enable the module via Configuration → Modules → icingadb, and configure the resource just created as the database connection for the module via the Configuration → Modules → icingadb → Database menu:

In summary, for Icinga Web you need to

• update Icinga Web via packages
• install the icingadb-web package
• create a new resource in Icinga Web pointing to the Icinga DB database
• enable the module
• and configure the resource just created as the database connection for the module

With all components installed and configured, you now have the option to use Icinga DB and IDO in parallel.
For migrating history data to Icinga DB, you basically have three options:

1. Do not migrate any data at all.
2. Run IDO and Icinga DB in parallel for some time before disabling IDO.
3. Run the migration tool.

Once you choose to disable IDO, you must disable the ido-mysql or ido-pgsql Icinga 2 feature on the primary nodes and disable the Icinga Web monitoringmodule.
Please note that it is not necessary to delete the IDO database. If you decide not to migrate any/all data, you can always re-enable the Icinga Web monitoringmodule and access the old data.