Forge Home

icinga

pdk
Puppet Module to manage the Icinga Software Stack

9,357 downloads

146 latest version

5.0 quality score

Version information

  • 2.5.0 (latest)
  • 2.4.2
  • 2.4.1
  • 2.4.0
  • 2.3.3
  • 2.3.2
  • 2.3.1
  • 2.3.0
  • 2.2.0
  • 2.1.4
  • 2.1.3
  • 2.1.2
  • 2.1.1
  • 2.1.0
  • 2.0.0
  • 1.0.3
  • 1.0.2
  • 1.0.1 (deleted)
  • 1.0.0 (deleted)
  • 0.1.2
  • 0.1.1
  • 0.1.0
released Dec 3rd 2021
This version is compatible with:
  • Puppet Enterprise 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x, 2017.3.x, 2017.2.x, 2016.4.x
  • Puppet >= 4.10.0 < 8.0.0
  • CentOS
    ,
    OracleLinux
    ,
    RedHat
    ,
    Scientific
    ,
    Debian
    ,
    Ubuntu
    ,
    Fedora
    ,
    SLES

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'icinga-icinga', '2.5.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add icinga-icinga
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install icinga-icinga --version 2.5.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download
Tags: monitoring

Documentation

icinga/icinga — version 2.5.0 Dec 3rd 2021

icinga

Icinga Logo

Table of Contents

  1. Description
  2. Setup - The basics of getting started with icinga
  3. Usage - Configuration options and additional functionality
  4. Reference
  5. Release notes

Description

This module provides several non private helper classes for the official Icinga modules:

  • [icinga/icinga2]
  • [icinga/icingaweb2]
  • [icinga/icingadb]

Changes in v2.0.0

  • Earlier the parameter manage_* enables or disables a repository but it was still managed. Now the management is enabled or disabled, see Enable or disable repositories.

Setup

What the Icinga Puppet module supports

  • [icinga::repos] involves the needed repositories to install icinga2, icingadb and icingaweb2:
    • The Icinga Project repository for the stages: stable, testing or nightly builds
    • EPEL repository for RHEL simular platforms
    • Backports repository for Debian and Ubuntu
    • NETWAYS extras repository for Icinga Web 2
    • NETWAYS plugins repository with some additional monitoring plugins
  • Classes to manage and setup an Icinga environment much easier:
    • [icinga::server] setups an Icinga 2 including CA, config server, zones and workers aka satellites
    • [icinga::worker] installs an Icinga 2 worker aka satellite
    • [icinga::ido] configures the IDO backend including the database
    • [icinga::web] manages Icinga Web 2, an Apache and a PHP-FPM

Setup Requirements

The requirements depend on the class to be used.

Beginning with icinga

Add this declaration to your Puppetfile:

mod 'icinga',
  :git => 'https://github.com/icinga/puppet-icinga.git',
  :tag => 'v2.5.0'

Then run:

bolt puppetfile install

Or do a git clone by hand into your modules directory:

git clone https://github.com/icinga/puppet-icinga.git icinga

Change to icinga directory and check out your desired version:

cd icinga
git checkout v2.5.0

Usage

icinga::repos

The class supports:

  • [puppet] >= 5.5 < 8.0

And requiers:

  • [puppetlabs/stdlib] >= 5.1.0 < 9.0.0
  • [puppetlabs/apt] >= 6.0.0
  • [puppet/zypprepo] >= 2.2.1
  • [puppetlabs/yumrepo_core] >= 1.0.0
    • If Puppet 6 or 7 is used

By default the upstream Icinga repository for stable release are involved.

include ::icinga::repos

To setup the testing repository for release candidates use instead:

class { '::icinga::repos':
  manage_stable  => false,
  manage_testing => true,
}

Or the nightly builds:

class { '::icinga::repos':
  manage_stable  => false,
  manage_nightly => true,
}

Other possible needed repositories like EPEL on RHEL or the Backports on Debian can also be involved:

class { '::icinga::repos':
  manage_epel         => true,
  configure_backports => true,
}

The prefix configure means that the repository is not manageable by the module. But backports can be configured by the class apt::backports, that is used by this module.

Enable and Disable Repositories

When manage is set to true for a repository the ressource is managed and the repository is enabled by default. To switch off a repository again, it still has to be managed and the corresponding parameter has to set via hiera. The module does a deep merge lookup for a hash named icinga::repos. Allowed keys are:

  • icinga-stable-release
  • icinga-testing-builds
  • icinga-snapshot-builds
  • epel (only on RHEL Enterprise platforms)
  • netways-plugins
  • netways-extras

An example for Yum or Zypper based platforms to change from stable to testing repo:

---
icinga::repos::manage_testing: true
icinga::repos:
  icinga-stable-release:
    enabled: 0

Or on Apt based platforms:

---
icinga::repos::manage_testing: true
icinga::repos:
  icinga-stable-release:
    ensure: absent

Installing from Non-Upstream Repositories

To change to a non upstream repository, e.g. a local mirror, the repos can be customized via hiera. The module does a deep merge lookup for a hash named icinga::repos. Allowed keys are:

  • icinga-stable-release
  • icinga-testing-builds
  • icinga-snapshot-builds
  • epel (only on RHEL Enterprise platforms)
  • netways-plugins
  • netways-extras

An example to configure a local mirror of the stable release:

---
icinga::repos:
  icinga-stable-release:
    baseurl: 'http://repo.example.com/icinga/epel/$releasever/release/'
    gpgkey: http://repo.example.com/icinga/icinga.key

IMPORTANT: The configuration hash depends on the platform an requires one of the following resources:

Also the Backports repo on Debian can be configured like the apt class of course, see https://forge.puppet.com/puppetlabs/apt to configure the class apt::backports via Hiera.

As an example, how you configure backports on a debian squeeze. For squeeze the repository is already moved to the unsupported archive:

---
apt::confs:
  no-check-valid-until:
    content: 'Acquire::Check-Valid-Until no;'
    priority: 99
    notify_update: true
apt::backports::location: 'http://archive.debian.org/debian'

icinga::server / icinga::worker / icinga::agent

The class supports:

  • [puppet] >= 5.5 < 8.0

And requiers:

  • [icinga/icinga2] >= 2.0.0 < 4.0.0

Setting up a Icinga Server with a CA and to store configuration:

class { '::icinga::server':
  ca            => true,
  ticket_salt   => 'supersecret',
  config_server => true,
  workers       => { 'dmz' => { 'endpoints' => { 'worker.example.org' => { 'host' => '172.16.2.11' }}, }},
  global_zones  => [ 'global-templates', 'linux-commands', 'windows-commands' ],
}

Addtition a connection to a worker is configured. By default the zone for the server is named main. When config_server is enabled directories are managed for all zones, including the worker and global zones.

IMPORTANT: A alpha numeric String has to be set to ticket_salt in Hiera to protect the CA! An alternative is to set icinga::ticket_salt in a hiera common section for all agents, workers and servers.

The associated worker could look like this:

class { '::icinga::worker':
  ca_server        => '172.16.1.11',
  zone             => 'dmz',
  parent_endpoints => { 'server.example.org' => { 'host' => '172.16.1.11', }, },
  global_zones     => [ 'global-templates', 'linux-commands', 'windows-commands' ],
}

If the worker doesn't have a certificate, it sends a certificate request to the CA on the host ca_server. The default parent zone is main. Thus, only the associated endpoint has to be defined.

If icinga::ticket_salt is also set in Hiera for the worker, he's automatically sent a certificate. Otherwise the request will be saved on the CA server and must be signed manually.

Both, server and workers, can operated with a parnter in the same zone to share load. The endpoint of the respective partner is specified as an Icinga object in colocation_endpoints.

colocation_endpoints => { 'server2.example.org' => { 'host' => '172.16.1.12', } },

Of course, the second endpoint must also be specified in the respective parent_endpoints of the worker or agent.

An agent is very similar to a worker, only it has no parameter colocation_endpoints:

class { '::icinga::agent':
  ca_server        => '172.16.1.11',
  parent_endpoints => { 'worker.example.org' => { 'host' => '172.16.2.11', }, } },
  global_zones     => [ 'linux-commands' ],
}

NOTICE: To switch off the package installation via chocolatey on windows, icinga2::manage_packgaes must be set to false for the corresponding hosts in Hiera. That works only on Windows, on Linux package installation is always used.

icinga::ido

The class supports:

  • [puppet] >= 5.5 < 8.0

Ands requires:

  • [puppetlabs/mysql] >= 6.0.0
  • [puppetlabs/postgresql] >= 7.0.0
  • [icinga/icinga2] >= 2.0.0 < 4.0.0

To activate and configure the IDO feature (usally on a server) do:

class { '::icinga::ido':
  db_type         => 'pgsql',
  db_host         => 'localhost',
  db_pass         => 'icinga2',
  manage_database => true,
}

Setting manage_database to true also setups a database as specified in db_type including database for the IDO. Supported are pgsql for PostgreSQL und maysql for MariaDB. By default the database name is set to icinga2 and the user to icinga2.

icinga::web

The class supports:

  • [puppet] >= 5.5 < 8.0

And requires:

  • [puppetlabs/mysql] >= 6.0.0
  • [puppetlabs/postgresql] >= 7.0.0
  • [puppetlabs/apache] >= 3.0.0
  • [puppet/php] >= 6.0.0
  • [icinga/icinga2] >= 2.0.0
  • [icinga/icingaweb2] >= 2.0.0

A Icinga Web 2 with an Apache and PHP-FPM can be managed as follows:

class { '::icinga::web':
  backend_db_type => $icinga::ido::db_type,
  backend_db_host => $icinga::ido::db_host,
  backend_db_pass => $icinga::ido::db_pass,
  db_type         => 'pgsql',
  db_host         => 'localhost',
  db_pass         => 'supersecret',
  manage_database => true,
  api_pass        => $icinga::server::web_api_pass,
}

If the Icinga Web 2 is operated on the same host as the IDO, the required user credentials can be accessed, otherwise they must be specified explicitly. With manage_database set to true, a database of the specified type is also installed here. It is used to save user settings for the users of the Icinga Web 2.

IMPORTANT: If you plan tu use icingacli as plugin, e.g. director health checks, businessprocess checks or vspheredb checks, set the parameter run_web => true for icinga::server on the same host icinga::web is declared. That put the Icinga user to the group icingaweb2 and restart the icinga2 process if necessary.

icinga::web::director

Install and manage the famous Icinga Director and the required database. A graphical addon to manage your monitoring environment, the hosts, services, notifications etc.

Here an example with an PostgreSQL database on the same host:

class { '::icinga::web::director':
  db_type         => 'pgsql',
  db_host         => 'localhost',
  db_pass         => 'supersecret',
  manage_database => true,
  endpoint        => $::fqdn,
  api_host        => 'localhost',
  api_pass        => $icinga::server::director_api_pass,
}

In this example the Icinga server is running on the same Host like the web and the director.

icinga::web::vspheredb

The class supports:

  • [puppet] >= 5.5 < 8.0

And required in addition to icinga::web:

  • [icinga/icingaweb2] >= 3.2.0

The following example sets up the vspheredb Icinga Web 2 module and teh required database. At this time only MySQL/MariaDB is support by the Icinga team, so this class also supports only mysql.

class { '::icinga::web::vspheredb':
  db_type         => 'mysql',
  db_host         => 'localhost',
  db_pass         => 'vspheredb',
  manage_database => true,
}

Reference

See REFERENCE.md

Release Notes

This code is a very early release and may still be subject to significant changes.