undercloud-debug validation documentation improvement

Documentation of the validation was adjusted to reflect actual
mechanism of operation, with the goal of preventing confusion
on the side of the customer.

Related-Bug: #1942508

Signed-off-by: Jiri Podivin <jpodivin@redhat.com>
Change-Id: I79b07f1929e81cfd162f3e191287da254f88c3ae

doc/source/roles/role-undercloud_debug.rst

@@ -2,5 +2,53 @@
 undercloud_debug
 ================
 
+--------------
+About the role
+--------------
+
+An Ansible role to check if debug is enabled on Undercloud services.
+
+Requirements
+============
+
+This role needs to be run against an installed Undercloud.
+The tested services must use one of the specified configuration files
+to set their debug status.
+
+Role Variables
+==============
+
+- debug_check: <True>
+- services_conf_files: List of paths for configuration files of services
+  you want to check
+
+Dependencies
+============
+
+- 'validations_read_ini' custom plugin
+
+Example Playbook
+================
+
+.. code-block:: yaml
+
+  - hosts: undercloud
+    roles:
+      - { role: undercloud-debug }
+
+License
+=======
+
+Apache
+
+Author Information
+==================
+
+Red Hat TripleO Validations Team
+
+----------------
+Full Description
+----------------
+
 .. ansibleautoplugin::
    :role: roles/undercloud_debug

playbooks/undercloud-debug.yaml

@@ -8,6 +8,9 @@
         This will check if debug is enabled on undercloud services.
         If debug is enabled, the root filesystem can fill up quickly, and
         is not a good thing.
+        This role needs to be run against an installed Undercloud.
+        The tested services must use one of the specified configuration files
+        to set their debug status.
       groups:
         - pre-deployment
       categories:

roles/undercloud_debug/README.md

@@ -1,38 +0,0 @@
-Undercloud-debug
-================
-
-An Ansible role to check if debug is enabled on Undercloud services.
-
-Requirements
-------------
-
-This role needs to be run against an installed Undercloud.
-
-Role Variables
---------------
-
-- debug_check: <True>
-- services_conf_files: List of path for each services configuration files you
-  want to check
-
-Dependencies
-------------
-
-- 'validations_read_ini' custom plugin
-
-Example Playbook
-----------------
-
-    - hosts: undercloud
-      roles:
-         - { role: undercloud-debug }
-
-License
--------
-
-Apache
-
-Author Information
-------------------
-
-Red Hat TripleO Validations Team

roles/undercloud_debug/defaults/main.yml

@@ -1,6 +1,8 @@
 ---
-
+# Fail if the 'debug' key is set to value of 'debug_check'
 debug_check: true
+
+# Parse following ini files, retrieving value of the 'debug' key
 services_conf_files:
   - /var/lib/config-data/puppet-generated/nova/etc/nova/nova.conf
   - /var/lib/config-data/puppet-generated/neutron/etc/neutron/neutron.conf

roles/undercloud_debug/vars/main.yaml

@@ -6,5 +6,8 @@ metadata:
     This will check if debug is enabled on undercloud services.
     If debug is enabled, the root filesystem can fill up quickly, and
     is not a good thing.
+    This role needs to be run against an installed Undercloud.
+    The tested services must use one of the specified configuration files
+    to set their debug status.
   groups:
     - pre-deployment