Adds installation of icingaweb2 modules from GitHub releases

changelogs/fragments/feature_add_x509_module_installation.yml

@@ -0,0 +1,3 @@
+---
+major_changes:
+ - Added Installation of x509 certificate monitoring model

changelogs/fragments/minor_change_add_git_installation.yml

@@ -0,0 +1,3 @@
+---
+minor_changes:
+ - Adds possibility of installing modules from source (git)

doc/getting-started.md

@@ -1,11 +1,19 @@
 ### Getting Started
 
-The collection includes two roles in the current version.
+The collection includes six roles in the current version.
 
 * icinga.repos: Role to manage repositories
  * [Documentation: doc/role-repos](role-repos/role-repos.md)
 * icinga.icinga2: Role to install and manage Icinga 2 instances.
  * [Documentation: doc/role-icinga2](role-icinga2/role-icinga2.md)
+* icinga.icingadb: Role to install and manage IcingaDB, Icinga2's new data backend.
+ * [Documentation: doc/role-icingadb](role-icingadb/role-icingadb.md)
+* icinga.icingadb_redis: Role to install and manage Redis, IcingaDB's cache backend.
+ * [Documentation: doc/role-icingadb_redis](role-icingadb_redis/role-icingadb_redis.md)
+* icinga.icingaweb2: Role to install and manage Icinga Web 2.
+ * [Documentation: doc/role-icingaweb2](role-icingaweb2/role-icingaweb2.md)
+* icinga.monitoring_plugins: Role to install and manage Icinga2 compatible monitoring plugins.
+ * [Documentation: doc/role-monitoring_plugins](role-monitoring_plugins/role-monitoring_plugins.md)
 
 
 ---
@@ -39,6 +47,36 @@ ansible-galaxy collection build ansible-collection-icinga
 ansible-galaxy collection install icinga-icinga-0.3.0.tar.gz
 ```
 
+## Databases
+
+Icinga2 relies on relational databases for many parts of its functionality. **None** of those databases get installed by the roles. You need to install and configure them yourself. For doing so, there are many ways available, e.g. the Ansible role [geerlingguy.mysql](https://galaxy.ansible.com/geerlingguy/mysql) for MySQL flavours (both MySQL and MariaDB) or [geerlingguy.postgresql](https://galaxy.ansible.com/geerlingguy/postgresql) for PostGresQL:
+
+```yaml
+- name: Configure databases for Icinga2
+ hosts: database
+ vars:
+ mysql_databases:
+ - name: icingadb
+ - name: icingaweb
+ - name: vspheredb
+ encoding: utf8mb4
+ collation: utf8mb4_unicode_ci
+ - name: director
+ mysql_users:
+ - name: icingadb-user
+ host: localhost
+ password: icingadb-password
+ priv: "icingadb.*:ALL"
+ [...]
+ roles:
+ - role: geerlingguy.mysql
+```
+
+> [!NOTE]
+> Schema migrations needed for the respective Icinga components to work will be handled either by the respective roles or by the Icinga components themselves.
+
+
+
 ## Example Playbooks
 
 This is an example on how to install an Icinga 2 server/master instance.

doc/role-icingadb/role-icingadb.md

@@ -5,7 +5,12 @@ This role installs and configures the IcingaDB daemon. In addition it can also i
 It serves as the official, more performant successor to Icinga IDO. More information about its purpose and design can be found [in the official documentation](https://icinga.com/docs/icinga-db/latest/doc/01-About/).
 
 
-> :information_source: In many scenarios you want to install the [icingadb_redis role](../role-icingadb_redis/) together with this role. It is part of this collection, too.
+> [!TIP]
+> In many scenarios you want to install the [icingadb_redis role](../role-icingadb_redis/) together with this role. It is part of this collection, too.
+
+## Database
+
+IcingaDB relies on a relational database to persist received data. This database **won't** be created by this role - you need to deploy and configure one in advance. For more information, see the [Databases](../getting-started.md#databases) section in the getting started guide.
 
 ## Variables
 

doc/role-icingaweb2/module-monitoring.md

@@ -4,7 +4,7 @@ The module Monitoring is the main module for the deprecated IDO backend.
 
 ## Configuration
 
-The general module parameter `enabled` be applied here.
+The general module parameters like `enabled` can be applied here.
 
 For every config file, create a dictionary with sections as keys and the parameters as values. For all parameters please check the [module documentation](https://icinga.com/docs/icinga-web/latest/doc/03-Configuration/#configuration)
 

doc/role-icingaweb2/module-x509.md

@@ -0,0 +1,90 @@
+## Module x509
+
+### Variables and Configuration
+
+The general module parameters like `enabled` and `source` can be applied here.
+
+#### Section configuration
+
+The backend database for the module needs to be available and configured at the `icingaweb2_resources` variable.
+
+```
+icingaweb2_modules:
+ x509:
+ source: package
+ enabled: true
+ config:
+ backend:
+ resource: x509
+```
+
+#### Configure SNI Names.
+
+To configure SNIs for a IP address, use the dictionary `sni`.
+
+Example:
+
+```
+icingaweb2_modules:
+ x509:
+ source: package
+ enabled: true
+ config:
+ backend:
+ resource: x509
+ sni:
+ 192.168.56.213:
+ hostnames:
+ - icinga.com
+ - test2.icinga.com
+```
+
+#### Import Certificates
+
+To import certificates use the **list** `certificate_files` all files need to be
+available locally beforehand.
+
+```
+icingaweb2_modules:
+ x509:
+ source: package
+ enabled: true
+ config:
+ backend:
+ resource: x509
+ certificate_files:
+ - /etc/ssl/certs/ca-certificates.crt
+```
+
+#### Database Schema Setup
+
+To import the database schema use `database` dictionary with the following variables.
+
+| Variable | Type | Description | Default |
+|----------|------|-------------|---------|
+| `import_schema` | `Boolean` | Defines wether the schema will be imported or not. | false |
+| `host` | `String` | Defines database address to connect to. | `localhost` |
+| `port` | `int` | Defines the database port to connect to. | `3306` or `5432` |
+| `user` | `string` | Defines database user | `x509` |
+| `name` | `String` | Defines the database to connect to. | `x509` |
+| `password` | `String` | Defines the database password to connect with. | OMITTED |
+| `ssl_mode` | `String` | Clients attempt to connect using encryption, falling back to an unencrypted connection if an encrypted connection cannot be established |**n/a** |
+|`ssl_ca`| `String`| Defines the path to the ca certificate for client authentication. | **n/a** |
+|`ssl_cert`|`String`| Defines the path to the certificate for client authentication. | **n/a** |
+|`ssl_key`| `String` | Defines the path to the certificate key for client key authentication. | **n/a** |
+|`ssl_cipher`|`String`| Ciphers for the client authentication. | **n/a** |
+|`ssl_extra_options`|`String`| Extra options for the client authentication. | **n/a** |
+
+
+```
+icingaweb2_modules:
+ x509:
+ source: package
+ enabled: true
+ database:
+ import_schema: true
+ host: localhost
+ port: 3306
+ user: x509
+ password: secret
+```

doc/role-icingaweb2/role-icingaweb2.md

@@ -7,6 +7,32 @@ The role icingaweb2 installs and configures Icinga Web 2 and its modules.
 * [IcingaDB](./module-icingadb.md)
 * [Monitoring](./module-monitoring.md)
 
+## Databases
+
+Icingaweb2 and some of its modules rely on a relational database to persist data. These databases **won't** be created by this role - you need to deploy and configure them in advance. For more information, see the [Databases](../getting-started.md#databases) section in the getting started guide.
+
+## Modules
+
+All modules get configured as child objects of the `icingaweb2_modules` variable. All modules can be installed **from source** by setting `source: git`. By default, this role installs the module from the official Icinga repositories, if available. When installing from source, the **latest tagged release** from GitHub will be installed.
+
+The following example displays different module configurations: 
+
+> [!WARNING]
+> Most configuration per module has been **omitted** for brevity, please see the respective module configuration docs
+
+```yaml
+icingaweb2_modules:
+ icingadb:
+ enabled: true
+ source: package # install package from the official repos
+ director:
+ enabled: true
+ source: package
+ reporting:
+ enabled: true
+ source: git # install from source due to lack of package
+```
+
 ## Variables
 
 ### Icinga Web 2 DB Configuration

roles/icingaweb2/tasks/main.yml

@@ -14,13 +14,18 @@
 
 - name: Gather module packages
  ansible.builtin.set_fact:
- icingaweb2_packages: "{{ icingaweb2_packages + [ icingaweb2_module_packages[item.key] ] }}"
+ icingaweb2_packages: "{{ icingaweb2_packages + [icingaweb2_module_packages[item.key]] }}"
  loop: "{{ icingaweb2_modules | dict2items }}"
- when: icingaweb2_modules is defined and icingaweb2_module_packages[item.key] is defined and item.value.enabled is true and item.value.source == "package"
+ when: icingaweb2_modules is defined and icingaweb2_module_packages[item.key] is defined and item.value.enabled|bool and item.value.source == "package"
 
 - name: Include OS specific installation
  ansible.builtin.include_tasks: "install_on_{{ ansible_os_family | lower }}.yml"
 
+- name: Include module installation from source
+ ansible.builtin.include_tasks: "modules/install_modules_from_source.yml"
+ when: icingaweb2_modules is defined
+ loop: "{{ icingaweb2_modules | dict2items }}"
+
 - name: Manage Icinga Web 2 config
  ansible.builtin.include_tasks: "manage_icingaweb_config.yml"
 
@@ -35,11 +40,20 @@
 
 - name: Manage enabled/disabled modules
  ansible.builtin.file:
- src: "{{ icingaweb2_config.global.module_path + '/' + item.key if item.value.enabled|bool == true else omit }}"
+ src: "{{ icingaweb2_config.global.module_path + '/' + item.key if item.value.enabled | bool else omit }}"
  dest: "{{ icingaweb2_config_dir }}/enabledModules/{{ item.key }}"
  owner: "{{ icingaweb2_httpd_user }}"
  group: "{{ icingaweb2_group }}"
- state: "{{ 'link' if item.value.enabled|bool == true else 'absent' }}"
+ state: "{{ 'link' if item.value.enabled | bool else 'absent' }}"
  force: yes
+ mode: "0777"
  when: icingaweb2_modules is defined
  loop: "{{ icingaweb2_modules | dict2items }}"
+
+# Many daemons fail before e.g. the resource is set up or the schema hasn't been migrated. This is a workaround.
+- name: Manage enabled module daemons
+ ansible.builtin.service:
+ name: "icinga-{{ item.key }}"
+ state: restarted
+ when: icingaweb2_modules is defined and item.value.enabled | bool and item.key in ['reporting', 'director', 'vspheredb', 'x509']
+ loop: "{{ icingaweb2_modules | dict2items }}"

roles/icingaweb2/tasks/manage_mysql_imports.yml

@@ -0,0 +1,38 @@
+---
+- name: Check Database Credentials
+ ansible.builtin.assert:
+ that:
+ - _db['user'] is defined
+ - _db['password'] is defined
+ fail_msg: "No database credentials defined."
+
+- name: Build mysql command
+ ansible.builtin.set_fact:
+ _tmp_mysqlcmd: >-
+ mysql {% if _db['host'] | default('localhost') != 'localhost' %} -h "{{ _db['host'] }}" {%- endif %}
+ {% if _db['port'] is defined %} -P "{{ _db['port'] }}" {%- endif %}
+ {% if _db['ssl_mode'] is defined %} --ssl-mode "{{ _db['ssl_mode'] }}" {%- endif %}
+ {% if _db['ssl_ca'] is defined %} --ssl-ca "{{ _db['ssl_ca'] }}" {%- endif %}
+ {% if _db['ssl_cert'] is defined %} --ssl-cert "{{ _db['ssl_cert'] }}" {%- endif %}
+ {% if _db['ssl_key'] is defined %} --ssl-key "{{ _db['ssl_key'] }}" {%- endif %}
+ {% if _db['ssl_cipher'] is defined %} --ssl-cipher "{{ _db['ssl_cipher'] }}" {%- endif %}
+ {% if _db['ssl_extra_options'] is defined %} {{ _db['ssl_extra_options'] }} {%- endif %}
+ -u "{{ _db['user'] }}"
+ -p"{{ _db['password'] }}"
+ "{{ _db['name'] }}"
+
+- name: MySQL check for db schema
+ ansible.builtin.shell: >
+ {{ _tmp_mysqlcmd }}
+ -Ns -e "{{ _db['select_query'] }}"
+ failed_when: false
+ changed_when: false
+ check_mode: false
+ register: _db_schema
+
+- name: MySQL import db schema
+ ansible.builtin.shell: >
+ {{ _tmp_mysqlcmd }}
+ < {{ _db['schema_path'] }}
+ when: _db_schema.rc != 0
+ run_once: yes

roles/icingaweb2/tasks/modules/director.yml

@@ -43,9 +43,3 @@
  ansible.builtin.shell:
  cmd: icingacli director kickstart run
  when: vars['icingaweb2_modules']['director']['run_kickstart'] is defined and vars['icingaweb2_modules']['director']['run_kickstart'] and vars['icingaweb2_modules']['director']['kickstart'] is defined and _required.rc|int == 0
-
-- name: Module Director | Ensure daemon is running
- ansible.builtin.service:
- name: "{{ icingaweb2_director_service }}"
- state: started
- enabled: yes

roles/icingaweb2/tasks/modules/install_modules_from_source.yml

@@ -0,0 +1,39 @@
+---
+- name: "Install module from source: {{ _module }}"
+ when: vars['icingaweb2_modules'][_module]['source'] == 'git'
+ vars:
+ _module: "{{ item.key }}"
+ block:
+ - name: Download release {{ icingaweb2_module_source_versions[_module] }}
+ ansible.builtin.get_url:
+ url: https://github.com/Icinga/icingaweb2-module-{{ _module }}/archive/refs/tags/{{ icingaweb2_module_source_versions[_module] }}.tar.gz
+ dest: /tmp/
+ mode: "0644"
+ register: _download
+
+ - name: Extract source archive
+ ansible.builtin.unarchive:
+ src: "{{ _download.dest }}"
+ dest: "{{ _download.dest | dirname }}"
+ owner: "{{ icingaweb2_httpd_user }}"
+ group: "{{ icingaweb2_group }}"
+ mode: "0755"
+ remote_src: true
+
+ - name: Create module directory
+ ansible.builtin.file:
+ state: directory
+ dest: "{{ icingaweb2_config.global.module_path }}/{{ _module }}"
+ owner: "{{ icingaweb2_httpd_user }}"
+ group: "{{ icingaweb2_group }}"
+ mode: "0755"
+
+ - name: Move module to module path
+ ansible.builtin.copy:
+ src: "{{ _download.dest | dirname }}/{{ _download.dest | basename | regex_replace('\\.tar\\.gz', '') }}/"
+ dest: "{{ icingaweb2_config.global.module_path }}/{{ _module }}"
+ owner: "{{ icingaweb2_httpd_user }}"
+ group: "{{ icingaweb2_group }}"
+ mode: "0755"
+ force: true
+ remote_src: true