Icinga Director Collection for Ansible

This Ansible collection contains:

Ansible modules to change objects in Icinga 2 using the director API. Additionally all supported modules have an appropriate *_info-module to gather facts about the existing objects in the director.
- icinga_command_template
- icinga_command
- icinga_endpoint
- icinga_host_template
- icinga_host
- icinga_hostgroup
- icinga_notification
- icinga_notification_template
- icinga_service
- icinga_service_apply
- icinga_service_template
- icinga_servicegroup
- icinga_serviceset
- icinga_timeperiod
- icinga_timeperiod_template
- icinga_user_group
- icinga_user_template
- icinga_user
- icinga_zone
A module to deploy changes in the director and a corresponding info-module.
A role to change objects in Icinga 2 using the the provided modules.
An inventory plugin to use hosts and groups defined in Icinga as a dynamic inventory.

Required Ansible version: 2.14.0

Recommended Icinga-Director version: 2.11.1

Installation

If you use Ansible >=3.0.0, this collection is included in Ansible.

If you use an older version, you can install it with Ansible Galaxy:

ansible-galaxy collection install telekom_mms.icinga_director

Alternatively put the collection into a requirements.yml-file:

---
collections:
- telekom_mms.icinga_director

Documentation

Our modules include documentation.

You can find the complete documentation for the modules in the docs-folder or in the Ansible documentation.

To display it on the command-line you can use the ansible-doc command.

For example, to see the documentation for the module icinga_host run the following command on the cli:

ansible-doc telekom_mms.icinga_director.icinga_host

To see the documentation for the inventory plugin, run:

ansible-doc -t inventory telekom_mms.icinga_director.icinga_director_inventory

Examples using the modules

See the examples directory for a complete list of examples.

- hosts: localhost
  collections:
    - telekom_mms.icinga_director
  tasks:
    - name: create a host in icinga
      telekom_mms.icinga_director.icinga_host:
        state: present
        url: "https://example.com"
        url_username: "{{ icinga_user }}"
        url_password: "{{ icinga_pass }}"
        object_name: "{{ ansible_hostname }}"
        address: "{{ ansible_default_ipv4.address }}"
        display_name: "{{ ansible_hostname }}"
        groups:
          - "foo"
        imports:
          - "StandardServer"
        vars:
          dnscheck: "no"

- name: Query a service apply rule in icinga
  telekom_mms.icinga_director.icinga_service_apply_info:
    url: "{{ icinga_url }}"
    url_username: "{{ icinga_user }}"
    url_password: "{{ icinga_pass }}"
    query: "SERVICE_dummy"
  register: result

Examples using the role

Please see the README of the role.

Examples using the inventory plugin

Create a file that ends with icinga_director_inventory.yaml, for example inventory.icinga_director_inventory.yaml.

The content should look like this:

plugin: telekom_mms.icinga_director.icinga_director_inventory
url: "https://example.com"
url_username: foo
url_password: bar
force_basic_auth: False

Then you can use the dynamic inventory like this:

ansible-playbook -i inventory.icinga_director_inventory.yaml path/to/your/playbook.yml

Example using module defaults groups

With ansible-core >= 2.12 it is possible to specify defaults parameters for all modules in this collection using Module defaults groups. Use it like this:

- hosts: localhost

  module_defaults:
    group/telekom_mms.icinga_director.icinga:
      url: "https://example.com"
      url_username: foo
      url_password: bar

  tasks:
    - name: Create host
      telekom_mms.icinga_director.icinga_host:
        object_name: myhost
        address: 172.0.0.1

    - name: Create command
      telekom_mms.icinga_director.icinga_command:
        object_name: my-command
        command: my-command.sh

Examples for defining multiple assign_filter conditions

The Icinga Director API expects multiple conditions for the assign_filter in a different format than what is rendered to the configuration files.

Example: An assign condition in the config looking like this:

assign where host.vars.something == "foo" || host.vars.something_else == "bar"

would have to look like this when using the module:

assign_filter: 'host.vars.something="foo"|host.vars.something_else="bar"'

Contributing

See Contributing.

Troubleshooting

If one of the following errors is thrown, your Icinga Director is probably sitting behind a basic authentication prompt. Use force_basic_auth: true in your tasks to fix the problem. If you are using this collections' ansible role, you have to use icinga_force_basic_auth: true to fix this problem.

fatal: [localhost]: FAILED! => {"changed": false, "msg": "bad return code while creating: -1. Error message: Request failed: <urlopen error Tunnel connection failed: 302 Found>"}

failed: [localhost] => {"ansible_loop_var": "item", "changed": false, "item": "localhost", "msg": "AbstractDigestAuthHandler does not support the following scheme: 'Negotiate'", "status": -1, "url": "https://icinga-director.example.com/director/host?name=foohost"}

Known Errors with different Director versions

Director 1.11.1

When creating notifications that contain the users-parameter, the task might not be idempotent (see).

Director 1.11.0

You cannot create usergroups because of invalid property assign_filter (see).

Director 1.10.0

Existing service apply rule objects cannot be modified (see):

TASK [Add service apply rule to icinga] ********************************************************************************************
fatal: [localhost]: FAILED! => {"changed": false, "msg": "exception when deleting: 'id'"}

Director 1.9.0

When creating service checks, the tasks fails (see):

failed: [icinga2-master1.localdomain] (item={'name': 'director-generic-service', 'enable_active_checks': True, 'enable_event_handler': True, 'enable_flapping': True, 'enable_notifications': True, 'eanble_passive_checks': True, 'enable_perfdata': True, 'use_agent': True, 'volatile': False}) => {"ansible_loop_var": "item", "changed": false, "item": {"eanble_passive_checks": true, "enable_active_checks": true, "enable_event_handler": true, "enable_flapping": true, "enable_notifications": true, "enable_perfdata": true, "name": "director-generic-service", "use_agent": true, "volatile": false}, "msg": "bad return code while creating: 422. Error message: Trying to recreate icinga_service (\"{\"object_name\":\"director-generic-service\"}\")"}

Extras

Use our code snippets template supported in Visual Studio Code

Please see the README for more information.

License

GPLv3

Author Information

Sebastian Gumprich
Lars Krahl
Michaela Mattes
Martin Schurz

telekom-mms / ansible-collection-icinga-director

readme