initial commit

Author: Lukas Burkhard

.gitignore

@@ -0,0 +1,2 @@
+docs/inventory/
+.fact_cache/

README.md

@@ -1,2 +1,31 @@
 # ansible-inventory-docs
-Example of how to use ansible facts to create an overwiew of managed hosts
+
+Example of how to use ansible facts to create an overwiew of managed hosts. 
+
+## How-To
+
+Ansible is capable of handling different inventories. The example here uses a default inventory as defined in `ansible.cfg` 
+using the yaml notation. In this example, `localhost` is assigned to the group *desktops* as an example.  
+Run the playbook and see what happens:
+
+	ansible-playbook inventory_docs.yml
+
+An overview `index.md` with a table of all hosts for the inventory is created as well as a `localhost.md` with all the 
+details that are available in the facts using a code block for every entry.
+
+Using another inventory is supported and will create another subfolder.
+
+	ansible-playbook -i inventories/other.yml inventory_docs.yml
+
+If you are new to ansible, there are a few techniques and features contained in this example:
+
+## Jinja Templates
+
+- usage of a macro to render a value from the facts
+- An example of how to access a nested value, e.g. `facts.date_time.tz` using a string notation `date_time.tz`.
+- Controlling indentation in template blocks using `-` in order to render table in markdown correctly
+- Intermediate variable definitions in templates using `{% set variable=.... %}`
+
+## Yaml-Syntax
+
+- Re-use of static expressions (`docs_folder: &folder "docs/inventory"`)

ansible.cfg

@@ -0,0 +1,16 @@
+[defaults]
+inventory=./inventories/hosts.example.yml
+log_path=logs/ansible.log
+gathering = smart
+fact_caching = jsonfile
+fact_caching_connection = .fact_cache/
+fact_caching_timeout = 86400
+remote_tmp     = .ansible/tmp
+local_tmp      = .ansible/tmp
+enable_task_debugger = False
+interpreter_python = auto_silent
+ansible_python_interpreter=/usr/bin/python3
+ansible_user = root
+
+;[ssh_connection]
+;pipelining = True

inventories/hosts.example.yml

@@ -0,0 +1,10 @@
+---
+all:
+  hosts:
+    localhost:
+      ansible_connection: local
+
+  children:
+    desktops:
+      hosts:
+        localhost:

inventory_docs.yml

@@ -0,0 +1,77 @@
+- hosts: all
+  gather_facts: true
+  vars:
+    docs_folder: &folder "docs/inventory"
+
+    inventory_fn: "{{ inventory_file | basename }}"
+    inventory_name: "{{ inventory_fn.split('.') | first }}"
+
+    inventory_docs: "{{ docs_folder }}/{{ inventory_name }}"
+  tasks:
+    - name: ensure directory for inventory {{ inventory_fn }}
+      file:
+        path: "{{ inventory_docs }}"
+        state: directory
+      delegate_to: 127.0.0.1
+
+    - name: render the details
+      template:
+        src: "host_detail.md.j2"
+        dest: "{{ fp }}"
+      delegate_to: 127.0.0.1
+      vars:
+        fp: "{{ inventory_docs }}/{{ inventory_hostname }}.md"
+
+- hosts: localhost
+  gather_facts: false
+  vars:
+    docs_folder: *folder
+
+    inventory_fn: "{{ inventory_file | basename }}"
+    inventory_name: "{{ inventory_fn.split('.') | first }}"
+    inventory_docs: "{{ docs_folder }}/{{ inventory_name }}"
+    outfile: "{{ inventory_docs }}/index.md"
+
+    filter_group: all
+    all_hosts: "{{ groups[filter_group] | default('all') }}"
+
+    table_fields: &used_fields
+      - system_vendor
+      - processor_cores
+      - memory_mb.swap.total
+      - memtotal_mb
+      - memfree_mb
+      - distribution
+      - architecture
+      - bios_date
+
+    # Modify the labels of supp
+    custom_labels:
+      memtotal_mb: RAM [mb]
+      distribution: Distro
+
+    # Add more to your liking, dotted notation is possible
+    labels:
+      architecture: ARCH
+      bios_date: BIOS DATE
+      bios_vendor: BIOS VENDOR
+      board_vendor: BOARD VENDOR
+      distribution: OS DISTRIBUTION
+      memfree_mb: RAM FREE
+      memory_mb.swap.total: SWAP
+      memtotal_mb: RAM
+      os_family: OS FAMILY
+      processor_cores: CPU CORES
+      processor_count: CPU COUNT
+      processor_vcpus: VCPUS
+      product_name: PRODUCT NAME
+      product_serial: PRODUCT SERIAL
+      product_version: PRODUCT VERSION
+      system: SYSTEM
+      system_vendor: VENDOR
+
+  tasks:
+    - name: render the overview to {{ outfile }}
+      template:
+        src: "ansible_host_overview.md.j2"
+        dest: "{{ outfile }}"

templates/ansible_host_overview.md.j2

@@ -0,0 +1,27 @@
+---
+{% macro get_val(facts, key) %}
+{%- if facts -%}
+{%- if not '.' in key -%}
+{{ facts[key] | default('n.a.') }} |
+{%- else -%}
+{% set attrs = key.split('.') %}
+{{ [attrs[0]] | map('extract', facts, attrs[1:]) | first }} |
+{%- endif -%}
+{%- else -%} - |{%- endif %}
+{% endmacro -%}
+
+# Ansible Host Overview
+
+**Inventory**: {{ inventory_fn }}
+
+{% set all_fields = ['NAME'] | union(table_fields) %}
+| {%- for field in all_fields %} {{ custom_labels[field] | default(labels[field] | default(field)) }} |
+{%- endfor %}
+
+|{% for field in all_fields %} {{ '-' * labels[field] | default(field) | length }} |{%- endfor %}
+
+{% for hostname in all_hosts %}
+{% set host_facts = hostvars[hostname]['ansible_facts'] %}
+| **{{ hostname }}** | {% for key in table_fields %} {{ get_val(host_facts, key) }}{% endfor %}
+
+{% endfor %}

templates/host_detail.md.j2

@@ -0,0 +1,12 @@
+---
+
+## Details for *{{ inventory_hostname }}*
+
+**Inventory Groups**: {{ group_names | join(', ') }}
+
+{% for section, value in ansible_facts.items() %}
+### {{ section.split('_') | map('capitalize') | join(' ') }}
+```
+{{ value | to_nice_json }}
+```
+{% endfor %}