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: https://github.com/T-Systems-MMS/ansible-icinga-modules

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ā€?

Regards,
Sebastian

6 Likes

Hi.

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.)

2 Likes

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 Icinga2APIObject.py or icinga.pyā€ Where to copy the content of module_utils?

Cheers,
Rafael

The modules are distributed as collections (https://docs.ansible.com/ansible/latest/user_guide/collections_using.html).
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 https://github.com/T-Systems-MMS/ansible-icinga-modules
cd ansible-icinga-modules
ansible-galaxy collection build
ansible-galaxy collection install T_Systems_MMS-icinga-*

Then you can run the play:

- hosts: localhost
  collections:
    - T_Systems_MMS.icinga-director
  tasks:
    - name: create a host in icinga
      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"```
1 Like

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

https://galaxy.ansible.com/t_systems_mms/icinga_director

Now installing it is as easy as:

ansible-galaxy collection install t_systems_mms.icinga_director
1 Like

Hi.

I tested it now and its working great!
As i do not have access to galaxy.ansible.com 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 ā€œhttps://example.com/icingaweb2/directorā€ the url needs to be https://example.com/icingaweb2

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

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

to

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

inside icinga_host.py f.e.

So here is my working example:

-name: Icinga Host
  hosts: icingaagents
  collections:
    - t_systems_mms.icinga_director
  tasks:
    - name: Include Director Vars
      include_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
      icinga_host:
        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 }}"
        #groups:
        #  - "foo"
        imports:
          - "LINUX SERVER AGENT"
        vars:
          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
  collections:
  - t_systems_mms.icinga_director
  roles:
    - ansible_icinga
  vars:
    icinga_url: "https://example.com"
    icinga_user: "{{ icinga_user }}"
    icinga_pass: "{{ icinga_pass }}"
    icinga_timeperiods:
      - timeperiod_object:
        - "8x5"
        ranges:
          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"
        ranges:
          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"
    icinga_users:
      - user_object:
        - "service_abbreviation_email_24x7"
        pager: "SIP/xxx"
        email: "service_abbreviation@example.com"
      - user_object:
        - "service_abbreviation_8x5"
        email: "service_abbreviation@example.com"
    icinga_hostgroups:
      - hostgroup_object:
        - "service_abbreviation-environement"
        - "service_abbreviation-environement-web"
    icinga_hosts:
      - 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!

3 Likes

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

I thought Iā€™d give an update here, since itā€™s been almost two years!

Here are our changes, with the most interesting changes highlighted in bold:

  • Add Icinga Deploy handler and module (#205) @flkhndlr
  • Add icon support to service template (#179) @jensrudolf
  • Add flapping support to service template module (#180) @jensrudolf
  • Add action_group to enable module default groups (#175) @jensrudolf
  • Add icinga_serviceset module (#163) @HeikoNeblung
  • Added missing fields to ā€˜icinga_hostā€™ and ā€˜icinga_host_templateā€™ (#158) @HeikoNeblung
  • Add possibility to use Compose and keyed groups in inventory-module (#155) @rndmh3ro
  • add option to append arguments to all modules (#153) @rndmh3ro
  • Add Icinga scheduled downtime module (#146) @xFuture603
  • Add command_endpoint parameter to host and host_template (#143) @jensrudolf
  • Add support for retry_interval and max_check_attempts to host template (#140) @jensrudolf
  • Add event_command parameter to service apply playbook to enable usage (#133) @avalor1
  • Add event_command parameter to icinga_service_apply module (#132) @avalor1
    add ā€œvarsā€ variable to icinga_notification in the role (#129) @z-bsod