Icinga Director Collection for Ansible

This collection contains Ansible modules and a role to change objects in Icinga 2 using the director API.

Required Ansible version: 2.9.10

Currently supported modules:

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_timeperiod
icinga_timeperiod_template
icinga_user_group
icinga_user_template
icinga_user
icinga_zone

Additionally all supported modules have an appropriate *_info-module to gather facts about the existing objects in the director.

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 t_systems_mms.icinga_director

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

---
collections:
- t_systems_mms.icinga_director

Documentation

Our modules include documentation. To display it 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 t_systems_mms.icinga_director.icinga_host

You can also find the complete documentation for the modules on the Ansible documentation:

https://docs.ansible.com/ansible/latest/collections/t_systems_mms/icinga_director/index.html#plugins-in-t-systems-mms-icinga-director

Examples using the modules

See the examples directory for a complete list of examples.

- hosts: localhost
  collections:
    - t_systems_mms.icinga_director
  tasks:
    - name: create a host in icinga
      t_systems_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
  t_systems_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.

Troubleshooting

If the following error is thrown, check if you're behind a proxy and use force_basic_auth: true in the task.

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

Local Development and testing

Linting with tox

> tox -elinters

Updating the tests and examples

If you add new features or arguments to the existing modules, please add them to the examples in the module itself. The integration tests and examples in our documentation are then generated from the module-examples.

To trigger this generation, you need to run the script hacking/update_examples_and_tests.sh from the root of the repository. For this you need to have yq in version 3 installed (see https://mikefarah.gitbook.io/yq/v/v3.x/).

Integration tests with docker

# run icinga in a container and forward port 80
> docker run -d -p 80:80 schurzi/icinga2

# run ansible-test
> ansible-test integration

# alternatively run the test playbooks against the container
> ansible-playbook tests/integration/targets/icinga/normalmode.yml
> ansible-playbook tests/integration/targets/icinga/checkmode.yml

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

sgruber94/ansible-collection-icinga-director