summaryrefslogtreecommitdiffstats
path: root/doc/book-enea-edge-automation-user-guide
diff options
context:
space:
mode:
Diffstat (limited to 'doc/book-enea-edge-automation-user-guide')
-rw-r--r--doc/book-enea-edge-automation-user-guide/doc/automation_framework_test_harness.xml335
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 @@
150 <para><literal>VNF_images</literal> - contains the VNF images that 150 <para><literal>VNF_images</literal> - contains the VNF images that
151 are used in test scenarios.</para> 151 are used in test scenarios.</para>
152 </listitem> 152 </listitem>
153
154 <listitem>
155 <para><literal>utils</literal> - contains configurable solutions for
156 different features. For example, the solution for automated
157 deployment reporting can be found under this directory.</para>
158 </listitem>
153 </itemizedlist> 159 </itemizedlist>
154 </section> 160 </section>
155 161
@@ -234,14 +240,11 @@
234 <emphasis role="bold">Example</emphasis>: for a more extended output, 240 <emphasis role="bold">Example</emphasis>: for a more extended output,
235 change the output from selective to debug.</para> 241 change the output from selective to debug.</para>
236 242
237 <para>The <literal>test_harness</literal> directory contains all the 243 <para>The <literal>test_harness</literal> directory contains the custom
238 implemented playbooks. This directory is structured in multiple 244 Ansible modules, located in the modules directory, and the playbooks
239 subdirectories, each subdirectory represents a functionality of the Enea 245 mapping functionalities from the Enea Edge Management application. The
240 Edge Management application. Each implemented playbook from this 246 playbooks are atomic operations that can be used in complex test
241 directory runs a method from a Python class from the 247 scenarios.</para>
242 <literal>automation_framework</literal> directory. Each playbook is an
243 atomic operation, a basic operation that need to be tested. These
244 playbooks are used in complex test scenarios.</para>
245 </section> 248 </section>
246 249
247 <section id="log_dir"> 250 <section id="log_dir">
@@ -673,18 +676,6 @@ Check 'test' directory for JSON configuration files</programlisting>
673 </listitem> 676 </listitem>
674 677
675 <listitem> 678 <listitem>
676 <para><filename>vnfmgmt_ipv6_br.json</filename> - contains
677 <literal>VNF Management OVS bridge, IPv6</literal>:</para>
678
679 <programlisting>
680{
681 "name": "vnfmgmt_ipv6_br",
682 "type": "vnfMgmt",
683 "vnfMgmtAddress": "2001:db8:0:0:0:0:0:0"
684}</programlisting>
685 </listitem>
686
687 <listitem>
688 <para><filename>lan_br.json</filename> - contains 679 <para><filename>lan_br.json</filename> - contains
689 <literal>Dataplane OVS bridge</literal>; Type: 680 <literal>Dataplane OVS bridge</literal>; Type:
690 <literal>communication</literal>; Interface: 681 <literal>communication</literal>; Interface:
@@ -1305,41 +1296,81 @@ Parameters(not needed): --
1305 <literal>&lt;Automation-installerdir&gt;/test_harness</literal> 1296 <literal>&lt;Automation-installerdir&gt;/test_harness</literal>
1306 directory.</para> 1297 directory.</para>
1307 1298
1299 <para>The Ansible based Test Harness represents an example of structuring
1300 the files needed for creating automated test cases using the Enea Edge
1301 Automation, and provides a way to implement them.</para>
1302
1303 <para>The <filename>ansible.cfg</filename> file contains an example of the
1304 Ansible default configuration. The default value for
1305 <literal>stdout_callback</literal> is set to <literal>selective</literal>,
1306 to print only certain tasks. It is recommended to switch to
1307 <literal>debug</literal> when a test fails. By setting the parameter
1308 <literal>any_errors_fatal</literal> to <literal>True</literal>, task
1309 failures are considered fatal errors and the play execution stops.</para>
1310
1311 <para>All the Playbooks that execute Automation Framework Python modules
1312 run on <literal>localhost</literal>. New entries have to be created for
1313 direct communication over SSH with the boards.</para>
1314
1315 <para>The <filename>setup_env.sh</filename> script sets up the
1316 <literal>testHarness</literal> test environment by creating the
1317 <literal>testHarness-venv</literal> Python virtual environment, executing
1318 requests needed by Automation Framework Python modules, and installing
1319 Ansible. The Ansible package version is 2.9.6.</para>
1320
1321 <section id="ansible_mods">
1322 <title>Ansible modules</title>
1323
1324 <para>The custom Ansible modules can be found in the
1325 <literal>test_harness/modules/</literal> directory. The Ansible modules
1326 are wrappers of Python Handlers from the
1327 <literal>automation_framework/</literal> directory. Each Ansible module
1328 has been designed to instantiate a Python handler and to run a method of
1329 it with specific parameters.</para>
1330
1331 <para>The Ansible modules are used in Ansible playbooks as:</para>
1332
1333 <programlisting>&lt;name_of_the_module&gt;:
1334 method: &lt;which method will be called&gt;
1335 &lt;param1&gt;: &lt;value_of_param1&gt;
1336 &lt;param2&gt;: &lt;value_of_param2&gt;
1337 ...
1338 &lt;paramx&gt;: &lt;value_of_paramx&gt;
1339 chdir: &lt;the path where the Ansible playbook will be run&gt;</programlisting>
1340
1341 <para>The method is a mandatory argument for all Ansible modules, the
1342 other arguments are optional. The method must exist in the
1343 <literal>&lt;name_of_the_module&gt;</literal> Ansible module. The params
1344 list (param1, param2... paramx) must have the same name as the
1345 parameters of the method, otherwise an error will occur.</para>
1346
1347 <para>For example, for adding a uCPE Device into the Enea Edge
1348 Management application from an Ansible playbook, the
1349 <filename>uCPEDeviceModule</filename> should be used as:</para>
1350
1351 <programlisting>uCPEDeviceModule:
1352 method: addDevice
1353 device_name: &lt;name_of_the device&gt;
1354 chdir: "{{ lookup('env','BASE_DIR') }}"</programlisting>
1355
1356 <para>This will call the <literal>addDevice</literal> method from the
1357 <literal>uCPEDevice</literal> class that instantiates a
1358 <literal>uCPEDeviceHandler</literal> object for the
1359 <literal>device_name</literal> uCPE Device. Afterwards, the
1360 <literal>addDevice</literal> method is called.</para>
1361
1362 <para>The list of possible parameters for all methods of an Ansible
1363 module is saved in the <filename>module_args</filename> dictionary in
1364 the Python script. The default value of all parameters is
1365 <literal>None</literal>.</para>
1366 </section>
1367
1308 <section id="indiv_ansible_playbooks"> 1368 <section id="indiv_ansible_playbooks">
1309 <title>Individual Ansible Playbooks</title> 1369 <title>Individual Ansible Playbooks</title>
1310 1370
1311 <para>The Ansible based Test Harness represents an example of
1312 structuring the files needed for creating automated test cases using the
1313 Enea Edge Automation, and provides a way to implement them.</para>
1314
1315 <para>The <filename>ansible.cfg</filename> file contains an example of
1316 the Ansible default configuration. The default value for
1317 <literal>stdout_callback</literal> is set to
1318 <literal>selective</literal>, to print only certain tasks. It is
1319 recommended to switch to <literal>debug</literal> when a test fails. By
1320 setting the parameter <literal>any_errors_fatal</literal> to
1321 <literal>True</literal>, task failures are considered fatal errors and
1322 the play execution stops.</para>
1323
1324 <para>All the Playbooks that execute Automation Framework Python modules
1325 run on <literal>localhost</literal>. New entries have to be created for
1326 direct communication over SSH with the boards.</para>
1327
1328 <para>The <filename>setup_env.sh</filename> script sets up the
1329 <literal>testHarness</literal> test environment by creating the
1330 <literal>testHarness-venv</literal> Python virtual environment,
1331 executing requests needed by Automation Framework Python modules, and
1332 installing Ansible. The Ansible package version is 2.9.6.</para>
1333
1334 <para>The <literal>test_harness</literal> directory contains all the 1371 <para>The <literal>test_harness</literal> directory contains all the
1335 implemented Ansible Playbooks. This directory contains the 1372 implemented Ansible Playbooks and many subdirectories, each subdirectory
1336 <filename>check_error.yml</filename> Playbook and many subdirectories, 1373 representing an Enea Edge Management module.</para>
1337 each subdirectory representing an Enea Edge Management module.</para>
1338
1339 <para>The <filename>check_errors.yml</filename> Playbook checks the
1340 Python output and returns success or fail results. This file is imported
1341 in all playbooks from the <literal>test_harness</literal> directory and
1342 it cannot be run standalone.</para>
1343 1374
1344 <para>According to their functionality, the Ansible Playbooks that refer 1375 <para>According to their functionality, the Ansible Playbooks that refer
1345 to offline configuration are in the <literal>OfflineConfig</literal> 1376 to offline configuration are in the <literal>OfflineConfig</literal>
@@ -1366,61 +1397,46 @@ Parameters(not needed): --
1366 1397
1367 <para><emphasis role="bold">Example</emphasis>:</para> 1398 <para><emphasis role="bold">Example</emphasis>:</para>
1368 1399
1369 <orderedlist> 1400 <para>Display the help menu for
1370 <listitem> 1401 <filename>addDataPlaneOvsBridge.yml</filename>:</para>
1371 <para>Display the help menu for 1402
1372 <filename>addDataPlaneOvsBridge.yml</filename>:</para> 1403 <programlisting>ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml
1373 1404.
1374 <programlisting>ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml 1405# fail *************************************************************
1375 1406 * localhost - FAILED!!! -------------------------
1376This playbook runs 'addDataPlaneOvsBridge' method from uCPEDeviceHandler module 1407 The 'device' and 'bridge_config_file' or 'bridge_name' and \
1377 1408'bridge_type' parameters are mandatory
1378 The Python module will be run as: 1409 Usage:
1379 1410 ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml \
1380 Usage: uCPEDeviceHandler.py [OPTIONS] [PARAMETERS]... 1411-e "device=&lt;device_name&gt; bridge_config_file=&lt;bridge_config_file&gt;"
1381 1412 ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml \
1382 Options: 1413-e "device=&lt;device_name&gt; bridge_name=&lt;bridge_name&gt; bridge_type=integration"
1383 -v, --verbose Get info about the methods and parameters 1414 ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml \
1384 -d, --device_name TEXT The uCPE Device name 1415-e "device=&lt;device_name&gt; bridge_name=&lt;bridge_name&gt; bridge_type=communication"
1385 -m, --method TEXT The atomic operation you want to run 1416 ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml \
1386 -f, --config_file TEXT The config file for NIC or bridges (optional 1417-e "device=&lt;device_name&gt; bridge_name=&lt;bridge_name&gt; \
1387 argument) 1418bridge_type=communication interfaces=&lt;interfaces&gt;"
1388 1419
1389 -o, --display_output Display output of the method 1420 Example of usage:
1390 --help Show this message and exit. 1421 ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml \
1391 1422-e "device=inteld1521-17 bridge_config_file=sfc_br.json"
1392Usage: 1423 ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml \
1393 ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml -e 1424-e "device=inteld1521-17 bridge_config_file=lan_br.json"
1394 "device=&lt;device_name&gt; bridge_config_file=&lt;bridge_config_file&gt;" 1425 ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml \
1395 ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml -e 1426-e "device=inteld1521-17 bridge_name=sfc_br bridge_type=integration"
1396 "device=&lt;device_name&gt; bridge_name=&lt;bridge_name&gt; bridge_type=integration" 1427 ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml \
1397 ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml -e 1428-e "device=inteld1521-17 bridge_name=wap_br bridge_type=communication"
1398 "device=&lt;device_name&gt; bridge_name=&lt;bridge_name&gt; bridge_type=communication" 1429 ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml \
1399 ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml -e 1430-e "device=inteld1521-17 bridge_name=lan_br \
1400 "device=&lt;device_name&gt; bridge_name=&lt;bridge_name&gt; bridge_type=communication 1431bridge_type=communication interfaces=eno4"
1401 interfaces=&lt;interfaces&gt;"</programlisting> 1432 ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml \
1402 </listitem> 1433-e "device=inteld1521-17 bridge_name=lan_br \
1403 1434bridge_type=communication interfaces=eno4,eno5"
1404 <listitem> 1435
1405 <para>Run the <filename>addDataPlaneOvsBridge.yml</filename> 1436
1406 playbook:</para> 1437# STATS ************************************************************
1407 1438localhost : ok=1 changed=0 failed=1 unreachable=0 \
1408 <programlisting>ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml -e 1439rescued=0 ignored=0</programlisting>
1409"device=inteld1521-17 bridge_config_file=sfc_br.json"
1410ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml -e
1411"device=inteld1521-17 bridge_config_file=lan_br.json"
1412ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml -e
1413"device=inteld1521-17 bridge_name=sfc_br bridge_type=integration"
1414ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml -e
1415"device=inteld1521-17 bridge_name=wap_br bridge_type=communication"
1416ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml -e
1417"device=inteld1521-17 bridge_name=lan_br bridge_type=communication
1418interfaces=eno4"
1419ansible-playbook test_harness/uCPEDevice/addDataPlaneOvsBridge.yml -e
1420"device=inteld1521-17 bridge_name=lan_br bridge_type=communication
1421interfaces=eno4,eno5"</programlisting>
1422 </listitem>
1423 </orderedlist>
1424 1440
1425 <para>Each Ansible Playbook from the <literal>test_harness</literal> 1441 <para>Each Ansible Playbook from the <literal>test_harness</literal>
1426 directory represents an atomic operation, a basic functionality that is 1442 directory represents an atomic operation, a basic functionality that is
@@ -1599,4 +1615,111 @@ vnfi_name: "fortigateFWInstance"</programlisting>
1599 Management application are provided in the <literal>README</literal> file 1615 Management application are provided in the <literal>README</literal> file
1600 from scenario in use.</para> 1616 from scenario in use.</para>
1601 </section> 1617 </section>
1618
1619 <section id="auto_deploy_reporting">
1620 <title>Automated Deployment Reporting</title>
1621
1622 <para>The Deployment Reporting functionality will generate a CSV file
1623 containing information about all uCPE Devices deployed with Enea Edge and
1624 enrolled into the Enea Edge Management application.</para>
1625
1626 <para>The Python script for this solution is available in
1627 <filename>modules/enea/utils/reporting/generate_deployment_report.py</filename>.</para>
1628
1629 <para>The information about uCPE Devices that will be found in the CSV
1630 file is following:</para>
1631
1632 <itemizedlist>
1633 <listitem>
1634 <para>Device Name</para>
1635 </listitem>
1636
1637 <listitem>
1638 <para>Device ID</para>
1639 </listitem>
1640
1641 <listitem>
1642 <para>Enea Edge Runtime version</para>
1643 </listitem>
1644
1645 <listitem>
1646 <para>Number of CPU cores - If the device is disconnected, a warning
1647 message appears in this field.</para>
1648 </listitem>
1649
1650 <listitem>
1651 <para>Timestamp when the device was added in the Enea Edge Management
1652 application - If the device was never connected, a warning message
1653 appears in this file.</para>
1654 </listitem>
1655
1656 <listitem>
1657 <para>The Enea Edge Management application IP or FQDN.</para>
1658 </listitem>
1659 </itemizedlist>
1660
1661 <para>Prerequisites:</para>
1662
1663 <orderedlist>
1664 <listitem>
1665 <para>Modify the Enea Edge Management configuration file, see "4.2.1
1666 Configuration Files for the Enea Edge Management application" from
1667 "Enea® Edge Automation User Guide" for more details.<remark>Add Olink
1668 here</remark></para>
1669 </listitem>
1670
1671 <listitem>
1672 <para>For reporting devices connected to one Enea Edge Management
1673 application instance, update the
1674 <filename>modules/enea/config/Management/management01.json</filename>
1675 file.</para>
1676 </listitem>
1677
1678 <listitem>
1679 <para>For reporting devices connected to multiple Enea Edge Management
1680 application instances, a new JSON file will be created for
1681 each.</para>
1682
1683 <para>The JSON file must have the following structure:</para>
1684
1685 <programlisting>{
1686 "ucpe_usr":"&lt;Management Username&gt;",
1687 "ucpe_pass":"&lt;Management Password&gt;",
1688 "ucpe_host":"&lt;Management IP or FQDN&gt;"
1689}</programlisting>
1690
1691 <para>All JSON files should be saved in the same directory and the
1692 path to the directory will be a parameter of the script
1693 (<literal>-m/--managements_directory</literal>).</para>
1694 </listitem>
1695
1696 <listitem>
1697 <para>Run the Python script to generate the CSV reporting:</para>
1698
1699 <programlisting>&gt; python modules/enea/utils/reporting/generate_deployment_report.py --help
1700Usage: generate_deployment_report.py [OPTIONS]
1701
1702Options:
1703 -r, --report_directory TEXT The directory where the report will be
1704 saved. Default: the current directory
1705
1706 -f, --filename TEXT The name of the CSV report. Default:
1707 Devices.csv
1708
1709 -t, --timestamp Append the timestamp to the filename.
1710 Default: False
1711
1712 -m, --managements_directory TEXT
1713 The directory where the JSON config files
1714 for the Edge Management applications are
1715 saved. Default:
1716 ./modules/enea/config/Management/
1717
1718 -v, --version Display the version of the Edge Automation
1719 and exit
1720
1721 --help Show this message and exit.</programlisting>
1722 </listitem>
1723 </orderedlist>
1724 </section>
1602</chapter> \ No newline at end of file 1725</chapter> \ No newline at end of file