Icinga Director Collection for Ansible

This Ansible collection contains:

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

2. A role to change objects in Icinga 2 using the the provided modules.

3. An inventory plugin to use hosts and groups defined in Icinga as a dynamic inventory.

Required Ansible version: 2.9.10

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

To see the documentation for the inventory plugin, run:

ansible-doc -t inventory t_systems_mms.icinga_director.icinga_director_inventory

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

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.

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: t_systems_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

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