From 637f7cc8e204145582a80f4b713492632f92a2d5 Mon Sep 17 00:00:00 2001 From: Daniel Bodky Date: Tue, 21 Nov 2023 13:23:15 +0100 Subject: [PATCH 1/5] Updates available roles --- doc/getting-started.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/doc/getting-started.md b/doc/getting-started.md index 6fd1ce35..17ab2c68 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) --- From 6ab1d1f20483a1d45c689c82e33a4e30537e18f4 Mon Sep 17 00:00:00 2001 From: Daniel Bodky Date: Tue, 21 Nov 2023 13:39:54 +0100 Subject: [PATCH 2/5] Adds references to the database examples to relevant parts of the docs --- doc/getting-started.md | 30 ++++++++++++++++++++++++++ doc/role-icingadb/role-icingadb.md | 7 +++++- doc/role-icingaweb2/role-icingaweb2.md | 4 ++++ 3 files changed, 40 insertions(+), 1 deletion(-) diff --git a/doc/getting-started.md b/doc/getting-started.md index 17ab2c68..851df2a7 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -47,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 gets 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 flavour (both MySQL and MariaDB) or [geerlingguy.postgresql](https://galaxy.ansible.com/geerlingguy/postgresql) 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/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 From b96d50d11f907a40aa52855f248ee8e2a18075cb Mon Sep 17 00:00:00 2001 From: Daniel Bodky Date: Tue, 21 Nov 2023 13:40:51 +0100 Subject: [PATCH 3/5] add installation for x509 module (#214) * add module x509 and mysql imports task * Add documentation for x509 module * Add documentation about database imports * Continues working on x509 module installation --------- Co-authored-by: Thilo W --- .../feature_add_x509_module_installation.yml | 3 + doc/role-icingaweb2/module-x509.md | 95 +++++++++++++++++++ roles/icingaweb2/tasks/main.yml | 8 ++ .../icingaweb2/tasks/manage_mysql_imports.yml | 38 ++++++++ roles/icingaweb2/tasks/modules/x509.yml | 66 +++++++++++++ roles/icingaweb2/vars/main.yml | 3 +- 6 files changed, 212 insertions(+), 1 deletion(-) create mode 100644 changelogs/fragments/feature_add_x509_module_installation.yml create mode 100644 doc/role-icingaweb2/module-x509.md create mode 100644 roles/icingaweb2/tasks/manage_mysql_imports.yml create mode 100644 roles/icingaweb2/tasks/modules/x509.yml 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/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/roles/icingaweb2/tasks/main.yml b/roles/icingaweb2/tasks/main.yml index e6bd7b6b..a020d4cd 100644 --- a/roles/icingaweb2/tasks/main.yml +++ b/roles/icingaweb2/tasks/main.yml @@ -43,3 +43,11 @@ force: yes 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 == true and item.key in ['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..676c6df2 --- /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'] }} + when: _db_schema.rc != 0 + run_once: yes 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..588f0d6d 100644 --- a/roles/icingaweb2/vars/main.yml +++ b/roles/icingaweb2/vars/main.yml @@ -2,4 +2,5 @@ icingaweb2_module_packages: icingadb: icingadb-web director: icinga-director - businessprocess: icinga-businessprocess \ No newline at end of file + x509: icinga-x509 + businessprocess: icinga-businessprocess From 0a37c99bf2d264e0b71ac7d9efb09d9457baeea4 Mon Sep 17 00:00:00 2001 From: Daniel Bodky Date: Tue, 21 Nov 2023 13:52:59 +0100 Subject: [PATCH 4/5] Fixes typos --- doc/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/getting-started.md b/doc/getting-started.md index 851df2a7..8a5b6767 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -49,7 +49,7 @@ 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 gets 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 flavour (both MySQL and MariaDB) or [geerlingguy.postgresql](https://galaxy.ansible.com/geerlingguy/postgresql) PostGresQL: +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 From 5245c5016f19ed88f47aa96ccf463cd89b56342b Mon Sep 17 00:00:00 2001 From: Daniel Bodky Date: Thu, 23 Nov 2023 07:57:05 +0100 Subject: [PATCH 5/5] Adds PostgresQL support for Icingaweb2 modules --- .../feature_add_pgsql_support_for_modules.yml | 3 ++ .../tasks/modules/manage_pgsql_imports.yml | 37 +++++++++++++++++++ roles/icingaweb2/tasks/modules/x509.yml | 26 +++++++++---- 3 files changed, 58 insertions(+), 8 deletions(-) create mode 100644 changelogs/fragments/feature_add_pgsql_support_for_modules.yml create mode 100644 roles/icingaweb2/tasks/modules/manage_pgsql_imports.yml diff --git a/changelogs/fragments/feature_add_pgsql_support_for_modules.yml b/changelogs/fragments/feature_add_pgsql_support_for_modules.yml new file mode 100644 index 00000000..5b558f98 --- /dev/null +++ b/changelogs/fragments/feature_add_pgsql_support_for_modules.yml @@ -0,0 +1,3 @@ +--- +minor_changes: + - Added support for PostgresQL databases for Icingaweb2 modules that support it diff --git a/roles/icingaweb2/tasks/modules/manage_pgsql_imports.yml b/roles/icingaweb2/tasks/modules/manage_pgsql_imports.yml new file mode 100644 index 00000000..2bc32a4e --- /dev/null +++ b/roles/icingaweb2/tasks/modules/manage_pgsql_imports.yml @@ -0,0 +1,37 @@ +--- +- name: Check Database Credentials + ansible.builtin.assert: + that: + - _db['user'] is defined + - _db['password'] is defined + fail_msg: "No database credentials defined." + +- name: Build pgsql command + ansible.builtin.set_fact: + _tmp_pgsqlcmd: >- + PGPASSWORD="{{ _db['password'] }}" + psql + "{% if _db['host'] | default('localhost') != 'localhost' %} host={{ _db['host'] }}{%- endif %} + {% if _db['port'] is defined %} port={{ _db['port'] }}{%- endif %} + user={{ _db['user'] }} + dbname={{ _db['name'] }} + {% if _db['ssl_mode'] is defined %} sslmode={{ _db['ssl_mode'] | default('require') }}{%- endif %} + {% if _db['ssl_cert'] is defined %} sslcert={{ _db['ssl_cert'] }}{%- endif %} + {% if _db['ssl_key'] is defined %} sslkey={{ _db['ssl_key'] }}{%- endif %} + {% if _db['ssl_extra_options'] is defined %} {{ _db['ssl_extra_options'] }}{%- endif %}" + +- name: PostgresQL check for db schema + ansible.builtin.shell: > + {{ _tmp_pgsqlcmd }} + -tq -c "{{ _db['select_query'] }}" + failed_when: false + changed_when: false + check_mode: false + register: _db_schema + +- name: PostgresQL import db schema + ansible.builtin.shell: > + {{ _tmp_pgsqlcmd }} + < {{ _db['schema_path_pgsql'] }} + when: _db_schema.rc != 0 + run_once: yes diff --git a/roles/icingaweb2/tasks/modules/x509.yml b/roles/icingaweb2/tasks/modules/x509.yml index a0bc7e25..a1a7a743 100644 --- a/roles/icingaweb2/tasks/modules/x509.yml +++ b/roles/icingaweb2/tasks/modules/x509.yml @@ -21,6 +21,9 @@ - sni - name: Module x509 | Manage Schema + when: vars['icingaweb2_modules'][_module]['database']['import_schema'] | default(false) + vars: + _module: "{{ item.key }}" block: - name: Module x509 | Prepare _db informations ansible.builtin.set_fact: @@ -36,23 +39,30 @@ 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 + schema_path_mysql: /usr/share/icingaweb2/modules/x509/schema/mysql.schema.sql + schema_path_pgsql: /usr/share/icingaweb2/modules/x509/schema/pgsql.schema.sql select_query: "select * from x509_certificate" - when: vars['icingaweb2_modules'][_module]['database']['type'] | default('mysql') == 'mysql' + 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: "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' + fail_msg: "Invalid database type was provided. [Supported: mysql, pgsql]" + when: _db.type not in ['mysql', 'pgsql'] - - name: Module x509 | Import Schema + - name: Module x509 | Import MySQL Schema ansible.builtin.include_tasks: ../manage_mysql_imports.yml + when: _db.type == 'mysql' + + - name: Module x509 | Import PostgresQL Schema + ansible.builtin.include_tasks: ../manage_pgsql_imports.yml + when: _db.type == 'pgsql' - 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: >