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_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

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