telekom_mms.icinga_director.icinga_syncrule module – Manage sync rules in Icinga2 Director

Note

This module is part of the telekom_mms.icinga_director collection (version 2.6.1).

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

New in telekom_mms.icinga_director 2.0.0

Synopsis

  • Add or remove a sync rule in Icinga2 Director through the director API.

Parameters

Parameter

Comments

api_timeout

integer

Default timeout to wait for transaction to finish in seconds.

Default: 10

append

boolean

added in telekom_mms.icinga_director 2.0.0

Do not overwrite the whole object but instead append the defined properties.

Note - Appending to existing vars, imports or any other list/dict is not possible. You have to overwrite the complete list/dict.

Note - Variables that are set by default will also be applied, even if not set.

Choices:

  • false

  • true

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.

description

string

An optional description for this sync rule.

filter_expression

string

An optional filter expression to restrict which imported rows are processed by this sync rule.

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"

object_type

string

The Icinga object type that this sync rule targets.

This is the type of Icinga object that will be created or updated by the sync rule, not to be confused with the Director object_type (object/template/apply).

Choices:

  • "host"

  • "service"

  • "command"

  • "user"

  • "hostgroup"

  • "servicegroup"

  • "usergroup"

  • "datalistEntry"

  • "endpoint"

  • "zone"

  • "timePeriod"

  • "serviceSet"

  • "scheduledDowntime"

  • "notification"

  • "dependency"

purge_action

string

Action to take when purging objects that no longer exist in the import source.

Only relevant when purge_existing is true.

Choices:

  • "delete"

  • "disable"

purge_existing

boolean

Whether to remove Icinga objects that are no longer present in the import source.

Choices:

  • false

  • true

rule_name

aliases: name

string / required

Name of the sync rule.

This must be unique across all sync rules in Icinga Director.

state

string

Apply feature state.

Choices:

  • "present" ← (default)

  • "absent"

sync_properties

list / elements=dictionary

List of sync property mappings from import-source columns to Icinga object fields.

Each entry must contain source (import source name), destination_field (Icinga property such as object_name, address, display_name), and source_expression (the column name from the import source).

Optional per-entry keys are merge_policy (default override) and filter_expression.

When omitted the module does not manage sync properties (existing properties are preserved).

update_policy

string

Defines how existing Icinga objects are updated when the sync rule runs.

merge merges properties from the import source with existing object properties.

override replaces all properties of existing objects with values from the import source.

ignore does not modify existing objects, only creates new ones.

update-only only updates existing objects, never creates new ones.

Choices:

  • "merge"

  • "override"

  • "ignore"

  • "update-only"

url

string / required

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

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)

Notes

Note

  • This module supports check mode.

  • Uses the standard /director/syncrules bulk endpoint (GET/POST/DELETE). Requires Director with upstream PR adding POST and DELETE support to SyncrulesController and unserializeSyncRules in ImportExport.

Examples

- name: Create a sync rule in icinga
  telekom_mms.icinga_director.icinga_syncrule:
    state: present
    url: "{{ icinga_url }}"
    url_username: "{{ icinga_user }}"
    url_password: "{{ icinga_pass }}"
    rule_name: "Sync Hosts from CMDB"
    object_type: "host"
    update_policy: "merge"
    purge_existing: false
    description: "Synchronizes hosts from the CMDB import source"

- name: Create a sync rule that purges deleted objects
  telekom_mms.icinga_director.icinga_syncrule:
    state: present
    url: "{{ icinga_url }}"
    url_username: "{{ icinga_user }}"
    url_password: "{{ icinga_pass }}"
    rule_name: "Sync Services from CMDB"
    object_type: "service"
    update_policy: "override"
    purge_existing: true
    purge_action: "disable"
    filter_expression: 'source.vars.monitored="yes"'

- name: Update the description of a sync rule
  telekom_mms.icinga_director.icinga_syncrule:
    state: present
    url: "{{ icinga_url }}"
    url_username: "{{ icinga_user }}"
    url_password: "{{ icinga_pass }}"
    rule_name: "Sync Hosts from CMDB"
    description: "Updated description"
    append: true

- name: Delete a sync rule in icinga
  telekom_mms.icinga_director.icinga_syncrule:
    state: absent
    url: "{{ icinga_url }}"
    url_username: "{{ icinga_user }}"
    url_password: "{{ icinga_pass }}"
    rule_name: "Sync Hosts from CMDB"

Authors

  • Michaela Mattes (@mikaEz)