community.general.icinga2_downtime module – Manages Icinga 2 downtimes

Note

This module is part of the community.general collection (version 12.4.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.icinga2_downtime.

New in community.general 12.4.0

Synopsis

Parameters

Parameter

Comments

all_services

boolean

Whether downtimes should be created for all services of the matched host objects.

If omitted, Icinga 2 does not create downtimes for all services of the matched host objects by default.

Choices:

  • false

  • true

author

string

Name of the author.

Default: "Ansible"

ca_path

path

CA certificates bundle to use to verify the Icinga 2 server certificate.

child_options

string

Schedule child downtimes.

Choices:

  • "DowntimeNoChildren"

  • "DowntimeTriggeredChildren"

  • "DowntimeNonTriggeredChildren"

client_cert

path

PEM formatted certificate chain file to be used for SSL client authentication.

This file can also include the key as well, and if the key is included, client_key is not required.

client_key

path

PEM formatted file that contains your private key to be used for SSL client authentication.

If client_cert contains both the certificate and key, this option is not required.

comment

string

A descriptive comment.

Default: "Downtime scheduled by Ansible"

duration

integer

Duration of the downtime.

Required in case of a flexible downtime.

end_time

integer

End time of the downtime as UNIX timestamp.

filter

string

Filter expression limiting the objects to operate on.

filter_vars

dictionary

Variable names and values used in the filter expression.

fixed

boolean

Whether the downtime is fixed or flexible.

If omitted, Icinga 2 creates a fixed downtime by default.

Choices:

  • false

  • true

force

boolean

If yes do not get a cached copy.

Choices:

  • false ← (default)

  • true

force_basic_auth

boolean

Credentials specified with url_username and url_password should be passed in HTTP Header.

Choices:

  • false ← (default)

  • true

http_agent

string

Header to identify as, generally appears in web server logs.

Default: "ansible-httpget"

name

string

Name of the downtime object.

This option has no effect for states other than absent.

object_type

string

Use Host for a host downtime and Service for a service downtime.

Use Downtime and give the name of the downtime object you want to remove.

Choices:

  • "Service"

  • "Host" ← (default)

  • "Downtime"

start_time

integer

Start time of the downtime as UNIX timestamp.

state

string

State of the downtime.

Choices:

  • "present" ← (default)

  • "absent"

timeout

integer

How long to wait for the server to send data before giving up.

Default: 10

trigger_name

string

Name of the downtime trigger.

url

string / required

URL of the Icinga 2 REST API.

url_password

string

The password for use in HTTP basic authentication.

If the url_username parameter is not specified, the url_password parameter will not be used.

url_username

string

The username for use in HTTP basic authentication.

This parameter can be used without url_password for sites that allow empty passwords.

use_gssapi

boolean

added in ansible-core 2.11

Use GSSAPI to perform the authentication, typically this is for Kerberos or Kerberos through Negotiate authentication.

Requires the Python library gssapi to be installed.

Credentials for GSSAPI can be specified with url_username/url_password or with the GSSAPI env var KRB5CCNAME that specified a custom Kerberos credential cache.

NTLM authentication is not supported even if the GSSAPI mech for NTLM has been installed.

Choices:

  • false ← (default)

  • true

use_proxy

boolean

If no, it will not use a proxy, even if one is defined in an environment variable on the target hosts.

Choices:

  • false

  • true ← (default)

validate_certs

boolean

If no, SSL certificates will not be validated.

This should only be used on personally controlled sites using self-signed certificates.

Choices:

  • false

  • true ← (default)

Attributes

Attribute

Support

Description

check_mode

Support: none

In case of a complex filter expression, it may become very complex to decide whether downtime creation or removal will succeed and trigger a change.

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: none

Returns details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Examples

- name: Schedule a host downtime
  community.general.icinga2_downtime:
    url: "https://icinga2.example.com:5665"
    url_username: icingadmin
    url_password: secret
    state: present
    author: Ansible
    comment: Scheduled downtime for test purposes.
    all_services: true
    start_time: "{{ downtime_start_time }}"
    end_time: "{{ downtime_end_time }}"
    duration: "{{ downtime_duration }}"
    fixed: true
    object_type: Host
    filter: host.name=="host.example.com"
  delegate_to: localhost
  register: icinga2_downtime_response
  vars:
    downtime_start_time: "{{ ansible_date_time['epoch'] | int }}"
    downtime_end_time: "{{ downtime_start_time | int + 3600 }}"
    downtime_duration: "{{ downtime_end_time | int - downtime_start_time | int }}"

- name: Remove scheduled host downtime
  community.general.icinga2_downtime:
    url: "https://icinga2.example.com:5665"
    url_username: icingadmin
    url_password: secret
    state: absent
    author: Ansible
    object_type: Downtime
    name: "{{ icinga2_downtime_response.results[0].name }}"
  delegate_to: localhost
  when: icinga2_downtime_response.results | default([]) | length > 0

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

error

dictionary

Error message as JSON dictionary returned from the Icinga 2 API.

Returned: if downtime scheduling or removal did not succeed

Sample: {"error": 404, "status": "No objects found."}

results

list / elements=dictionary

Results of downtime scheduling or removal

Returned: success

Sample: [{"code": 200, "legacy_id": 28911, "name": "host.example.com!e19c705a-54c2-49c5-8014-70ff624f9e51", "status": "Successfully scheduled downtime 'host.example.com!e19c705a-54c2-49c5-8014-70ff624f9e51' for object 'host.example.com'."}]

code

integer

Success or error code of downtime scheduling.

Returned: always

Sample: 200

legacy_id

integer

Legacy id of the downtime object.

Returned: if a downtime was scheduled successfully

Sample: 28911

name

string

Name of the downtime object.

Returned: if a downtime was scheduled successfully

Sample: "host.example.com!e19c705a-54c2-49c5-8014-70ff624f9e51"

status

string

Human-readable message describing the result of downtime scheduling.

Returned: always

Sample: "Successfully scheduled downtime 'host.example.com!e19c705a-54c2-49c5-8014-70ff624f9e51' for object 'host.example.com'."

Authors

  • Christoph Fiehe (@cfiehe)