diff --git a/changelogs/fragments/feature_add_reporting_module_installation.yml b/changelogs/fragments/feature_add_reporting_module_installation.yml new file mode 100644 index 00000000..69385a71 --- /dev/null +++ b/changelogs/fragments/feature_add_reporting_module_installation.yml @@ -0,0 +1,3 @@ +--- +major_changes: + - Added Installation of reporting model diff --git a/changelogs/fragments/feature_add_x509_module_installation.yml b/changelogs/fragments/feature_add_x509_module_installation.yml new file mode 100644 index 00000000..82c1f981 --- /dev/null +++ b/changelogs/fragments/feature_add_x509_module_installation.yml @@ -0,0 +1,3 @@ +--- +major_changes: + - Added Installation of x509 certificate monitoring model diff --git a/doc/getting-started.md b/doc/getting-started.md index 6fd1ce35..8a5b6767 100644 --- a/doc/getting-started.md +++ b/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. diff --git a/doc/role-icingadb/role-icingadb.md b/doc/role-icingadb/role-icingadb.md index 5d66a32a..e30742ab 100644 --- a/doc/role-icingadb/role-icingadb.md +++ b/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 diff --git a/doc/role-icingaweb2/module-reporting.md b/doc/role-icingaweb2/module-reporting.md new file mode 100644 index 00000000..b76dc11e --- /dev/null +++ b/doc/role-icingaweb2/module-reporting.md @@ -0,0 +1,29 @@ +## Module Reporting + +The module Reporting provides a way to generate reports based on data provided by Icinga2. + +## Configuration + +The general module parameter like `enabled` and `source` can be applied here. + +Configuration is done via the `reporting` section of the `icingaweb2_modules` variable. In addition to the general module parameters `backend.resource` and `mail.from`, a **database connection** can be defined for automatically creating the required tables. in the referenced database resource. + +Example: +```yaml +icingaweb2_modules: + reporting: + enabled: true + source: git + config: + backend: + resource: reporting-db + mail: + from: icinga@example.com + database: + import_schema: true + host: localhost + port: 3306 + user: reporting + password: reporting + type: mysql +``` diff --git a/doc/role-icingaweb2/module-x509.md b/doc/role-icingaweb2/module-x509.md new file mode 100644 index 00000000..684000fd --- /dev/null +++ b/doc/role-icingaweb2/module-x509.md @@ -0,0 +1,95 @@ +## Module x509 + +### Variables and Configuration + +The general module parameter like `enabled` and `source` can be applied here. + +| Variable | Value | +|----------|------------| +| enabled | true/false | +| source | package | + +#### 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 +``` diff --git a/doc/role-icingaweb2/role-icingaweb2.md b/doc/role-icingaweb2/role-icingaweb2.md index 4faf1ae7..bff00b7c 100644 --- a/doc/role-icingaweb2/role-icingaweb2.md +++ b/doc/role-icingaweb2/role-icingaweb2.md @@ -7,6 +7,10 @@ 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. + ## Variables ### Icinga Web 2 DB Configuration diff --git a/roles/icingaweb2/tasks/main.yml b/roles/icingaweb2/tasks/main.yml index e6bd7b6b..7557ac35 100644 --- a/roles/icingaweb2/tasks/main.yml +++ b/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 }}" diff --git a/roles/icingaweb2/tasks/manage_mysql_imports.yml b/roles/icingaweb2/tasks/manage_mysql_imports.yml new file mode 100644 index 00000000..42938028 --- /dev/null +++ b/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_mysql'] }} + when: _db_schema.rc != 0 + run_once: yes diff --git a/roles/icingaweb2/tasks/modules/install_modules_from_source.yml b/roles/icingaweb2/tasks/modules/install_modules_from_source.yml new file mode 100644 index 00000000..69ab3f33 --- /dev/null +++ b/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 diff --git a/roles/icingaweb2/tasks/modules/reporting.yml b/roles/icingaweb2/tasks/modules/reporting.yml new file mode 100644 index 00000000..1e1b5217 --- /dev/null +++ b/roles/icingaweb2/tasks/modules/reporting.yml @@ -0,0 +1,73 @@ +--- +- name: Module Reporting | Ensure config directory + ansible.builtin.file: + state: directory + dest: "{{ icingaweb2_modules_config_dir }}/{{ item.key }}" + owner: "{{ icingaweb2_httpd_user }}" + group: "{{ icingaweb2_group }}" + mode: "2770" + +- name: Module Reporting | Manage config files + ansible.builtin.include_tasks: manage_module_config.yml + loop: "{{ _files }}" + loop_control: + loop_var: _file + when: vars['icingaweb2_modules'][_module][_file] is defined + vars: + _module: "{{ item.key }}" + _files: + - config + +- name: Module Reporting | Manage Schema + when: vars['icingaweb2_modules'][_module]['database']['import_schema'] | default(false) + vars: + _module: "{{ item.key }}" + block: + - name: Module Reporting | Prepare _db informations + ansible.builtin.set_fact: + _db: + host: "{{ vars['icingaweb2_modules'][_module]['database']['host'] | default('localhost') }}" + port: "{{ vars['icingaweb2_modules'][_module]['database']['port'] | default('3306') }}" + user: "{{ vars['icingaweb2_modules'][_module]['database']['user'] | default('reporting') }}" + password: "{{ vars['icingaweb2_modules'][_module]['database']['password'] | default(omit) }}" + name: "{{ vars['icingaweb2_modules'][_module]['database']['name'] | default('reporting') }}" + ssl_mode: "{{ vars['icingaweb2_modules'][_module]['database']['ssl_mode'] | default(omit) }}" + ssl_ca: "{{ vars['icingaweb2_modules'][_module]['database']['ssl_ca'] | default(omit) }}" + ssl_cert: "{{ vars['icingaweb2_modules'][_module]['database']['ssl_cert'] | default(omit) }}" + ssl_key: "{{ vars['icingaweb2_modules'][_module]['database']['ssl_key'] | default(omit) }}" + ssl_cipher: "{{ vars['icingaweb2_modules'][_module]['database']['ssl_cipher'] | default(omit) }}" + ssl_extra_options: "{{ vars['icingaweb2_modules'][_module]['database']['ssl_extra_options'] | default(omit) }}" + schema_path_mysql: /usr/share/icingaweb2/modules/reporting/schema/mysql.schema.sql + schema_path_pgsql: /usr/share/icingaweb2/modules/reporting/schema/pgsql.schema.sql + select_query: "select * from reporting_schema" + type: "{{ vars['icingaweb2_modules'][_module]['database']['type'] | default(omit) }}" + + - ansible.builtin.fail: + fail_msg: "No database type was provided" + when: vars['icingaweb2_modules'][_module]['database']['type'] is not defined + + - ansible.builtin.fail: + fail_msg: "Invalid database type was provided. [Supported: mysql, pgsql]" + when: _db.type not in ['mysql', 'pgsql'] + + - name: Module Reporting | Import MySQL Schema + ansible.builtin.include_tasks: ../manage_mysql_imports.yml + when: _db.type == 'mysql' + + - name: Module Reporting | Import PostgreSQL Schema + ansible.builtin.include_tasks: ../manage_pgsql_imports.yml + when: _db.type == 'pgsql' + + - name: Module Reporting | empty _db var + ansible.builtin.set_fact: + _db: {} + +- name: Module Reporting | Configure daemon + ansible.builtin.copy: + src: "{{ icingaweb2_config.global.module_path }}/reporting/config/systemd/icinga-reporting.service" + dest: /etc/systemd/system/icinga-reporting.service + mode: "0644" + owner: root + group: root + remote_src: true + when: icingaweb2_modules['reporting']['source'] == 'git' # if source is package, service gets installed for us. diff --git a/roles/icingaweb2/tasks/modules/x509.yml b/roles/icingaweb2/tasks/modules/x509.yml new file mode 100644 index 00000000..a0bc7e25 --- /dev/null +++ b/roles/icingaweb2/tasks/modules/x509.yml @@ -0,0 +1,66 @@ +- name: Module x509 | Ensure config directory + ansible.builtin.file: + state: directory + dest: "{{ icingaweb2_modules_config_dir }}/{{ _module }}" + owner: "{{ icingaweb2_httpd_user }}" + group: "{{ icingaweb2_group }}" + mode: "2770" + vars: + _module: "{{ item.key }}" + +- name: Module x509 | Manage config files + ansible.builtin.include_tasks: manage_module_config.yml + loop: "{{ _files }}" + loop_control: + loop_var: _file + when: vars['icingaweb2_modules'][_module][_file] is defined + vars: + _module: "{{ item.key }}" + _files: + - config + - sni + +- name: Module x509 | Manage Schema + block: + - name: Module x509 | Prepare _db informations + ansible.builtin.set_fact: + _db: + host: "{{ vars['icingaweb2_modules'][_module]['database']['host'] | default('localhost') }}" + port: "{{ vars['icingaweb2_modules'][_module]['database']['port'] | default('3306') }}" + user: "{{ vars['icingaweb2_modules'][_module]['database']['user'] | default('x509') }}" + password: "{{ vars['icingaweb2_modules'][_module]['database']['password'] | default(omit) }}" + name: "{{ vars['icingaweb2_modules'][_module]['database']['name'] | default('x509') }}" + ssl_mode: "{{ vars['icingaweb2_modules'][_module]['database']['ssl_mode'] | default(omit) }}" + ssl_ca: "{{ vars['icingaweb2_modules'][_module]['database']['ssl_ca'] | default(omit) }}" + ssl_cert: "{{ vars['icingaweb2_modules'][_module]['database']['ssl_cert'] | default(omit) }}" + ssl_key: "{{ vars['icingaweb2_modules'][_module]['database']['ssl_key'] | default(omit) }}" + ssl_cipher: "{{ vars['icingaweb2_modules'][_module]['database']['ssl_cipher'] | default(omit) }}" + ssl_extra_options: "{{ vars['icingaweb2_modules'][_module]['database']['ssl_extra_options'] | default(omit) }}" + schema_path: /usr/share/icingaweb2/modules/x509/schema/mysql.schema.sql + select_query: "select * from x509_certificate" + when: vars['icingaweb2_modules'][_module]['database']['type'] | default('mysql') == 'mysql' + + - ansible.builtin.fail: + fail_msg: "The Database type select is not supported, {{ vars['icingaweb2_modules'][_module]['database']['type'] }} [Supported=mysql]" + when: vars['icingaweb2_modules'][_module]['database']['type'] is defined and vars['icingaweb2_modules'][_module]['database']['type'] != 'mysql' + + - name: Module x509 | Import Schema + ansible.builtin.include_tasks: ../manage_mysql_imports.yml + + - name: Module x509 | empty _db var + ansible.builtin.set_fact: + _db: {} + when: vars['icingaweb2_modules'][_module]['database']['import_schema'] | default(false) + vars: + _module: "{{ item.key }}" + +- name: Module x509 | Import Certificates + ansible.builtin.shell: > + icingacli {{ _module }} import --file {{ _file }} + loop: "{{ vars['icingaweb2_modules'][_module]['certificate_files'] }}" + loop_control: + loop_var: _file + vars: + _module: "{{ item.key }}" + when: vars['icingaweb2_modules'][_module]['certificate_files'] is defined + changed_when: false diff --git a/roles/icingaweb2/vars/main.yml b/roles/icingaweb2/vars/main.yml index 8092fd97..0da2d9ce 100644 --- a/roles/icingaweb2/vars/main.yml +++ b/roles/icingaweb2/vars/main.yml @@ -2,4 +2,12 @@ icingaweb2_module_packages: icingadb: icingadb-web director: icinga-director - businessprocess: icinga-businessprocess \ No newline at end of file + x509: icinga-x509 + businessprocess: icinga-businessprocess + +icingaweb2_module_source_versions: + businessprocess: v2.5.0 + director: v1.11.0 + icingadb: v1.1.1 + reporting: v1.0.0 + x509: v1.3.1