#231 adding example playbooks explaining implicit deletion

docs/example_playbooks.rst

@@ -0,0 +1,58 @@
+Icinga Director Ansible Playbooks
+================================
+
+Introduction
+------------
+
+This document provides an illustrative guide to managing services in Icinga Director using sample Ansible playbooks in the example directory which leverage the `telekom_mms.icinga_director` Ansible collection.
+These playbooks described here are intended as examples, designed to demonstrate potential use cases and provide a basis for custom playbook development.
+It's important to note that these examples are not meant to be deployed without modifications and made to fit a specific environment, so your requirements may differ.
+These playbooks include management for the lifecycle of icinga object, including creation, update and delete, to make the Ansible configuration the SPoT.
+
+Due to the behaviour of Ansible and the Icinga Director API, there are some workarounds chosen in these playbooks, especially to enable implicit deletion of objects.
+
+
+
+How to Use
+----------
+
+
+The playbook includes three tasks and a role that is executed thereafter:
+
+1. **Include Vars**: This task includes variables from the `vars/icinga_{object}.yml` file. Object is the general Term for different Icinga Director objects like services, hosts, etc.
+
+2. **Get All Object Configs**: This task retrieves all object configurations from the Icinga Director. The `url`, `url_username`, and `url_password` variables are used to authenticate with the Icinga Director. The `query` variable is set to `"*"` to retrieve all object configurations. The result is registered in the `result` variable.
+
+3. **Create Objects Scheduled for Deletion**: This task creates objects that are scheduled for deletion. The `icinga_{object}` variable is updated with the Objects in the Icinga Director
+      that are not currently in the `icinga_{object}` list.
+      This means that any object that exists in the Director, but is not defined in the playbook will be marked for deletion.
+      This done by creating objects with an `'absent'` state to remove them and define in the configuration as the SPoT.
+
+In addition to these tasks, the playbook uses the `ansible_icinga` role.
+
+Variables
+---------
+
+The playbook uses the following variables:
+
+- `icinga_host`: The URL of the Icinga Director.
+- `icinga_user`: The username used for authentication with the Icinga Director.
+- `icinga_pass`: The password used for authentication with the Icinga Director.
+- `icinga_{object}`: A list of objects different by type managed by the playbook. This variable should be defined in the `vars/icinga_service.yml` file.
+- `icinga_delete`: This variable controls whether objects not defined in the vars should be deleted from the Icinga Director. Currently it is set to `false` by default.
+
+Make sure to define these variables before running the playbook.
+
+Running the Playbook
+--------------------
+
+To run the playbook, use the `ansible-playbook` command.:
+
+.. code-block:: bash
+
+   ansible-playbook  icinga_{object}.yml
+
+To run all playbooks at once there is a meta playbook to. 
+This playbook will execute all example playbooks sequentially and execution is controlled by the tags, too.
+Additionally, it is possible to customize the example playbook runs if needed.
+This is achieved by adjusting the tags. By setting the `icinga_delete` tag you can enable or disable the deletion of objects.

examples/playbooks/icinga_commands.yml

@@ -0,0 +1,51 @@
+---
+- hosts: localhost
+  gather_facts: false
+  collections:
+    - telekom_mms.icinga_director
+  vars:
+    icinga_deploy_config: true
+    icinga_deploy_timeout: 5
+    icinga_delete: false
+  pre_tasks:
+    - name: include Vars
+      ansible.builtin.include_vars:
+        file: vars/icinga_commands.yml
+        name: included_icinga_commands
+
+    - name: get all object configs
+      telekom_mms.icinga_director.icinga_command_info:
+        url: "{{ icinga_host }}"
+        url_username: "{{ icinga_user }}"
+        url_password: "{{ icinga_pass }}"
+        query: "*"
+        force_basic_auth: true
+      register: result
+
+    - name: create empty object to fill it with delete objects
+      ansible.builtin.set_fact:
+        delete_icinga_commands: []
+
+    - name: create objects scheduled for deletion
+      ansible.builtin.set_fact:
+        delete_icinga_commands: "{{ delete_icinga_commands + [{'name': item.object_name, 'state': 'absent' }] }}"
+      when: not included_icinga_commands.icinga_commands | selectattr('name', 'contains', item.object_name)
+      loop: "{{ result.objects | list }}"
+
+    - name: set deletion objects as used objects
+      ansible.builtin.set_fact:
+        icinga_commands: "{{ delete_icinga_commands }}"
+      when: icinga_delete
+
+    - name: set included objects as used objects
+      ansible.builtin.set_fact:
+        icinga_commands: "{{ included_icinga_commands.icinga_commands }}"
+      when: not icinga_delete
+
+  roles:
+    - role: ansible_icinga
+
+  post_tasks:
+    - name: remove vars
+      ansible.builtin.set_fact:
+        icinga_commands: []

examples/playbooks/icinga_config.yml

@@ -0,0 +1,135 @@
+---
+# manages Icinga2 Monitoring Configuration via Icinga2 Director API as a meta playbook
+########################################################################
+
+# object deletion
+- name: import icinga_service_apply playbook
+  import_playbook: icinga_service_apply.yml
+  vars:
+    icinga_delete: true
+  tags:
+    - icinga_service_apply
+    - icinga_delete
+
+- name: import icinga_service playbook
+  import_playbook: icinga_service.yml
+  vars:
+    icinga_delete: true
+  tags:
+    - icinga_service
+    - icinga_delete
+
+- name: import icinga_service_templates playbook
+  import_playbook: icinga_service_templates.yml
+  vars:
+    icinga_delete: true
+  tags:
+    - icinga_service_templates
+    - icinga_delete
+
+- name: import icinga_commands playbook
+  ansible.builtin.import_playbook: icinga_commands.yml
+  vars:
+    icinga_delete: true
+  tags:
+    - icinga_commands
+    - icinga_delete
+
+- name: import icinga_hostgroups playbook
+  ansible.builtin.import_playbook: icinga_hostgroups.yml
+  vars:
+    icinga_delete: true
+  tags:
+    - icinga_hostgroups
+    - icinga_delete
+
+- name: import icinga_hosts playbook
+  ansible.builtin.import_playbook: icinga_hosts.yml
+  vars:
+    icinga_delete: true
+  tags:
+    - icinga_hosts
+    - icinga_delete
+
+- name: import icinga_host_templates playbook
+  ansible.builtin.import_playbook: icinga_host_templates.yml
+  vars:
+    icinga_delete: true
+  tags:
+    - icinga_host_templates
+    - icinga_delete
+
+- name: import icinga_timeperiods playbook
+  import_playbook: icinga_timeperiods.yml
+  vars:
+    icinga_delete: true
+  tags:
+    - icinga_timeperiods
+    - icinga_delete
+
+- name: import icinga_user playbook
+  import_playbook: icinga_user.yml
+  vars:
+    icinga_delete: true
+  tags:
+    - icinga_user
+    - icinga_delete
+
+- name: import icinga_notifications playbook
+  import_playbook: icinga_notifications.yml
+  vars:
+    icinga_delete: true
+  tags:
+    - icinga_notifications
+    - icinga_delete
+
+# object modification and creation
+- name: import icinga_host_templates playbook
+  ansible.builtin.import_playbook: icinga_host_templates.yml
+  tags:
+    - icinga_host_templates
+
+- name: import icinga_hosts playbook
+  ansible.builtin.import_playbook: icinga_hosts.yml
+  tags:
+    - icinga_hosts
+
+- name: import icinga_hostgroups playbook
+  ansible.builtin.import_playbook: icinga_hostgroups.yml
+  tags:
+    - icinga_hostgroups
+
+- name: import icinga_commands playbook
+  ansible.builtin.import_playbook: icinga_commands.yml
+  tags:
+    - icinga_commands
+
+- name: import icinga_service_templates playbook
+  ansible.builtin.import_playbook: icinga_service_templates.yml
+  tags:
+    - icinga_service_templates
+
+- name: import icinga_service playbook
+  ansible.builtin.import_playbook: icinga_service.yml
+  tags:
+    - icinga_service
+
+- name: import icinga_service_apply playbook
+  ansible.builtin.import_playbook: icinga_service_apply.yml
+  tags:
+    - icinga_service_apply
+
+- name: import icinga_timeperiods playbook
+  ansible.builtin.import_playbook: icinga_timeperiods.yml
+  tags:
+    - icinga_timeperiods
+
+- name: import icinga_user playbook
+  import_playbook: icinga_user.yml
+  tags:
+    - icinga_user
+
+- name: import icinga_notifications playbook
+  import_playbook: icinga_notifications.yml
+  tags:
+    - icinga_notifications

examples/playbooks/icinga_endpoints.yml

@@ -0,0 +1,51 @@
+---
+- hosts: localhost
+  gather_facts: false
+  collections:
+    - telekom_mms.icinga_director
+  vars:
+    icinga_deploy_config: true
+    icinga_deploy_timeout: 5
+    icinga_delete: false
+  pre_tasks:
+    - name: include Vars
+      ansible.builtin.include_vars:
+        file: vars/icinga_endpoints.yml
+        name: included_icinga_endpoints
+
+    - name: get all object configs
+      telekom_mms.icinga_director.icinga_endpoint_info:
+        url: "{{ icinga_host }}"
+        url_username: "{{ icinga_user }}"
+        url_password: "{{ icinga_pass }}"
+        query: "*"
+        force_basic_auth: true
+      register: result
+
+    - name: create empty object to fill it with delete objects
+      ansible.builtin.set_fact:
+        delete_icinga_endpoints: []
+
+    - name: create objects scheduled for deletion
+      ansible.builtin.set_fact:
+        delete_icinga_endpoints: "{{ delete_icinga_endpoints + [{'name': item.object_name, 'state': 'absent' }] }}"
+      when: not included_icinga_endpoints.icinga_endpoints | selectattr('name', 'contains', item.object_name)
+      loop: "{{ result.objects | list }}"
+
+    - name: set deletion objects as used objects
+      ansible.builtin.set_fact:
+        icinga_endpoints: "{{ delete_icinga_endpoints }}"
+      when: icinga_delete
+
+    - name: set included objects as used objects
+      ansible.builtin.set_fact:
+        icinga_endpoints: "{{ included_icinga_endpoints.icinga_endpoints }}"
+      when: not icinga_delete
+
+  roles:
+    - role: ansible_icinga
+
+  post_tasks:
+    - name: remove vars
+      ansible.builtin.set_fact:
+        icinga_zones: []

examples/playbooks/icinga_host_templates.yml

@@ -0,0 +1,52 @@
+---
+- hosts: localhost
+  gather_facts: false
+  collections:
+    - telekom_mms.icinga_director
+  vars:
+    icinga_force_basic_auth: true
+    icinga_deploy_config: true
+    icinga_deploy_timeout: 5
+    icinga_delete: false
+  pre_tasks:
+    - name: include Vars
+      ansible.builtin.include_vars:
+        file: vars/icinga_host_templates.yml
+        name: included_icinga_host_templates
+
+    - name: get all object configs
+      telekom_mms.icinga_director.icinga_host_template_info:
+        url: "{{ icinga_host }}"
+        url_username: "{{ icinga_user }}"
+        url_password: "{{ icinga_pass }}"
+        query: "*"
+        force_basic_auth: true
+      register: result
+
+    - name: create empty object to fill it with delete objects
+      ansible.builtin.set_fact:
+        delete_icinga_host_templates: []
+
+    - name: create objects scheduled for deletion
+      ansible.builtin.set_fact:
+        delete_icinga_host_templates: "{{ delete_icinga_host_templates + [{'name': item.object_name, 'state': 'absent' }] }}"
+      when: not included_icinga_host_templates.icinga_host_templates | selectattr('name', 'contains', item.object_name)
+      loop: "{{ result.objects }}"
+
+    - name: set deletion objects as used objects
+      ansible.builtin.set_fact:
+        icinga_host_templates: "{{ delete_icinga_host_templates }}"
+      when: icinga_delete
+
+    - name: set included objects as used objects
+      ansible.builtin.set_fact:
+        icinga_host_templates: "{{ included_icinga_host_templates.icinga_host_templates }}"
+      when: not icinga_delete
+
+  roles:
+    - ansible_icinga
+
+  post_tasks:
+    - name: remove vars
+      ansible.builtin.set_fact:
+        icinga_host_templates: []