Merge branch 'develop'Enea_Edge_2.6.0

Change-Id: I5b91b0eebe7cdf49944af93f47f1e304dcffba45

1 files changed, 229 insertions, 106 deletions

diff --git a/doc/book-enea-edge-automation-user-guide/doc/automation_framework_test_harness.xml b/doc/book-enea-edge-automation-user-guide/doc/automation_framework_test_harness.xml
index cec8dcf..6dac5b8 100644
--- a/doc/book-enea-edge-automation-user-guide/doc/automation_framework_test_harness.xml
+++ b/doc/book-enea-edge-automation-user-guide/doc/automation_framework_test_harness.xml
@@ -150,6 +150,12 @@
           <para><literal>VNF_images</literal> - contains the VNF images that
           are used in test scenarios.</para>
         </listitem>
+
+        <listitem>
+          <para><literal>utils</literal> - contains configurable solutions for
+          different features. For example, the solution for automated
+          deployment reporting can be found under this directory.</para>
+        </listitem>
       </itemizedlist>
     </section>
 
@@ -234,14 +240,11 @@
       <emphasis role="bold">Example</emphasis>: for a more extended output,
       change the output from selective to debug.</para>
 
-      <para>The <literal>test_harness</literal> directory contains all the
-      implemented playbooks. This directory is structured in multiple
-      subdirectories, each subdirectory represents a functionality of the Enea
-      Edge Management application. Each implemented playbook from this
-      directory runs a method from a Python class from the
-      <literal>automation_framework</literal> directory. Each playbook is an
-      atomic operation, a basic operation that need to be tested. These
-      playbooks are used in complex test scenarios.</para>
+      <para>The <literal>test_harness</literal> directory contains the custom
+      Ansible modules, located in the modules directory, and the playbooks
+      mapping functionalities from the Enea Edge Management application. The
+      playbooks are atomic operations that can be used in complex test
+      scenarios.</para>
     </section>
 
     <section id="log_dir">
@@ -673,18 +676,6 @@ Check 'test' directory for JSON configuration files</programlisting>
               </listitem>
 
               <listitem>
-                <para><filename>vnfmgmt_ipv6_br.json</filename> - contains
-                <literal>VNF Management OVS bridge, IPv6</literal>:</para>
-
-                <programlisting>
-{
-    "name": "vnfmgmt_ipv6_br",
-    "type": "vnfMgmt",
-    "vnfMgmtAddress": "2001:db8:0:0:0:0:0:0"
-}</programlisting>
-              </listitem>
-
-              <listitem>
                 <para><filename>lan_br.json</filename> - contains
                 <literal>Dataplane OVS bridge</literal>; Type:
                 <literal>communication</literal>; Interface:
@@ -1305,41 +1296,81 @@ Parameters(not needed): --
     <literal>&lt;Automation-installerdir&gt;/test_harness</literal>
     directory.</para>
 
+    <para>The Ansible based Test Harness represents an example of structuring
+    the files needed for creating automated test cases using the Enea Edge
+    Automation, and provides a way to implement them.</para>
+
+    <para>The <filename>ansible.cfg</filename> file contains an example of the
+    Ansible default configuration. The default value for
+    <literal>stdout_callback</literal> is set to <literal>selective</literal>,
+    to print only certain tasks. It is recommended to switch to
+    <literal>debug</literal> when a test fails. By setting the parameter
+    <literal>any_errors_fatal</literal> to <literal>True</literal>, task
+    failures are considered fatal errors and the play execution stops.</para>
+
+    <para>All the Playbooks that execute Automation Framework Python modules
+    run on <literal>localhost</literal>. New entries have to be created for
+    direct communication over SSH with the boards.</para>
+
+    <para>The <filename>setup_env.sh</filename> script sets up the
+    <literal>testHarness</literal> test environment by creating the
+    <literal>testHarness-venv</literal> Python virtual environment, executing
+    requests needed by Automation Framework Python modules, and installing
+    Ansible. The Ansible package version is 2.9.6.</para>
+
+    <section id="ansible_mods">
+      <title>Ansible modules</title>
+
+      <para>The custom Ansible modules can be found in the
+      <literal>test_harness/modules/</literal> directory. The Ansible modules
+      are wrappers of Python Handlers from the
+      <literal>automation_framework/</literal> directory. Each Ansible module
+      has been designed to instantiate a Python handler and to run a method of
+      it with specific parameters.</para>
+
+      <para>The Ansible modules are used in Ansible playbooks as:</para>
+
+      <programlisting>&lt;name_of_the_module&gt;:
+  method: &lt;which method will be called&gt;
+  &lt;param1&gt;: &lt;value_of_param1&gt;
+  &lt;param2&gt;: &lt;value_of_param2&gt;
+  ...
+  &lt;paramx&gt;: &lt;value_of_paramx&gt;
+  chdir: &lt;the path where the Ansible playbook will be run&gt;</programlisting>
+
+      <para>The method is a mandatory argument for all Ansible modules, the
+      other arguments are optional. The method must exist in the
+      <literal>&lt;name_of_the_module&gt;</literal> Ansible module. The params
+      list (param1, param2... paramx) must have the same name as the
+      parameters of the method, otherwise an error will occur.</para>
+
+      <para>For example, for adding a uCPE Device into the Enea Edge
+      Management application from an Ansible playbook, the
+      <filename>uCPEDeviceModule</filename> should be used as:</para>
+
+      <programlisting>uCPEDeviceModule:
+  method: addDevice
+  device_name: &lt;name_of_the device&gt;
+  chdir: "{{ lookup('env','BASE_DIR') }}"</programlisting>
+
+      <para>This will call the <literal>addDevice</literal> method from the
+      <literal>uCPEDevice</literal> class that instantiates a
+      <literal>uCPEDeviceHandler</literal> object for the
+      <literal>device_name</literal> uCPE Device. Afterwards, the
+      <literal>addDevice</literal> method is called.</para>
+
+      <para>The list of possible parameters for all methods of an Ansible
+      module is saved in the <filename>module_args</filename> dictionary in
+      the Python script. The default value of all parameters is
+      <literal>None</literal>.</para>
+    </section>
+
     <section id="indiv_ansible_playbooks">
       <title>Individual Ansible Playbooks</title>
 
-      <para>The Ansible based Test Harness represents an example of
-      structuring the files needed for creating automated test cases using the
-      Enea Edge Automation, and provides a way to implement them.</para>
-
-      <para>The <filename>ansible.cfg</filename> file contains an example of
-      the Ansible default configuration. The default value for
-      <literal>stdout_callback</literal> is set to
-      <literal>selective</literal>, to print only certain tasks. It is
-      recommended to switch to <literal>debug</literal> when a test fails. By
-      setting the parameter <literal>any_errors_fatal</literal> to
-      <literal>True</literal>, task failures are considered fatal errors and
-      the play execution stops.</para>
-
-      <para>All the Playbooks that execute Automation Framework Python modules
-      run on <literal>localhost</literal>. New entries have to be created for
-      direct communication over SSH with the boards.</para>
-
-      <para>The <filename>setup_env.sh</filename> script sets up the
-      <literal>testHarness</literal> test environment by creating the
-      <literal>testHarness-venv</literal> Python virtual environment,
-      executing requests needed by Automation Framework Python modules, and
-      installing Ansible. The Ansible package version is 2.9.6.</para>
-
       <para>The <literal>test_harness</literal> directory contains all the
-      implemented Ansible Playbooks. This directory contains the
-      <filename>check_error.yml</filename> Playbook and many subdirectories,
-      each subdirectory representing an Enea Edge Management module.</para>
-
-      <para>The <filename>check_errors.yml</filename> Playbook checks the
-      Python output and returns success or fail results. This file is imported
-      in all playbooks from the <literal>test_harness</literal> directory and
-      it cannot be run standalone.</para>
+      implemented Ansible Playbooks and many subdirectories, each subdirectory
+      representing an Enea Edge Management module.</para>
 
       <para>According to their functionality, the Ansible Playbooks that refer
       to offline configuration are in the <literal>OfflineConfig</literal>
@@ -1366,61 +1397,46 @@ Parameters(not needed): --
 
       <para><emphasis role="bold">Example</emphasis>:</para>
 
-      <orderedlist>
-        <listitem>
-          <para>Display the help menu for
-          <filename>addDataPlaneOvsBridge.yml</filename>:</para>
-
-          <programlisting>ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml
-
-This playbook runs 'addDataPlaneOvsBridge' method from uCPEDeviceHandler module
-
-    The Python module will be run as:
-
-    Usage: uCPEDeviceHandler.py [OPTIONS] [PARAMETERS]...
-
-    Options:
-      -v, --verbose           Get info about the methods and parameters
-      -d, --device_name TEXT  The uCPE Device name
-      -m, --method TEXT       The atomic operation you want to run
-      -f, --config_file TEXT  The config file for NIC or bridges (optional
-                              argument)
-
-      -o, --display_output    Display output of the method
-      --help                  Show this message and exit.
-
-Usage:
-    ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml -e 
-    "device=&lt;device_name&gt; bridge_config_file=&lt;bridge_config_file&gt;"
-    ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml -e 
-    "device=&lt;device_name&gt; bridge_name=&lt;bridge_name&gt; bridge_type=integration"
-    ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml -e 
-    "device=&lt;device_name&gt; bridge_name=&lt;bridge_name&gt; bridge_type=communication"
-    ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml -e 
-    "device=&lt;device_name&gt; bridge_name=&lt;bridge_name&gt; bridge_type=communication 
-    interfaces=&lt;interfaces&gt;"</programlisting>
-        </listitem>
-
-        <listitem>
-          <para>Run the <filename>addDataPlaneOvsBridge.yml</filename>
-          playbook:</para>
-
-          <programlisting>ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml -e 
-"device=inteld1521-17 bridge_config_file=sfc_br.json"
-ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml -e 
-"device=inteld1521-17 bridge_config_file=lan_br.json"
-ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml -e 
-"device=inteld1521-17 bridge_name=sfc_br bridge_type=integration"
-ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml -e 
-"device=inteld1521-17 bridge_name=wap_br bridge_type=communication"
-ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml -e 
-"device=inteld1521-17 bridge_name=lan_br bridge_type=communication 
-interfaces=eno4"
-ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml -e 
-"device=inteld1521-17 bridge_name=lan_br bridge_type=communication 
-interfaces=eno4,eno5"</programlisting>
-        </listitem>
-      </orderedlist>
+      <para>Display the help menu for
+      <filename>addDataPlaneOvsBridge.yml</filename>:</para>
+
+      <programlisting>ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml
+.
+# fail *************************************************************
+  * localhost                  - FAILED!!! -------------------------
+    The 'device' and 'bridge_config_file' or 'bridge_name' and \
+'bridge_type' parameters are mandatory
+    Usage:
+      ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml \
+-e "device=&lt;device_name&gt; bridge_config_file=&lt;bridge_config_file&gt;"
+      ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml \
+-e "device=&lt;device_name&gt; bridge_name=&lt;bridge_name&gt; bridge_type=integration"
+      ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml \
+-e "device=&lt;device_name&gt; bridge_name=&lt;bridge_name&gt; bridge_type=communication"
+      ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml \
+-e "device=&lt;device_name&gt; bridge_name=&lt;bridge_name&gt; \
+bridge_type=communication interfaces=&lt;interfaces&gt;"
+
+    Example of usage:
+      ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml \
+-e "device=inteld1521-17 bridge_config_file=sfc_br.json"
+      ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml \
+-e "device=inteld1521-17 bridge_config_file=lan_br.json"
+      ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml \
+-e "device=inteld1521-17 bridge_name=sfc_br bridge_type=integration"
+      ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml \
+-e "device=inteld1521-17 bridge_name=wap_br bridge_type=communication"
+      ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml \
+-e "device=inteld1521-17 bridge_name=lan_br \
+bridge_type=communication interfaces=eno4"
+      ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml \
+-e "device=inteld1521-17 bridge_name=lan_br \
+bridge_type=communication interfaces=eno4,eno5"
+
+
+# STATS ************************************************************
+localhost    : ok=1     changed=0       failed=1        unreachable=0   \
+rescued=0       ignored=0</programlisting>
 
       <para>Each Ansible Playbook from the <literal>test_harness</literal>
       directory represents an atomic operation, a basic functionality that is
@@ -1599,4 +1615,111 @@ vnfi_name: "fortigateFWInstance"</programlisting>
     Management application are provided in the <literal>README</literal> file
     from scenario in use.</para>
   </section>
+
+  <section id="auto_deploy_reporting">
+    <title>Automated Deployment Reporting</title>
+
+    <para>The Deployment Reporting functionality will generate a CSV file
+    containing information about all uCPE Devices deployed with Enea Edge and
+    enrolled into the Enea Edge Management application.</para>
+
+    <para>The Python script for this solution is available in
+    <filename>modules/enea/utils/reporting/generate_deployment_report.py</filename>.</para>
+
+    <para>The information about uCPE Devices that will be found in the CSV
+    file is following:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>Device Name</para>
+      </listitem>
+
+      <listitem>
+        <para>Device ID</para>
+      </listitem>
+
+      <listitem>
+        <para>Enea Edge Runtime version</para>
+      </listitem>
+
+      <listitem>
+        <para>Number of CPU cores - If the device is disconnected, a warning
+        message appears in this field.</para>
+      </listitem>
+
+      <listitem>
+        <para>Timestamp when the device was added in the Enea Edge Management
+        application - If the device was never connected, a warning message
+        appears in this file.</para>
+      </listitem>
+
+      <listitem>
+        <para>The Enea Edge Management application IP or FQDN.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>Prerequisites:</para>
+
+    <orderedlist>
+      <listitem>
+        <para>Modify the Enea Edge Management configuration file, see "4.2.1
+        Configuration Files for the Enea Edge Management application" from
+        "Enea® Edge Automation User Guide" for more details.<remark>Add Olink
+        here</remark></para>
+      </listitem>
+
+      <listitem>
+        <para>For reporting devices connected to one Enea Edge Management
+        application instance, update the
+        <filename>modules/enea/config/Management/management01.json</filename>
+        file.</para>
+      </listitem>
+
+      <listitem>
+        <para>For reporting devices connected to multiple Enea Edge Management
+        application instances, a new JSON file will be created for
+        each.</para>
+
+        <para>The JSON file must have the following structure:</para>
+
+        <programlisting>{
+  "ucpe_usr":"&lt;Management Username&gt;",
+  "ucpe_pass":"&lt;Management Password&gt;",
+  "ucpe_host":"&lt;Management IP or FQDN&gt;"
+}</programlisting>
+
+        <para>All JSON files should be saved in the same directory and the
+        path to the directory will be a parameter of the script
+        (<literal>-m/--managements_directory</literal>).</para>
+      </listitem>
+
+      <listitem>
+        <para>Run the Python script to generate the CSV reporting:</para>
+
+        <programlisting>&gt; python modules/enea/utils/reporting/generate_deployment_report.py --help
+Usage: generate_deployment_report.py [OPTIONS]
+
+Options:
+  -r, --report_directory TEXT     The directory where the report will be
+                                  saved. Default: the current directory
+
+  -f, --filename TEXT             The name of the CSV report. Default:
+                                  Devices.csv
+
+  -t, --timestamp                 Append the timestamp to the filename.
+                                  Default: False
+
+  -m, --managements_directory TEXT
+                                  The directory where the JSON config files
+                                  for the Edge Management applications are
+                                  saved. Default:
+                                  ./modules/enea/config/Management/
+
+  -v, --version                   Display the version of the Edge Automation
+                                  and exit
+
+  --help                          Show this message and exit.</programlisting>
+      </listitem>
+    </orderedlist>
+  </section>
 </chapter>
\ No newline at end of file