DEBOPS.ICINGA_WEB(5)

NAME
debops.icinga_web - Manage Icinga 2 Webservice using Ansible

SYNOPSIS

debops service/icinga_web [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

The Icinga <https://www.icinga.com/> project is a monitoring solution which can be used to monitor infrastructure hosts and services. Icinga can use variety of remote agents as well as SNMP to monitor remote hosts.

DebOps provides support for Icinga 2, split into several roles:

•   the debops.icinga role is the Icinga 2 Agent role, usually installed on all hosts in the cluster that should be monitored. Different instances can function as masters, satellites or clients depending on the configuration.

•   the debops.icinga_db role can be used to configure the database support for Icinga 2, used by the web interface. Both PostgreSQL and MariaDB databases are supported.

•   the debops.icinga_web role manages the Icinga 2 Web interface, including installation of external modules like Icinga 2 Director.

GETTING STARTED

  Example inventory

The debops.icinga_web role is not included in the common.yml playbook and needs to be enabled by adding a host to a specific Ansible inventory group.

The application expects a PostgreSQL or MariaDB database and won't work without one or the other. You can install a database on the same host as the application, or configure the debops.postgresql or the debops.mariadb roles to use an external database (see the documentation of these roles for details).

It's also possible to install the Icinga 2 Web interface without the Icinga 2 Agent on the same host, however it results in a reduced functionality and additional configuration is required to point the Web interface to an external Icinga 2 Agent for command transport. By default the role uses the Icinga 2 Agent installed on the localhost for command transport.

See the Deployment guide documentation for more details about deploying Icinga in DebOps and for a full example of Ansible inventory.

  Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.icinga_web role:

---
- name: Configure Icinga Web service
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_icinga_web' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  pre_tasks:
    - name: Apply keyring configuration for php environment
      import_role:
        name: 'keyring'
      vars:
        keyring__dependent_apt_keys:
          - '{{ php__keyring__dependent_apt_keys }}'
          - '{{ nginx__keyring__dependent_apt_keys }}'
          - '{{ postgresql__keyring__dependent_apt_keys if (icinga_web__database_type == "postgresql") else [] }}'
          - '{{ mariadb__keyring__dependent_apt_keys
                if (icinga_web__database_type == "mariadb" or icinga_web__x509_enabled)
                else [] }}'
      tags: [ 'role::keyring', 'skip::keyring',
              'role::php', 'role::nginx', 'role::postgresql', 'role::mariadb' ]
    - name: Prepare php environment
      import_role:
        name: 'php'
        tasks_from: 'main_env'
      tags: [ 'role::php', 'role::php:env', 'role::logrotate' ]
  roles:
    - role: apt_preferences
      tags: [ 'role::apt_preferences', 'skip::apt_preferences' ]
      apt_preferences__dependent_list:
        - '{{ icinga_web__apt_preferences__dependent_list }}'
        - '{{ php__apt_preferences__dependent_list }}'
        - '{{ nginx__apt_preferences__dependent_list }}'
        - '{{ postgresql__apt_preferences__dependent_list | d([]) }}'
    - role: cron
      tags: [ 'role::cron', 'skip::cron' ]
    - role: logrotate
      tags: [ 'role::logrotate', 'skip::logrotate' ]
      logrotate__dependent_config:
        - '{{ php__logrotate__dependent_config }}'
    - role: ferm
      tags: [ 'role::ferm', 'skip::ferm' ]
      ferm__dependent_rules:
        - '{{ nginx__ferm__dependent_rules }}'
    - role: python
      tags: [ 'role::python', 'skip::python', 'role::mariadb', 'role::postgresql' ]
      python__dependent_packages3:
        - '{{ postgresql__python__dependent_packages3 if icinga_web__database_type == "postgresql" else [] }}'
        - '{{ mariadb__python__dependent_packages3
              if (icinga_web__database_type == "mariadb" or icinga_web__x509_enabled)
              else [] }}'
        - '{{ nginx__python__dependent_packages3 }}'
      python__dependent_packages2:
        - '{{ postgresql__python__dependent_packages2 if icinga_web__database_type == "postgresql" else [] }}'
        - '{{ mariadb__python__dependent_packages2
              if (icinga_web__database_type == "mariadb" or icinga_web__x509_enabled)
              else [] }}'
        - '{{ nginx__python__dependent_packages2 }}'
    - role: php
      tags: [ 'role::php', 'skip::php' ]
      php__dependent_packages:
        - '{{ icinga_web__php__dependent_packages }}'
      php__dependent_pools:
        - '{{ icinga_web__php__dependent_pools }}'
    - role: nginx
      tags: [ 'role::nginx', 'skip::nginx' ]
      nginx__dependent_servers:
        - '{{ icinga_web__nginx__dependent_servers }}'
      nginx__dependent_upstreams:
        - '{{ icinga_web__nginx__dependent_upstreams }}'
    - role: ldap
      tags: [ 'role::ldap', 'skip::ldap' ]
      ldap__dependent_tasks:
        - '{{ icinga_web__ldap__dependent_tasks }}'
    - role: postgresql
      tags: [ 'role::postgresql', 'skip::postgresql' ]
      postgresql__dependent_roles:
        - '{{ icinga_web__postgresql__dependent_roles }}'
      postgresql__dependent_groups:
        - '{{ icinga_web__postgresql__dependent_groups }}'
      postgresql__dependent_databases:
        - '{{ icinga_web__postgresql__dependent_databases }}'
      postgresql__dependent_extensions:
        - '{{ icinga_web__postgresql__dependent_extensions }}'
      when: icinga_web__database_type == 'postgresql'
    - role: mariadb
      tags: [ 'role::mariadb', 'skip::mariadb' ]
      mariadb__dependent_databases:
        - '{{ icinga_web__mariadb__dependent_databases }}'
      mariadb__dependent_users:
        - '{{ icinga_web__mariadb__dependent_users }}'
      when: icinga_web__database_type == 'mariadb' or
            icinga_web__x509_enabled|bool
    - role: icinga_web
      tags: [ 'role::icinga_web', 'skip::icinga_web' ]

  Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after a host was first configured to speed up playbook execution, when you are sure that most of the configuration is already in the desired state.

Available role tags:

role::icinga_web
    Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

DEFAULT VARIABLE DETAILS

Some of debops.icinga_web default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  icinga_web__modules

The icinga_web__*_modules variables define what Icinga Web modules will be installed by the role. The variables are merged together and each list entry from the default list can be overwritten using the icinga_web__modules variable. List entries are YAML dictionaries with specific parameters:

name
    Required. The name of the Icinga Web module. It will be used as the name of the symlink in the /usr/share/icingaweb2/modules/ directory.

    This parameter is also used as a marker for merging of different entries.

git_repo
    Optional. An URL of the git repository which contains the module. External modules will be cloned to the /usr/local/src/icinga_web/ directory with subdirectories based on their URL.

git_version
    Optional. Specify the version (tag) or branch of a given module to install.

enabled
    Optional, boolean. If True, the module will be enabled by default. If False, module will be disabled but can still be enabled via the web interface.

state
    Optional. Specify the desired state of the module. If present, the module will be installed and enabled. If absent, existing modules will be disabled but not removed entirely; non-installed modules won't be installed.

  Examples

See the icinga_web__default_modules variable for examples.

  icinga_web__initial_account_groups

The icinga_web__initial_account_groups variable defines a list of account groups added to the Icinga Web database during initialization. The list is ordered sequentially and groups are numbered from 1, therefore the first group listed should be "Administrators".

Each list entry is a YAML dictionary with specific parameters:

name
    Required. Name of the group to create.

state
    Optional. If not specified or present, the group will be created in the database. If absent, the group will not be created.

  Examples

See the icinga_web__initial_account_groups variable for examples.

  icinga_web__initial_accounts

The icinga_web__initial_accounts variable defines a set of administrator accounts added to the Icinga Web database during initialization. These accounts allow users to login to the web interface and use the Icinga Director REST API. All accounts listed will be added to the account grup with id 1, ie. the first one created, usually "Administrators".

Each list entry is a YAML dictionary with specific parameters:

name
    Required. The name of the user account to add to the database.

state
    Optional. If not specified or present, the account will be added to the database. If absent, the account will not be created during initialization.

password
    Optional. A plaintext password which will be hashed and encoded in the format expected by Icinga Web application and stored in the database.

    If not specified, the value of the icinga_web__default_account_password variable will be used by default.

password_hash
    Optional. A hash of the password to store in the database for a given user account. Icinga 2 Web uses native password hashing from PHP 5.6+ <https://www.icinga.com/docs/icingaweb2/latest/doc/20-Advanced-Topics/#advanced-authentication-tips> and the password hash should be specified in this format.

group_id
    Optional. Specify the numeric group id to which a given account should be added. If not specified, 1 is used by default.

  Examples

See the icinga_web__initial_accounts variable for examples.

  icinga_web__ini_configuration

The debops.icinga_web role uses a set of default variables to create and maintain the INI configuration files of Icinga 2 Web application, located in the /etc/icingaweb2/ directory. Because these files can be modified through the Web interface, the role combines the current configuration gathered at runtime from the host with the default configuration defined by the role and custom user configuration defined in the Ansible inventory variables.

Each set of variables maintains one INI configuration file. The variables are defined as list of INI configuration sections with options defined as keys and values. Each section is defined using specific parameters:

name
    Required. The INI section name. This variable is used as a marker to merge multiple configuration entries together.

state
    Optional. If not specified or present, a given configuration section will be included in the generated file. If absent, a given configuration section will be removed from the generated file. If ignore, a given configuration entry will be ignored by the role and not evaluated.

options
    Optional. Specify the INI configuration options in a given section. The options lists from multiple configuration entries with the same name are merged together, this allows to modify existing options or add new ones seamlessly.

    Each element of the list is a YAML dictionary with specific parameters:

name
    Required. The option name.

value
    Required. The option value.

state
    Optional. If not specified or present, the option will be included in the generated file. If absent, the option will be removed from the generated file. If ignore, the given element will not be evaluated by the role.

  Examples

See the icinga_web__default_config or the icinga_web__default_resources variables for example usage.

  icinga_web__director_templates

Icinga has a notion of templates <https://icinga.com/docs/icinga-2/latest/doc/03-monitoring-basics/#templates> which can be used to define sets of objects (host templates, service templates) with multiple attributes and then assign them to specific hosts and services. Templates can simplify configuration of large environments; each object can use multiple templates, they can be inherited and augment each other hierarchically.

The debops.icinga_web Ansible role can define new host and service templates using Icinga Director API. The icinga_web__director_*_templates variables define the lists of YAML dictionaries, each dictionary represents an Icinga template. Currently templates can only be created, the role does not support removing or modifying existing templates.

  Syntax

name
    Required. Name of the template, not used otherwise. Multiple entries with the same name parameter are merged together and can affect each other in order of appearance.

data
    Required. The YAML dictionary with template configuration passed to Icinga Director via its API. See Icinga documentation for information about required keys and values for a specific template.

api_endpoint
    Required. The HTTP API endpoint to use for a given template, for example /host or /service. It will be appended at the end of the icinga_web__director_api_url variable to point Ansible to the correct API endpoint.

state
    Optional. If not specified or present, a given template will be created in Icinga Director if not already present. If absent, the role will not try to create a template. If ignore, a given entry will not be evaluated during role execution.

  Examples

You can see the default list of templates imported by the role in the icinga_web__director_default_templates variable.

AUTHOR
Maciej Delmanowski

COPYRIGHT
2014-2022, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others