telekom_mms.icinga_director.ansible_icinga role – Configure an Icinga instance with Icinga Director

Note

This role is part of the telekom_mms.icinga_director collection (version 2.2.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 telekom_mms.icinga_director.

To use it in a playbook, specify: telekom_mms.icinga_director.ansible_icinga.

Entry point icinga_service_apply – Configure an Icinga instance with Icinga Director

Synopsis

  • The main entry point includes all tasks for objects that can be created with the role.

Parameters

Parameter

Comments

icinga_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.

icinga_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.

icinga_url

string

HTTP, HTTPS, or FTP URL in the form (http|https|ftp)://[user[:pass]]@host.domain[:port]/path

icinga_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.

icinga_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

icinga_use_gssapi

boolean

Use GSSAPI to perform the authentication, typically this is for Kerberos or Kerberos through Negotiate authentication. Requires the Python library gssapi <https://github.com/pythongssapi/python- 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

icinga_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)

icinga_validate_certs

boolean

If `no’, SSL certificates will not be validated. icinga_This should only be used on personally controlled sites using selfigned certificates.

Choices:

  • false

  • true ← (default)

Entry point main – Configure an Icinga instance with Icinga Director

Synopsis

  • The main entry point includes all tasks for objects that can be created with the role.

Parameters

Parameter

Comments

icinga_command_templates

list / elements=string

A list of Icinga command_templates to configure

arguments

dictionary

Arguments of the command template.

command

string

The command Icinga should run.

Absolute paths are accepted as provided, relative paths are prefixed with “PluginDir + “, similar Constant prefixes are allowed.

Spaces will lead to separation of command path and standalone arguments.

Please note that this means that we do not support spaces in plugin names and paths right now.

command_type

string

Plugin Check commands are what you need when running checks against your infrastructure.

Notification commands will be used when it comes to notify your users.

Event commands allow you to trigger specific actions when problems occur.

Some people use them for auto-healing mechanisms, like restarting services or rebooting systems at specific thresholds.

Choices:

  • "PluginCheck" ← (default)

  • "PluginNotification"

  • "PluginEvent"

disabled

boolean

Disabled objects will not be deployed.

Choices:

  • false ← (default)

  • true

imports

list / elements=string

Importable templates, add as many as you want. Please note that order matters when importing properties from multiple templates - last one wins.

name

string / required

Name of the command template.

state

string

Apply feature state.

Choices:

  • "present" ← (default)

  • "absent"

timeout

string

Optional command timeout. Allowed values are seconds or durations postfixed with a specific unit (for example 1m or also 3m 30s).

vars

dictionary

Custom properties of the command template.

zone

string

Icinga cluster zone. Allows to manually override Directors decisions of where to deploy your config to.

You should consider not doing so unless you gained deep understanding of how an Icinga Cluster stack works.

icinga_commands

list / elements=string

A list of Icinga commands to configure

arguments

dictionary

Arguments of the command.

command

string

The command Icinga should run. Required when state is present.

Absolute paths are accepted as provided, relative paths are prefixed with “PluginDir + “, similar Constant prefixes are allowed.

Spaces will lead to separation of command path and standalone arguments.

Please note that this means that we do not support spaces in plugin names and paths right now.

command_type

string

Plugin Check commands are what you need when running checks against your infrastructure.

Notification commands will be used when it comes to notify your users.

Event commands allow you to trigger specific actions when problems occur.

Some people use them for auto-healing mechanisms, like restarting services or rebooting systems at specific thresholds.

Choices:

  • "PluginCheck" ← (default)

  • "PluginNotification"

  • "PluginEvent"

disabled

boolean

Disabled objects will not be deployed.

Choices:

  • false ← (default)

  • true

imports

list / elements=string

Importable templates, add as many as you want. Please note that order matters when importing properties from multiple templates - last one wins.

name

string / required

Name of the command.

state

string

Apply feature state.

Choices:

  • "present" ← (default)

  • "absent"

timeout

string

Optional command timeout. Allowed values are seconds or durations postfixed with a specific unit (for example 1m or also 3m 30s).

vars

dictionary

Custom properties of the command.

zone

string

Icinga cluster zone. Allows to manually override Directors decisions of where to deploy your config to.

You should consider not doing so unless you gained deep understanding of how an Icinga Cluster stack works.

icinga_endpoints

list / elements=string

A list of Icinga endpoints to configure

host

string

The hostname/IP address of the remote Icinga 2 instance.

log_duration

string

Duration for keeping replay logs on connection loss. Defaults to 1d (86400 seconds). Attribute is specified in seconds. If log_duration is set to 0, replaying logs is disabled. You could also specify the value in human readable format like 10m for 10 minutes or 1h for one hour.

name

string / required

Icinga object name for this endpoint.

This is usually a fully qualified host name but it could basically be any kind of string.

To make things easier for your users we strongly suggest to use meaningful names for templates.

For example “generic-endpoint” is ugly, “Standard Linux Server” is easier to understand.

port

integer

The service name/port of the remote Icinga 2 instance. Defaults to 5665.

state

string

Apply feature state.

Choices:

  • "present" ← (default)

  • "absent"

zone

string

The name of the zone this endpoint is part of.

icinga_host_templates

list / elements=string

A list of Icinga host_templates to configure

accept_config

boolean

added in telekom_mms.icinga_director 1.9.0

Whether the agent is configured to accept config.

Choices:

  • false

  • true

address

string

Host address. Usually an IPv4 address, but may be any kind of address your check plugin is able to deal with.

address6

string

Host IPv6 address. Usually an IPv64 address, but may be any kind of address your check plugin is able to deal with.

check_command

string

The name of the check command.

Though this is not required to be defined in the director, you still have to supply a check_command in a host or host-template.

check_interval

string

Your regular check interval.

disabled

boolean

Disabled objects will not be deployed.

Choices:

  • false ← (default)

  • true

display_name

string

Alternative name for this host.

Might be a host alias or and kind of string helping your users to identify this host.

event_command

string

Event command for host which gets called on every check execution if one of these conditions matches

The host is in a soft state

The host state changes into a hard state

The host state recovers from a soft or hard state to OK/Up

groups

list / elements=string

Hostgroups that should be directly assigned to this node. Hostgroups can be useful for various reasons.

You might assign service checks based on assigned hostgroup. They are also often used as an instrument to enforce restricted views in Icinga Web 2.

Hostgroups can be directly assigned to single hosts or to host templates.

You might also want to consider assigning hostgroups using apply rules.

Default: []

has_agent

boolean

added in telekom_mms.icinga_director 1.9.0

Whether this host has the Icinga 2 Agent installed.

Choices:

  • false

  • true

imports

list / elements=string

Choose a host-template.

master_should_connect

boolean

added in telekom_mms.icinga_director 1.9.0

Whether the parent (master) node should actively try to connect to this agent.

Choices:

  • false

  • true

name

string / required

Icinga object name for this host template.

This is usually a fully qualified host name but it could basically be any kind of string.

To make things easier for your users we strongly suggest to use meaningful names for templates.

For example “generic-host” is ugly, “Standard Linux Server” is easier to understand.

notes

string

added in telekom_mms.icinga_director 1.8.0

Additional notes for this object.

notes_url

string

added in telekom_mms.icinga_director 1.8.0

An URL pointing to additional notes for this object.

Separate multiple urls like this “http://url1 http://url2”

Maximum length is 255 characters.

state

string

Apply feature state.

Choices:

  • "present" ← (default)

  • "absent"

vars

dictionary

Custom properties of the host.

zone

string

Set the zone.

icinga_hostgroups

list / elements=string

A list of Icinga hostgroups to configure

assign_filter

string

This allows you to configure an assignment filter.

Please feel free to combine as many nested operators as you want.

display_name

string

An alternative display name for this group.

If you wonder how this could be helpful just leave it blank.

name

string / required

Icinga object name for this hostgroup.

state

string

Apply feature state.

Choices:

  • "present" ← (default)

  • "absent"

icinga_hosts

list / elements=string

A list of Icinga hosts to configure

accept_config

boolean

added in telekom_mms.icinga_director 1.9.0

Whether the agent is configured to accept config.

Choices:

  • false

  • true

address

string

Host address. Usually an IPv4 address, but may be any kind of address your check plugin is able to deal with.

address6

string

added in telekom_mms.icinga_director 1.4.0

Host IPv6 address. Usually an IPv6 address, but may be any kind of address your check plugin is able to deal with.

check_command

string

The name of the check command.

Though this is not required to be defined in the director, you still have to supply a check_command in a host or host-template.

disabled

boolean

Disabled objects will not be deployed.

Choices:

  • false ← (default)

  • true

display_name

string

Alternative name for this host. Might be a host alias or and kind of string helping your users to identify this host.

groups

list / elements=string

Hostgroups that should be directly assigned to this node. Hostgroups can be useful for various reasons.

You might assign service checks based on assigned hostgroup. They are also often used as an instrument to enforce restricted views in Icinga Web 2.

Hostgroups can be directly assigned to single hosts or to host templates.

You might also want to consider assigning hostgroups using apply rules.

Default: []

has_agent

boolean

added in telekom_mms.icinga_director 1.9.0

Whether this host has the Icinga 2 Agent installed.

Choices:

  • false

  • true

imports

list / elements=string / required

Choose a Host Template. Required when state is present.

master_should_connect

boolean

added in telekom_mms.icinga_director 1.9.0

Whether the parent (master) node should actively try to connect to this agent.

Choices:

  • false

  • true

name

string / required

Icinga object name for this host.

This is usually a fully qualified host name but it could basically be any kind of string.

To make things easier for your users we strongly suggest to use meaningful names for templates.

For example “generic-host” is ugly, “Standard Linux Server” is easier to understand.

notes

string

added in telekom_mms.icinga_director 1.8.0

Additional notes for this object.

notes_url

string

added in telekom_mms.icinga_director 1.8.0

An URL pointing to additional notes for this object.

Separate multiple urls like this “http://url1 http://url2”

The maximum length is 255 characters.

state

string

Apply feature state.

Choices:

  • "present" ← (default)

  • "absent"

vars

dictionary

Custom properties of the host.

zone

string

Set the zone.

icinga_notifications

list / elements=string

A list of Icinga notifications to configure

apply_to

string / required

Whether this notification should affect hosts or services.

Choices:

  • "host"

  • "service"

assign_filter

string

The filter where the notification will take effect.

disabled

boolean

added in telekom_mms.icinga_director 1.9.0

Disabled objects will not be deployed.

Choices:

  • false ← (default)

  • true

imports

list / elements=string

Importable templates, add as many as you want. Required when state is present.

Please note that order matters when importing properties from multiple templates - last one wins.

name

string / required

Name of the notification.

notification_interval

string

The notification interval (in seconds). This interval is used for active notifications.

Defaults to 30 minutes. If set to 0, re-notifications are disabled.

state

string

Apply feature state.

Choices:

  • "present" ← (default)

  • "absent"

states

list / elements=string

added in telekom_mms.icinga_director 1.9.0

The host or service states you want to get notifications for.

time_period

string

added in telekom_mms.icinga_director 1.15.0

The name of a time period which determines when this notification should be triggered.

times_begin

integer

added in telekom_mms.icinga_director 1.15.0

First notification delay.

Delay unless the first notification should be sent.

times_end

integer

added in telekom_mms.icinga_director 1.15.0

Last notification.

When the last notification should be sent.

types

list / elements=string

The state transition types you want to get notifications for.

user_groups

list / elements=string

added in telekom_mms.icinga_director 1.16.0

User Groups that should be notified by this notification.

users

list / elements=string

Users that should be notified by this notification.

vars

dictionary

added in telekom_mms.icinga_director 1.9.0

Custom properties of the notification.

icinga_service_applies

list / elements=string

A list of Icinga service_applies to configure

apply_for

string

Evaluates the apply for rule for all objects with the custom attribute specified.

For example selecting “host.vars.custom_attr” will generate “for (config in host.vars.array_var)” where “config” will be accessible through “$config$”.

Note - only custom variables of type “Array” are eligible.

assign_filter

string

The filter where the service apply rule will take effect.

check_command

string

added in telekom_mms.icinga_director 1.7.0

Check command definition.

check_interval

string

Your regular check interval.

check_period

string

The name of a time period which determines when this object should be monitored. Not limited by default.

check_timeout

string

Check command timeout in seconds. Overrides the CheckCommand’s timeout attribute.

command_endpoint

string

The host where the service should be executed on.

display_name

string

Alternative displayed name of the service apply rule.

enable_active_checks

boolean

Whether to actively check this object.

Choices:

  • false

  • true

enable_event_handler

boolean

Whether to enable event handlers this object.

Choices:

  • false

  • true

enable_notifications

boolean

Whether to send notifications for this object.

Choices:

  • false

  • true

enable_passive_checks

boolean

Whether to accept passive check results for this object.

Choices:

  • false

  • true

enable_perfdata

boolean

Whether to process performance data provided by this object.

Choices:

  • false

  • true

groups

list / elements=string

Service groups that should be directly assigned to this service.

Servicegroups can be useful for various reasons.

They are helpful to provided service-type specific view in Icinga Web 2, either for custom dashboards or as an instrument to enforce restrictions.

Service groups can be directly assigned to single services or to service templates.

imports

list / elements=string

Importable templates, add as many as you want.

Please note that order matters when importing properties from multiple templates - last one wins.

max_check_attempts

string

Defines after how many check attempts a new hard state is reached.

name

string / required

Name for the Icinga service apply rule.

notes

string

Additional notes for this object.

notes_url

string

An URL pointing to additional notes for this object.

Separate multiple urls like this “http://url1 http://url2”

Maximum length is 255 characters.

retry_interval

string

Retry interval, will be applied after a state change unless the next hard state is reached.

state

string

Apply feature state.

Choices:

  • "present" ← (default)

  • "absent"

vars

dictionary

Custom properties of the service apply rule.

icinga_service_templates

list / elements=string

A list of Icinga service_templates to configure

check_command

string

Check command definition.

check_interval

string

Your regular check interval.

check_period

string

The name of a time period which determines when this object should be monitored. Not limited by default.

check_timeout

string

Check command timeout in seconds. Overrides the CheckCommand’s timeout attribute.

disabled

boolean

Disabled objects will not be deployed.

Choices:

  • false ← (default)

  • true

enable_active_checks

boolean

Whether to actively check this object.

Choices:

  • false

  • true

enable_event_handler

boolean

Whether to enable event handlers this object.

Choices:

  • false

  • true

enable_notifications

boolean

Whether to send notifications for this object.

Choices:

  • false

  • true

enable_passive_checks

boolean

Whether to accept passive check results for this object.

Choices:

  • false

  • true

enable_perfdata

boolean

Whether to process performance data provided by this object.

Choices:

  • false

  • true

event_command

string

Event command for service which gets called on every check execution if one of these conditions matches

The service is in a soft state

The service state changes into a hard state

The service state recovers from a soft or hard state to OK/Up

groups

list / elements=string

Service groups that should be directly assigned to this service.

Servicegroups can be useful for various reasons.

They are helpful to provided service-type specific view in Icinga Web 2, either for custom dashboards or as an instrument to enforce restrictions.

Service groups can be directly assigned to single services or to service templates.

Default: []

imports

list / elements=string

Importable templates, add as many as you want.

Please note that order matters when importing properties from multiple templates - last one wins.

Default: []

max_check_attempts

string

Defines after how many check attempts a new hard state is reached.

name

string / required

Name of the service template.

notes

string

added in telekom_mms.icinga_director 1.8.0

Additional notes for this object.

notes_url

string

added in telekom_mms.icinga_director 1.8.0

An URL pointing to additional notes for this object.

Separate multiple urls like this “http://url1 http://url2”

Maximum length is 255 characters.

retry_interval

string

Retry interval, will be applied after a state change unless the next hard state is reached.

state

string

Apply feature state.

Choices:

  • "present" ← (default)

  • "absent"

use_agent

boolean

Whether the check command for this service should be executed on the Icinga agent.

Choices:

  • false

  • true

vars

dictionary

Custom properties of the service template.

Default: {}

volatile

boolean

Whether this check is volatile.

Choices:

  • false

  • true

icinga_servicegroups

list / elements=string

A list of Icinga sservicegroups to configure

assign_filter

string

This allows you to configure an assignment filter.

Please feel free to combine as many nested operators as you want.

display_name

string

An alternative display name for this group.

If you wonder how this could be helpful just leave it blank.

name

string / required

Name for the Icinga servicegroup.

state

string

Apply feature state.

Choices:

  • "present" ← (default)

  • "absent"

icinga_services

list / elements=string

A list of Icinga services to configure

check_command

string

Check command definition.

check_interval

string

Your regular check interval.

check_period

string

The name of a time period which determines when this object should be monitored. Not limited by default.

check_timeout

string

Check command timeout in seconds. Overrides the CheckCommand’s timeout attribute.

disabled

boolean

Disabled objects will not be deployed.

Choices:

  • false ← (default)

  • true

enable_active_checks

boolean

Whether to actively check this object.

Choices:

  • false

  • true

enable_event_handler

boolean

Whether to enable event handlers this object.

Choices:

  • false

  • true

enable_notifications

boolean

Whether to send notifications for this object.

Choices:

  • false

  • true

enable_passive_checks

boolean

Whether to accept passive check results for this object.

Choices:

  • false

  • true

enable_perfdata

boolean

Whether to process performance data provided by this object.

Choices:

  • false

  • true

groups

list / elements=string

Service groups that should be directly assigned to this service.

Servicegroups can be useful for various reasons.

They are helpful to provided service-type specific view in Icinga Web 2, either for custom dashboards or as an instrument to enforce restrictions.

Service groups can be directly assigned to single services or to service templates.

Default: []

host

string / required

Choose the host this single service should be assigned to.

imports

list / elements=string

Importable templates, add as many as you want.

Please note that order matters when importing properties from multiple templates - last one wins.

Default: []

max_check_attempts

string

Defines after how many check attempts a new hard state is reached.

name

string / required

Name of the service.

notes

string

added in telekom_mms.icinga_director 1.8.0

Additional notes for this object.

notes_url

string

added in telekom_mms.icinga_director 1.8.0

An URL pointing to additional notes for this object.

Separate multiple urls like this “http://url1 http://url2”

Maximum length is 255 characters.

retry_interval

string

Retry interval, will be applied after a state change unless the next hard state is reached.

state

string

Apply feature state.

Choices:

  • "present" ← (default)

  • "absent"

use_agent

boolean

Whether the check command for this service should be executed on the Icinga agent.

Choices:

  • false

  • true

vars

dictionary

Custom properties of the service.

Default: {}

volatile

boolean

Whether this check is volatile.

Choices:

  • false

  • true

icinga_timeperiods

list / elements=string

A list of Icinga timeperiods to configure

display_name

string

Alternative name for this timeperiod.

imports

list / elements=string

Importable templates, add as many as you want.

Please note that order matters when importing properties from multiple templates - last one wins.

name

string

Name of the time period.

ranges

dictionary

A dict of days and timeperiods.

state

string

Apply feature state.

Choices:

  • "present" ← (default)

  • "absent"

icinga_user_templates

list / elements=string

A list of Icinga user_templates to configure

enable_notifications

boolean

Whether to send notifications for this user.

Choices:

  • false

  • true

imports

list / elements=string

Importable templates, add as many as you want.

Please note that order matters when importing properties from multiple templates - last one wins.

name

string / required

Name of the user template.

period

string

The name of a time period which determines when notifications to this User should be triggered. Not set by default.

state

string

Apply feature state.

Choices:

  • "present" ← (default)

  • "absent"

vars

dictionary

Custom properties of the user.

Default: {}

icinga_users

list / elements=string

A list of Icinga users to configure

disabled

boolean

Disabled objects will not be deployed.

Choices:

  • false ← (default)

  • true

display_name

string

Alternative name for this user.

In case your object name is a username, this could be the full name of the corresponding person.

email

string

The Email address of the user.

groups

list / elements=string

User groups that should be directly assigned to this user.

Groups can be useful for various reasons. You might prefer to send notifications to groups instead of single users.

imports

list / elements=string

Importable templates, add as many as you want.

Please note that order matters when importing properties from multiple templates - last one wins.

name

string / required

Name of the user.

pager

string

The pager address of the user.

period

string

The name of a time period which determines when notifications to this User should be triggered. Not set by default.

state

string

Apply feature state.

Choices:

  • "present" ← (default)

  • "absent"

vars

dictionary

Custom properties of the user.

Default: {}

icinga_zones

list / elements=string

A list of Icinga zones to configure

is_global

boolean

Whether configuration files for this zone should be synced to all endpoints.

Choices:

  • false ← (default)

  • true

name

string / required

Icinga object name for this zone.

This is usually a fully qualified host name but it could basically be any kind of string.

To make things easier for your users we strongly suggest to use meaningful names for templates.

For example “generic-zone” is ugly, “Standard Linux Server” is easier to understand.

parent

string

The name of the parent zone.

state

string

Apply feature state.

Choices:

  • "present" ← (default)

  • "absent"