diff options
Diffstat (limited to 'doc/10-Migration.md')
| -rw-r--r-- | doc/10-Migration.md | 160 |
1 files changed, 160 insertions, 0 deletions
diff --git a/doc/10-Migration.md b/doc/10-Migration.md new file mode 100644 index 0000000..a8ed80f --- /dev/null +++ b/doc/10-Migration.md @@ -0,0 +1,160 @@ +# Migration + +If you previously used the monitoring module, (built into Icinga Web 2) you may want to +migrate your existing configuration, custom dashboards and navigation items as well as +permissions or restrictions. + +If that is the case, this chapter has you covered. + +## Configuration + +### Command Transports + +Icinga DB Web still uses the same configuration format for command transports. This means that the file +`/etc/icingaweb2/modules/monitoring/commandtransports.ini` can simply be copied over to +`/etc/icingaweb2/modules/icingadb/commandtransports.ini`. + +But note that Icinga DB Web doesn't support the commandfile (local and remote) anymore. Remove all sections +that do **not** define `transport=api`. + +### Protected Customvars + +The rules previously configured at `Configuration -> Modules -> monitoring -> Security` have moved into the +roles configuration as a new restriction. This is called `icingadb/protect/variables` and accepts the same +rules. Just copy them over. + +## Navigation + +The monitoring module provides two custom navigation item types: `host-action` and `service-action` +Icinga DB Web does the same, though uses different type names to achieve that: `icingadb-host-action` +and `icingadb-service-action` + +With Icinga DB Web 1.1, its migrate command allows you to migrate these navigation items automatically: + +`icingacli icingadb migrate navigation --user=<name> [--no-backup] [--override]` + +By default, this only migrates navigation items of specific users and keeps the old ones. The `--user` +switch expects a username, with optional wildcards (`*`) to match multiple users. `--user=*` matches +all users. Pass `--no-backup` to fully remove the old monitoring navigation items. + +A similar version of this command has already been available since Icinga Web 2.9.4. Due to this, the new +command allows you to perform the migration from scratch again with the `--override` switch. (Provided you +still have the old navigation items.) Otherwise, already migrated items are ignored. That's also a difference +to the previous command, which duplicated items instead. + +## Dashboards + +The dashboard item configuration does not change since it is related to Icinga Web. However, items that +reference views of the monitoring module should be changed in order to permanently reference views of +Icinga DB Web. + +With Icinga DB Web 1.1, its migrate command allows you to migrate such dashboard items automatically: + +`icingacli icingadb migrate dashboard --user=<name> [--no-backup]` + +By default, this only migrates dashboards of specific users and creates backups. The `--user` switch +expects a username, with optional wildcards (`*`) to match multiple users. `--user=*` matches all users. +Pass `--no-backup` to disable backup creation. Please note, if you do so, that this makes resetting +changes more difficult. + +### Automation + +For those who integrate Icinga Web into e.g. custom dashboards, there is also a way to automate the +migration of urls. An API endpoint in Icinga DB Web allows for this: + +`/icingaweb2/icingadb/migrate/monitoring-url` + +If you `POST` a JSON list there, you'll get a JSON list back with the transformed urls in it. +The returned list is ordered the same and any unrecognized url is left unchanged: + +**Input:** +```json +[ + "/icingaweb2/monitoring/list/services?hostgroup_name=prod-hosts|(_host_env=prod&_host_stage!=testing)", + "/icingaweb2/businessprocess/process/show?config=production" +] +``` + +**Output**: +```json +[ + "/icingaweb2/icingadb/services?hostgroup.name=prod-hosts|(host.vars.env=prod&host.vars.stage!=testing)", + "/icingaweb2/businessprocess/process/show?config=production" +] +``` + +**cURL example:** +`curl -s -HContent-Type:application/json -HAccept:application/json -u icingaadmin:icinga http://localhost/icingaweb2/icingadb/migrate/monitoring-url -d '["/icingaweb2/monitoring/list/services?hostgroup_name=prod-hosts|(_host_env=prod&_host_stage!=testing)","/icingaweb2/businessprocess/process/show?config=production"]'` + + +## Views and Exports + +### Url Parameter `addColumns` + +The host and service list of the monitoring module allows to show/export additional information per object by using the +URL parameter `addColumns`. Icinga DB Web has a very similar but much enhanced parameter: `columns` + +If you pass this to the host and service list of Icinga DB Web, you'll get an entirely different view mode in which you +have full control over the information displayed. The parameter accepts a comma separated list of columns. This list +also defines the order in which the columns are shown. + +As of now, there is no dedicated control in the UI to conveniently choose those columns. You can use all columns +however, which are valid in the search bar as well. The migration widget, that's shown if you have access to +monitoring and Icinga DB Web, also assists you by providing an example set of columns conveying the same information +shown in the monitoring module lists. + +## Access Control + +### `monitoring/filter/objects` + +This is now `icingadb/filter/objects` but still accepts the same filter syntax. Only the columns have changed +or support for them has been dropped. Check the table below for details: + +| Old Column Name | New Column Name | +|----------------------|------------------------| +| instance\_name | - | +| host\_name | host.name | +| hostgroup\_name | hostgroup.name | +| service\_description | service.name | +| servicegroup\_name | servicegroup.name | +| \_host\_customvar | host.vars.customvar | +| \_service\_customvar | service.vars.customvar | + +### `monitoring/blacklist/properties` + +This is now `icingadb/denylist/variables`. However, it does not accept the same rules as +`monitoring/blacklist/properties`. It still accepts a comma separated list of GLOB like filters, +but with some features removed: + +* No distinction between host and service variables (`host.vars.` and `service.vars.` prefixes are no longer keywords) +* No `**` to cross multiple level boundaries at once (`a.**.d` does not differ from `a.*.d`) +* Dots are not significant (`foo.*.oof` and `foo*oof` will both match `foo.bar.oof`) + +Check the [security chapter](04-Security.md#variable-paths) for more details. + +### Permissions + +The command permissions have not changed. It is only the module identifier that has changed of course: +`monitoring/command/*` is now `icingadb/command/*` + +The `no-monitoring/contacts` permission (or *fake refusal*) is now a restriction: `icingadb/denylist/routes`. +Add `users,usergroups` to it to achieve the same effect. + +### Perform The Migration + +To apply the necessary changes automatically, Icinga DB Web 1.1 provides this command: + +`icingacli icingadb migrate role [--role=<name>] [--group=<name>] [--override] [--no-backup]` + +By default, this only migrates roles with matching names or matching groups, doesn't change roles that were +already manually migrated and creates backups. Either `--role` or `--group` must be passed, but not both. +Both accept wildcards and just `*` matches all roles. Pass `--override` to forcefully update roles that appear +to be already migrated. Please note that this will reset changes made to Icinga DB Web's rules, which were not +equally applied to their monitoring module counterparts. Pass `--no-backup` to disable backup creation. Please +note, if you do so, that this makes resetting changes more difficult. + +With respect to permissions, the command will only migrate the command permissions. If a role grants full or +general access to the monitoring module, this is not automatically migrated. You have to adjust this manually. +It gives you the chance to review the performed changes, before letting them loose on your users. Please also +take in mind, that Icinga DB Web handles permissions and restrictions differently. Our blog provides details +on that: https://icinga.com/blog/2021/04/07/web-access-control-redefined/#icingadb-permission-linkage |