From: Michael Friedrich Date: Fri, 27 Apr 2018 14:16:59 +0000 (+0200) Subject: Enhance advanced topics with (scheduled) downtimes X-Git-Tag: v2.9.0~71^2 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=refs%2Fpull%2F6271%2Fhead;p=icinga2 Enhance advanced topics with (scheduled) downtimes --- diff --git a/doc/04-configuring-icinga-2.md b/doc/04-configuring-icinga-2.md index 5b2dfa1f2..61e920126 100644 --- a/doc/04-configuring-icinga-2.md +++ b/doc/04-configuring-icinga-2.md @@ -653,8 +653,10 @@ More details on `Notification` object attributes can be found [here](09-object-t The `load` service apply rule defined in [services.conf](04-configuring-icinga-2.md#services-conf) defines the `backup_downtime` custom attribute. -The [ScheduledDowntime](09-object-types.md#objecttype-scheduleddowntime) apply rule uses this attribute -to define the default value for the time ranges required for recurring downtime slots. +The ScheduledDowntime apply rule uses this attribute to define the default value +for the time ranges required for recurring downtime slots. + +Learn more about downtimes in [this chapter](08-advanced-topics.md#downtimes). apply ScheduledDowntime "backup-downtime" to Service { author = "icingaadmin" diff --git a/doc/06-distributed-monitoring.md b/doc/06-distributed-monitoring.md index bdbff6555..91b8e9748 100644 --- a/doc/06-distributed-monitoring.md +++ b/doc/06-distributed-monitoring.md @@ -1844,7 +1844,7 @@ to all nodes depending on them. Common examples are: * Templates which are imported into zone specific objects. * Command objects referenced by Host, Service, Notification objects. -* Apply rules for services, notifications, dependencies and scheduled downtimes. +* Apply rules for services, notifications and dependencies. * User objects referenced in notifications. * Group objects. * TimePeriod objects. @@ -1892,7 +1892,7 @@ into your global zone. Example: [root@icinga2-master1.localdomain /]# cd /etc/icinga2/conf.d - [root@icinga2-master1.localdomain /etc/icinga2/conf.d]# cp {commands,downtimes,groups,notifications,services,templates,timeperiods,users}.conf /etc/icinga2/zones.d/global-templates + [root@icinga2-master1.localdomain /etc/icinga2/conf.d]# cp {commands,groups,notifications,services,templates,timeperiods,users}.conf /etc/icinga2/zones.d/global-templates ### Health Checks diff --git a/doc/08-advanced-topics.md b/doc/08-advanced-topics.md index 0cbf93362..c51a303d7 100644 --- a/doc/08-advanced-topics.md +++ b/doc/08-advanced-topics.md @@ -8,22 +8,36 @@ can safely skip over things you're not interested in. Downtimes can be scheduled for planned server maintenance or any other targeted service outage you are aware of in advance. -Downtimes will suppress any notifications, and may trigger other +Downtimes suppress notifications and can trigger other downtimes too. If the downtime was set by accident, or the duration -exceeds the maintenance, you can manually cancel the downtime. -Planned downtimes will also be taken into account for SLA reporting -tools calculating the SLAs based on the state and downtime history. +exceeds the maintenance windows, you can manually cancel the downtime. + +### Scheduling a downtime + +The most convenient way to schedule planned downtimes is to create +them in Icinga Web 2 inside the host/service detail view. Select +multiple hosts/services from the listing with the shift key to +schedule multiple downtimes. + +![Downtime in Icinga Web 2](images/advanced-topics/icingaweb2_downtime_handled.png) + +In addition to that you can schedule a downtime by using the Icinga 2 API action +[schedule-downtime](12-icinga2-api.md#icinga2-api-actions-schedule-downtime). +This is especially useful to schedule a downtime on-demand inside a (remote) backup +script, or create maintenance downtimes from a cron job for specific dates and intervals. Multiple downtimes for a single object may overlap. This is useful when you want to extend your maintenance window taking longer than expected. If there are multiple downtimes triggered for one object, the overall downtime depth will be greater than `1`. - If the downtime was scheduled after the problem changed to a critical hard state triggering a problem notification, and the service recovers during the downtime window, the recovery notification won't be suppressed. +Planned downtimes are also taken into account for SLA reporting +tools calculating the SLAs based on the state and downtime history. + ### Fixed and Flexible Downtimes A `fixed` downtime will be activated at the defined start time, and @@ -51,13 +65,6 @@ For that reason, you may want to schedule a downtime between 07:30 and its trigger time until the duration is over. After that, the downtime is removed (may happen before or after the actual end time!). -### Scheduling a downtime - -You can schedule a downtime either by using the Icinga 2 API action -[schedule-downtime](12-icinga2-api.md#icinga2-api-actions-schedule-downtime) or -by sending an [external command](14-features.md#external-commands). - - #### Fixed Downtime If the host/service changes into a NOT-OK state between the start and @@ -102,22 +109,37 @@ recurring downtimes for services. Example: - apply ScheduledDowntime "backup-downtime" to Service { - author = "icingaadmin" - comment = "Scheduled downtime for backup" +``` +apply ScheduledDowntime "backup-downtime" to Service { + author = "icingaadmin" + comment = "Scheduled downtime for backup" - ranges = { - monday = "02:00-03:00" - tuesday = "02:00-03:00" - wednesday = "02:00-03:00" - thursday = "02:00-03:00" - friday = "02:00-03:00" - saturday = "02:00-03:00" - sunday = "02:00-03:00" - } + ranges = { + monday = "02:00-03:00" + tuesday = "02:00-03:00" + wednesday = "02:00-03:00" + thursday = "02:00-03:00" + friday = "02:00-03:00" + saturday = "02:00-03:00" + sunday = "02:00-03:00" + } - assign where "backup" in service.groups - } + assign where "backup" in service.groups +} +``` + +Icinga 2 attempts to find the next possible segment from a ScheduledDowntime object's +`ranges` attribute, and wont create multiple downtimes in the future. In case you need +all these downtimes planned and visible for the next days, weeks or months, schedule them +manually via the [REST API](12-icinga2-api.md#icinga2-api-actions-schedule-downtime) using +a script or cron job. + +> **Note** +> +> If ScheduledDowntime objects are synced in a distributed high-availability setup, +> both will create the next possible downtime on their own. These runtime generated +> downtimes are synced among both zone instances, and you may see sort-of duplicate downtimes +> in Icinga Web 2. ## Comments diff --git a/doc/images/advanced-topics/icingaweb2_downtime_handled.png b/doc/images/advanced-topics/icingaweb2_downtime_handled.png new file mode 100644 index 000000000..3fe26902c Binary files /dev/null and b/doc/images/advanced-topics/icingaweb2_downtime_handled.png differ