User Guide April 13th update, for Fraser MS9

JIRA: AUTO-26

Updated user guide for each Use Case:
- UC1: minor typos
- UC2: new figures (test logic, cardinalities), additional text
- UC3: new figures (test cases mapped on architecture), updated
text, aligned with updated UC3 definition

Change-Id: I45faef95fde8eb362faffaa7469a0f2e1bcbf318
Signed-off-by: Gerard Damm <gerard.damm@wipro.com>

12 files changed, 76 insertions, 34 deletions

diff --git a/docs/release/userguide/UC01-feature.userguide.rst b/docs/release/userguide/UC01-feature.userguide.rst
index 5cf38e1..ea02bad 100644
--- a/docs/release/userguide/UC01-feature.userguide.rst
+++ b/docs/release/userguide/UC01-feature.userguide.rst
@@ -34,7 +34,7 @@ Preconditions:
 
 Main Success Scenarios:
 
-* lifecycle management - stop, stop, scale (dependent upon telemetry)
+* lifecycle management - start, stop, scale (dependent upon telemetry)
 
 * recovering from faults (detect, determine appropriate response, act); i.e. exercise closed-loop policy engine in ONAP
 
@@ -47,7 +47,7 @@ Details on the test cases corresponding to this use case:
 
 * Environment check
 
-  * Basic environment check: Create test script to check basic VIM (OpenStack), ONAP, and VNF are up and running
+  * Basic environment check: Create test script to check basic VIM (OpenStack), ONAP, and VNF(s) are up and running
 
 * VNF lifecycle management
 
@@ -55,7 +55,7 @@ Details on the test cases corresponding to this use case:
 
   * Tacker Monitoring Driver (VNFMonitorPing):
 
-    * Write Tacker Monitor driver to handle monitor_call and based on return state value create custom events
+    * Write Tacker Monitor driver to handle monitor_call and, based on return state value, create custom events
     * If Ping to VNF fails, trigger below events
 
       * Event 1 : Collect failure logs from VNF
diff --git a/docs/release/userguide/UC02-feature.userguide.rst b/docs/release/userguide/UC02-feature.userguide.rst
index 0ecb7de..3ed5781 100644
--- a/docs/release/userguide/UC02-feature.userguide.rst
+++ b/docs/release/userguide/UC02-feature.userguide.rst
@@ -8,7 +8,8 @@
 Auto User Guide: Use Case 2 Resiliency Improvements Through ONAP
 ================================================================
 
-This document provides the user guide for Fraser release of Auto, specifically for Use Case 2: Resiliency Improvements Through ONAP.
+This document provides the user guide for Fraser release of Auto,
+specifically for Use Case 2: Resiliency Improvements Through ONAP.
 
 
 Description
@@ -22,6 +23,8 @@ This use case illustrates VNF failure recovery time reduction with ONAP, thanks
 
 The benefit for NFV edge service providers is to assess what degree of added VIM+NFVI platform resilience for VNFs is obtained by leveraging ONAP closed-loop control, vs. VIM+NFVI self-managed resilience (which may not be aware of the VNF or the corresponding end-to-end Service, but only of underlying resources such as VMs and servers).
 
+Also, a problem, or challenge, may not necessarily be a failure (which could also be recovered by other layers): it could be an issue leading to suboptimal performance, without failure. A VNF management layer as provided by ONAP may detect such non-failure problems, and provide a recovery solution which no other layer could provide in a given deployment.
+
 
 Preconditions:
 
@@ -36,7 +39,7 @@ Different types of problems can be simulated, hence the identification of multip
 
 .. image:: auto-UC02-testcases.jpg
 
-Description of simulated problems/challenges:
+Description of simulated problems/challenges, leading to various test cases:
 
 * Physical Infra Failure
 
@@ -60,7 +63,6 @@ Description of simulated problems/challenges:
 
 
 
-
 Test execution high-level description
 =====================================
 
@@ -76,7 +78,7 @@ The second MSC illustrates the pattern of all test cases for the Resiliency Impr
 * simulate the chosen problem (a.k.a. a "Challenge") for this test case, for example suspend a VM which may be used by a VNF
 * start tracking the target VNF of this test case
 * measure the ONAP-orchestrated VNF Recovery Time
-* then the test stops simulating the problem (for example: resume the VM that was suspended),
+* then the test stops simulating the problem (for example: resume the VM that was suspended)
 
 In parallel, the MSC also shows the sequence of events happening in ONAP, thanks to its configuration to provide Service Assurance for the VNF.
 
@@ -86,21 +88,21 @@ In parallel, the MSC also shows the sequence of events happening in ONAP, thanks
 Test design: data model, implementation modules
 ===============================================
 
-The high-level design of classes identifies several entities:
+The high-level design of classes identifies several entities, described as follows:
 
-* Test Case: as identified above, each is a special case of the overall use case (e.g., categorized by challenge type)
-* Test Definition: gathers all the information necessary to run a certain test case
-* Metric Definition: describes a certain metric that may be measured, in addition to Recovery Time
-* Challenge Definition: describe the challenge (problem, failure, stress, ...) simulated by the test case
-* Recipient: entity that can receive commands and send responses, and that is queried by the Test Definition or Challenge Definition (a recipient would be typically a management service, with interfaces (CLI or API) for clients to query)
-* Resources: with 3 types (VNF, cloud virtual resource such as a VM, physical resource such as a server)
+* ``Test Case`` : as identified above, each is a special case of the overall use case (e.g., categorized by challenge type)
+* ``Test Definition`` : gathers all the information necessary to run a certain test case
+* ``Metric Definition`` : describes a certain metric that may be measured for a Test Case, in addition to Recovery Time
+* ``Challenge Definition`` : describe the challenge (problem, failure, stress, ...) simulated by the test case
+* ``Recipient`` : entity that can receive commands and send responses, and that is queried by the Test Definition or Challenge Definition (a recipient would be typically a management service, with interfaces (CLI or API) for clients to query)
+* ``Resources`` : with 3 types (VNF, cloud virtual resource such as a VM, physical resource such as a server)
 
 
 Three of these entities have execution-time corresponding classes:
 
-* Test Execution, which captures all the relevant data of the execution of a Test Definition
-* Challenge Execution, which captures all the relevant data of the execution of a Challenge Definition
-* Metric Value, which captures the a quantitative measurement of a Metric Definition (with a timestamp)
+* ``Test Execution`` , which captures all the relevant data of the execution of a Test Definition
+* ``Challenge Execution`` , which captures all the relevant data of the execution of a Challenge Definition
+* ``Metric Value`` , which captures the quantitative measurement of a Metric Definition (with a timestamp)
 
 .. image:: auto-UC02-data1.jpg
 
@@ -122,13 +124,28 @@ The module design is straightforward: functions and classes for managing data, f
 .. image:: auto-UC02-module1.jpg
 
 
-This last diagram shows the test user menu functions:
+This last diagram shows the test user menu functions, when used interactively:
 
 .. image:: auto-UC02-module2.jpg
 
 
-In future releases of Auto, testing environments such as FuncTest and Yardstick might be leveraged.
+In future releases of Auto, testing environments such as Robot, FuncTest and Yardstick might be leveraged. Use Case code will then be invoked by API, not by a CLI interaction.
 
 Also, anonymized test results could be collected from users willing to share them, and aggregates could be
 maintained as benchmarks.
 
+As further illustration, the next figure shows cardinalities of class instances: one Test Definition per Test Case, multiple Test Executions per Test Definition, zero or one Recovery Time Metric Value per Test Execution (zero if the test failed for any reason, including if ONAP failed to recover the challenge), etc.
+
+.. image:: auto-UC02-cardinalities.png
+
+
+In this particular implementation, both Test Definition and Challenge Definition classes have a generic execution method (e.g., ``run_test_code()`` for Test Definition) which can invoke a particular script, by way of an ID (which can be configured, and serves as a script selector for each Test Definition instance). The overall test execution logic between classes is show in the next figure.
+
+.. image:: auto-UC02-logic.png
+
+The execution of a test case starts with invoking the generic method from Test Definition, which then creates Execution instances, invokes Challenge Definition methods, performs the Recovery time calculation, performs script-specific actions, and writes results to the CSV files.
+
+Finally, the following diagram show a mapping between these class instances and the initial test case design. It corresponds to the test case which simulates a VM failure, and shows how the OpenStack SDK API is invoked (with a connection object) by the Challenge Definition methods, to suspend and resume a VM.
+
+.. image:: auto-UC02-TC-mapping.png
+
diff --git a/docs/release/userguide/UC03-feature.userguide.rst b/docs/release/userguide/UC03-feature.userguide.rst
index 5f28158..cf96981 100644
--- a/docs/release/userguide/UC03-feature.userguide.rst
+++ b/docs/release/userguide/UC03-feature.userguide.rst
@@ -15,16 +15,25 @@ specifically for Use Case 3: Enterprise vCPE.
 Description
 ===========
 
-This Use Case shows how ONAP can help ensuring that virtual CPEs (including vFW: virtual firewalls) in Edge Cloud are enterprise-grade.
+This Use Case shows how ONAP can help ensure that virtual CPEs (including vFW: virtual firewalls) in Edge Cloud are enterprise-grade.
+Other vCPE examples: vAAA, vDHCP, vDNS, vGW, vBNG, vRouter, ...
 
-ONAP operations include a verification process for VNF onboarding (i.e. inclusion in the ONAP catalog), with multiple Roles (designer, tester, governor, operator), responsible for approving proposed VNFs (as VSPs (Vendor Software Products), and eventually as end-to-end Services).
+ONAP operations include a verification process for VNF onboarding (i.e., inclusion in the ONAP catalog), with multiple Roles (Designer, Tester, Governor, Operator), responsible for approving proposed VNFs (as VSPs (Vendor Software Products), and eventually as end-to-end Services).
 
-This process guarantees a minimum level of quality of onboarded VNFs. If all deployed vCPEs are only chosen from such an approved ONAP catalog, the resulting deployed end-to-end vCPE services will meet enterprise-grade requirements. ONAP provides a NBI in addition to a standard portal, thus enabling a programmatic deployment of VNFs, still conforming to ONAP processes.
+This process guarantees a minimum level of quality of onboarded VNFs. If all deployed vCPEs are only chosen from such an approved ONAP catalog, the resulting deployed end-to-end vCPE services will meet enterprise-grade requirements. ONAP provides a NBI (currently HTTP-based) in addition to a standard GUI portal, thus enabling a programmatic deployment of VNFs, still conforming to ONAP processes.
 
-Moreover, ONAP also comprises real-time monitoring (by the DCAE component), which monitors performance for SLAs, can adjust allocated resources accordingly (elastic adjustment at VNF level), and can ensure High Availability.
+Moreover, ONAP also comprises real-time monitoring (by the DCAE component), which can perform the following functions:
+
+* monitor VNF performance for SLAs
+* adjust allocated resources accordingly (elastic adjustment at VNF level: scaling out and in, possibly also scaling up and down)
+* ensure High Availability (restoration of failed or underperforming services)
 
 DCAE executes directives coming from policies described in the Policy Framework, and closed-loop controls described in the CLAMP component.
 
+ONAP can perform the provisioning side of a BSS Order Management application handling vCPE orders.
+
+Additional processing can be added to ONAP (internally as configured policies and closed-loop controls, or externally as separate systems): Path Computation Element and Load Balancing, and even telemetry-based Network Artificial Intelligence.
+
 Finally, this automated approach also reduces costs, since repetitive actions are designed once and executed multiple times, as vCPEs are instantiated and decommissioned (frequent events, given the variability of business activity, and a Small Business market similar to the Residential market: many contract updates resulting in many vCPE changes).
 
 NFV edge service providers need to provide site2site, site2dc (Data Center) and site2internet services to tenants both efficiently and safely, by deploying such qualified enterprise-grade vCPE.
@@ -42,34 +51,50 @@ Main Success Scenarios:
 
 * VNF spin-up
 
-  * vCPE spin-up: MSO calls the VNFM to spin up a vCPE instance from the catalog and then updates the active VNF list
   * vFW spin-up: MSO calls the VNFM to spin up a vFW instance from the catalog and then updates the active VNF list
+  * other vCPEs spin-up: MSO calls the VNFM to spin up a vCPE instance from the catalog and then updates the active VNF list
 
 * site2site
 
   * L3VPN service subscribing: MSO calls the SDNC to create VXLAN tunnels to carry L2 traffic between client's ThinCPE and SP's vCPE, and enables vCPE to route between different sites.
   * L3VPN service unsubscribing: MSO calls the SDNC to destroy tunnels and routes, thus disable traffic between different sites.
 
+* site2dc (site to Data Center) by VPN
+* site2internet
+* scaling control (start with scaling out/in)
 
 See `ONAP description of vCPE use case <https://wiki.onap.org/display/DW/Use+Case+proposal%3A+Enterprise+vCPE>`_ for more details, including MSCs.
 
 
 Details on the test cases corresponding to this use case:
 
-* VNF Management
+* vCPE VNF deployment
+
+  * Spin up a vFW instance by calling NBI of the orchestrator.
+  * Following the vFW example and pattern, spin up other vCPE instances
+
+* vCPE VNF networking
+
+  * Subscribe/Unsubscribe to a VPN service: configure tenant/subscriber for vCPE, configure VPN service
+  * Subscribe/Unsubscribe to an Internet Access service: configure tenant/subscriber for vCPE, configure Internet Access service
+
+* vCPE VNF Scaling
+
+  * ONAP-based VNF Scale-out and Scale-in (using measurements arriving in DCAE, policies/CLAMP or external system performing LB function)
+  * later, possibly also scale-up and scale-down
+
+
+
+The following diagram shows these test cases:
+
+.. image:: auto-UC03-TestCases.png
 
-  * Spin up a vCPE instance: Spin up a vCPE instance, by calling NBI of the orchestrator.
-  * Spin up a vFW instance: Spin up a vFW instance, by calling NBI of the orchestrator.
 
-* VPN as a Service
+Illustration of test cases mapped to architecture, with possible external systems (BSS for Order Management, PCE+LB, Network AI:
 
-  * Subscribe to a VPN service: Subscribe to a VPN service, by calling NBI of the orchestrator.
-  * Unsubscribe to a VPN service: Unsubscribe to a VPN service, by calling NBI of the orchestrator.
+.. image:: auto-UC03-TC-archit.png
 
-* Internet as a Service
 
-  * Subscribe to an Internet service: Subscribe to an Internet service, by calling NBI of the orchestrator.
-  * Unsubscribe to an Internet service: Unsubscribe to an Internet service, by calling NBI of the orchestrator.
 
 
 Test execution high-level description
diff --git a/docs/release/userguide/auto-UC02-TC-mapping.png b/docs/release/userguide/auto-UC02-TC-mapping.png
new file mode 100644
index 0000000..c2dd0db
--- /dev/null
+++ b/docs/release/userguide/auto-UC02-TC-mapping.png
diff --git a/docs/release/userguide/auto-UC02-cardinalities.png b/docs/release/userguide/auto-UC02-cardinalities.png
new file mode 100644
index 0000000..10dd3b0
--- /dev/null
+++ b/docs/release/userguide/auto-UC02-cardinalities.png
diff --git a/docs/release/userguide/auto-UC02-data1.jpg b/docs/release/userguide/auto-UC02-data1.jpg
index 02a60ba..62526c5 100644
--- a/docs/release/userguide/auto-UC02-data1.jpg
+++ b/docs/release/userguide/auto-UC02-data1.jpg
diff --git a/docs/release/userguide/auto-UC02-data2.jpg b/docs/release/userguide/auto-UC02-data2.jpg
index 7096c96..df73a94 100644
--- a/docs/release/userguide/auto-UC02-data2.jpg
+++ b/docs/release/userguide/auto-UC02-data2.jpg
diff --git a/docs/release/userguide/auto-UC02-data3.jpg b/docs/release/userguide/auto-UC02-data3.jpg
index 8e8921d..3f84a20 100644
--- a/docs/release/userguide/auto-UC02-data3.jpg
+++ b/docs/release/userguide/auto-UC02-data3.jpg
diff --git a/docs/release/userguide/auto-UC02-logic.png b/docs/release/userguide/auto-UC02-logic.png
new file mode 100644
index 0000000..90b41dd
--- /dev/null
+++ b/docs/release/userguide/auto-UC02-logic.png
diff --git a/docs/release/userguide/auto-UC03-TC-archit.png b/docs/release/userguide/auto-UC03-TC-archit.png
new file mode 100644
index 0000000..95d641b
--- /dev/null
+++ b/docs/release/userguide/auto-UC03-TC-archit.png
diff --git a/docs/release/userguide/auto-UC03-TestCases.png b/docs/release/userguide/auto-UC03-TestCases.png
new file mode 100644
index 0000000..bb84a57
--- /dev/null
+++ b/docs/release/userguide/auto-UC03-TestCases.png
diff --git a/docs/release/userguide/index.rst b/docs/release/userguide/index.rst
index 7cfbe94..dd308dc 100644
--- a/docs/release/userguide/index.rst
+++ b/docs/release/userguide/index.rst
@@ -16,7 +16,7 @@ OPNFV Auto (ONAP-Automated OPNFV) User Guide
 
 .. toctree::
    :numbered:
-   :maxdepth: 2
+   :maxdepth: 3
 
    UC01-feature.userguide.rst
    UC02-feature.userguide.rst