Ansible modules for Icinga Director

Hi everyone,

at our company we extensively use Icinga 2 and Ansible.

We configure commands, hosts, users, templates and practically all other objects trough the director with the help of an Ansible-role.
This proved cumbersome and hard to manage, so we developed some native Ansible-modules.

You can find them here:

This is an early release with missing features and probably some bugs. But I wanted to get them out quickly to gather feedback.

One question I’d like direct feedback on: what about the name? It’s “ansible-icinga-modules” for now, however it utilizes the director-api, so should we rename it to “ansible-icinga-director-modules”?




I would change the name to clarify that it uses the director, because there are many other roles and playbooks out there already and they mostly use the icinga Api to add hosts. I will give it a try, as i just started to install Icinga2 agent with ansible and i want to add the new agent into the director.

1 Like

Thanks for your answer!

I’ll rename it to (probably) “icinga-director”.

The repo will the be called “ansible-collection-icinga-director”, the collection “T_Systems_MMS.icinga-director”.

1 Like

Very nice. It definitely has some potential.

I see you have written the logic for the api calls to icinga by yourself.
This module covers it pretty well:

Have been using it for couple of month with zero issues. Have only used it up to Icinga 2.10.5 though.

1 Like

@Mili_D, I briefly took a look at this library and it seemed good. However we only alter objects through the director, not trough the icinga-api. As far as I can see, this library does not support the director.

The director does nothing else than use the icinga-API with a certain user defined in the api-conf.

Is there an advantage in going through the director-api with ansible?

I did not know this, thanks!

No, it should not matter. I’m not quite fluent with the icinga-api. Does it support auditing and rollbacks like the director does? Does it support multiple masters?

Changes through the api are also being audited. I´m not sure though how to rollback throught the api. I always use the Icingaweb-Interface for that.

I´m also by far no expert for icinga and you should definitely get another opionion on this. Maybe I´m understanding it wrong. :slight_smile:

The advantage of using the director Api is, that the host is actually shown in the director. Adding it with icinga-api you will not be able to edit the host inside the director (As far as i know the icinga2 api is not aware of the Director). The Director is so powerfull, that i always use it, because you get a lot of good features with him. (service sets, import sources, gui with selectabel lists/dropdowns, etc.)


How to install the module?

I’am rather new to ansible/python and copied the plugins/module content to /usr/share/ansible/plugins/modules. But i get the Erromessage “Could not find imported module support code for icinga_host. Looked either for or” Where to copy the content of module_utils?


The modules are distributed as collections (
The installation is not quite forward, yet, since I could not publish the collection to Ansible Galaxy yet.

First, you have to install the icinga-collection. As it isn’t on Galaxy yet, you cannot do:

ansible-galaxy collection install T_Systems_MMS.icinga

Instead you have to clone, build and then install the collection:

git clone
cd ansible-icinga-modules
ansible-galaxy collection build
ansible-galaxy collection install T_Systems_MMS-icinga-*

Then you can run the play:

- hosts: localhost
    - T_Systems_MMS.icinga-director
    - name: create a host in icinga
        state: present
        url: ""
        url_username: "{{ icinga_user }}"
        url_password: "{{ icinga_pass }}"
        object_name: "{{ ansible_hostname }}"
        address: "{{ ansible_default_ipv4.address }}"
        display_name: "{{ ansible_hostname }}"
          - "foo"
          - "StandardServer"
          dnscheck: "no"```
1 Like

So we finally managed to bring the collection into Ansible Galaxy!

Now installing it is as easy as:

ansible-galaxy collection install t_systems_mms.icinga_director
1 Like


I tested it now and its working great!
As i do not have access to from the host, i used the manual way you explained before. I needed some time to find out how to get it up and running.

Here are my findings:

If your director is installed in “” the url needs to be

If you use a proxy by default you need to add “proxy: no” if its a local website (at least on our installation, otherwise I’am getting this error: "bad return code while creating: "

After renaming the collection the import command needs to be updated:


from ansible_collections.T_Systems_MMS.icinga.plugins.module_utils.icinga import Icinga2APIObject


from ansible_collections.t_systems_mms.icinga_director.plugins.module_utils.icinga import Icinga2APIObject

inside f.e.

So here is my working example:

-name: Icinga Host
  hosts: icingaagents
    - t_systems_mms.icinga_director
    - name: Include Director Vars
        file: vars/main.yaml

    - name: Create a Host in Icinga
      #no ideas if i need local connection here, but other remote hosts can't reach the director url.
      connection: local
        state: present
        use_proxy: no
        #validate_certs: no
        url: "{{ director_url }}"
        url_username: "{{ director_user }}"
        url_password: "{{ director_pass }}"
        object_name: "{{ ansible_hostname }}"
        address: "{{ ansible_default_ipv4.address }}"
        display_name: "{{ ansible_hostname }}"
        #  - "foo"
          - "LINUX SERVER AGENT"
          os: "{{ ansible_distribution }}"

Glad to hear it!

I’ll add something along these lines to the docs, thanks!

Yeah, I forgot to rename it when renaming the repository… It’s fixed now.

1 Like

We worked hard on the collection and just released version 1.3.1.

We fixed and updated many things: simplified the code, improved the error messages and automated the release to ansible galaxy.

However we have two user-facing changes that are more interesting:

  • we added a module to add host templates via the director
  • we added an (opinonated) Ansible role that utilizes the new modules! Here’s an example straight from the docs:
- hosts: localhost
  gather_facts: false
  - t_systems_mms.icinga_director
    - ansible_icinga
    icinga_url: ""
    icinga_user: "{{ icinga_user }}"
    icinga_pass: "{{ icinga_pass }}"
      - timeperiod_object:
        - "8x5"
          monday: "09:00-17:00"
          tuesday: "09:00-17:00"
          wednesday: "09:00-17:00"
          thursday: "09:00-17:00"
          friday: "09:00-17:00"
      - timeperiod_object:
        - "24x7"
          monday: "00:00-24:00"
          tuesday: "00:00-24:00"
          wednesday: "00:00-24:00"
          thursday: "00:00-24:00"
          friday: "00:00-24:00"
          saturday: "00:00-24:00"
          sunday: "00:00-24:00"
      - user_object:
        - "service_abbreviation_email_24x7"
        pager: "SIP/xxx"
        email: ""
      - user_object:
        - "service_abbreviation_8x5"
        email: ""
      - hostgroup_object:
        - "service_abbreviation-environement"
        - "service_abbreviation-environement-web"
      - host_object:
        - "service_abbreviation-environement-web01"

With this role we try to make it easy to create objects in icinga by creating all required tasks that you only have to fill with variables.

Let me know what you think!


We’re working hard on the collection and I wanted to give you an excerpt on what we did the last couple of months. The bold features are (to me) the most interesting ones!

  • add Usergroups modules #114 (rndmh3ro)
  • add new options to notification and notification template #110 (rndmh3ro)
  • Add event commands to modules that support this feature #101 (xFuture603)
  • add info modules for Director objects #98 (schurzi)
  • Add check_interval parameter to host_template #95 (mmslkr)
  • Add execution parms #67 (AnBenn)
  • add vars option to icinga_notification #68 (rndmh3ro)
  • Notification templates #64 (rndmh3ro)
  • added vsc code snippets #57 (xFuture603)
  • Add support for notes and notes_url to all relevant objects #56 (mmslkr)
  • add check_command arg to service_apply module #53 (rndmh3ro)
  • add new service module #32 (rndmh3ro)
  • Add Support for Zones and Endpoints #48 (arbu)
  • add timeout parameter to icinga_command.yml #43 (AnBenn)
  • add support for address6 on host object #37 (schurzi)
1 Like