4 files changed, 338 insertions, 196 deletions
diff --git a/docs/release/userguide/UC01-feature.userguide.rst b/docs/release/userguide/UC01-feature.userguide.rst
index 28e1097..fd3a05f 100644
--- a/docs/release/userguide/UC01-feature.userguide.rst
+++ b/docs/release/userguide/UC01-feature.userguide.rst
@@ -1,24 +1,81 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-.. SPDX-License-Identifier CC-BY-4.0
-.. (c) optionally add copywriters name
-
-.. contents::
-   :depth: 3
-   :local:
-
-OPNFV Auto Use Case 1: Edge Cloud description
-=========================================================
-.. Describe the specific features and how it is realised in the scenario in a brief manner
-.. to ensure the user understand the context for the user guide instructions to follow.
-
-OPNFV Auto Use Case 1: Edge Cloud capabilities and usage
-=========================================================
-.. Describe the specific capabilities and usage for <XYZ> feature.
-.. Provide enough information that a user will be able to operate the feature on a deployed scenario.
-
-<Feature and API usage guidelines and example>
-=========================================================
-.. Describe with examples how to use specific features, provide API examples and details required to
-.. operate the feature on the platform.
-
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. SPDX-License-Identifier CC-BY-4.0
+.. (c) optionally add copywriters name
+
+.. contents::
+   :depth: 3
+   :local:
+
+
+======================================
+Auto User Guide: Use Case 1 Edge Cloud
+======================================
+
+This document provides the user guide for Fraser release of Auto,
+specifically for Use Case 1: Edge Cloud.
+
+
+Description
+===========
+
+This use case aims at showcasing the benefits of using ONAP for autonomous Edge Cloud management.
+
+A high level of automation of VNF lifecycle event handling after launch is enabled by ONAP policies
+and closed-loop controls, which take care of most lifecycle events (start, stop, scale up/down/in/out,
+recovery/migration for HA) as well as their monitoring and SLA management.
+
+Multiple types of VNFs, for different execution environments, are first approved in the catalog thanks
+to the onboarding process, and then can be deployed and handled by multiple controllers in a systematic way.
+
+This results in management efficiency (lower control/automation overhead) and high degree of autonomy.
+
+
+Preconditions:
+#. hardware environment in which Edge cloud may be deployed
+#. an Edge cloud has been deployed and is ready for operation
+#. ONAP has been deployed onto a Cloud, and is interfaced (i.e. provisioned for API access) to the Edge cloud
+
+
+
+Main Success Scenarios:
+
+* lifecycle management - stop, stop, scale (dependent upon telemetry)
+
+* recovering from faults (detect, determine appropriate response, act); i.e. exercise closed-loop policy engine in ONAP
+
+  * verify mechanics of control plane interaction
+
+* collection of telemetry for machine learning
+
+
+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
+
+* VNF lifecycle management
+
+  * VNF Instance Management: Validation of VNF Instance Management which includes VNF instantiation, VNF State Management and termination
+
+  * Tacker Monitoring Driver (VNFMonitorPing):
+
+    * 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
+      * Event 2 : Soft restart/respawn the VNF
+
+  * Integrate with Telemetry
+
+    * Create TOSCA template policies to implement ceilometer  data collection service
+    * Collect CPU utilization data, compare with threshold, and perform action accordingly (respawn, scale-in/scale-out)
+
+
+
+Test execution high-level description
+=====================================
+
+<TBC>
+
diff --git a/docs/release/userguide/UC02-feature.userguide.rst b/docs/release/userguide/UC02-feature.userguide.rst
index 39f0fd3..d5b9481 100644
--- a/docs/release/userguide/UC02-feature.userguide.rst
+++ b/docs/release/userguide/UC02-feature.userguide.rst
@@ -1,119 +1,138 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-.. SPDX-License-Identifier CC-BY-4.0
-.. (c) optionally add copywriters name
-
-
-================================================================
-Auto User Guide: Use Case 2 Resiliency Improvements Through ONAP
-================================================================
-
-This document provides the release notes for Fraser release of Auto,
-specifically for Use Case 2: Resiliency Improvements Through ONAP.
-
-.. contents::
-   :depth: 3
-   :local:
-
-
-Description
-===========
-
-This use case illustrates VNF failure recovery time reduction with ONAP, thanks to its automated monitoring and management.
-It simulates an underlying problem (failure, stress, etc.: any adverse condition in the network that can impact VNFs),
-tracks a VNF, and measures the amount of time it takes for ONAP to restore the VNF functionality. 
-
-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).
-
-Preconditions:
-#. hardware environment in which Edge cloud may be deployed
-#. Edge cloud has been deployed and is ready for operation
-#. ONAP has been deployed onto a cloud and is interfaced (i.e. provisioned for API access) to the Edge cloud
-#. Components of ONAP have been deployed on the Edge cloud as necessary for specific test objectives
-
-In future releases, Auto Use cases will also include the deployment of ONAP (if not already installed), the deployment
-of test VNFs (pre-existing VNFs in pre-existing ONAP can be used in the test as well), the configuration of ONAP for
-monitoring these VNFs (policies, CLAMP, DCAE), in addition to the test scripts which simulate a problem and measures recovery time.
-
-Different types of problems can be simulated, hence the identification of multiple test cases corresponding to this use case,
-as illustrated in this diagram:
-
-.. image:: auto-UC02-testcases.jpg
-
-
-Test execution high-level description
-=====================================
-
-The following two MSCs (Message Sequence Charts) show the actors and high-level interactions.
-
-The first MSC shows the preparation activities (assuming the hardware, network, cloud, and ONAP have already been installed):
-onboarding and deployment of VNFs (via ONAP portal and modules in sequence: SDC, VID, SO), and ONAP configuration
-(policy framework, closed-loops in CLAMP, activation of DCAE).
-
-.. image:: auto-UC02-preparation.jpg
-
-The second MSC illustrates the pattern of all test cases for the Resiliency Improvements:
-* 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),
-
-In parallel, the MSC also shows the sequence of events happening in ONAP, thanks to its configuration to provide Service
-Assurance for the VNF.
-
-.. image:: auto-UC02-pattern.jpg
-
-
-Test design: data model, implementation modules
-===============================================
-
-The high-level design of classes shows the identification of several entities:
-* 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)
-
-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)
-
-.. image:: auto-UC02-data1.jpg
-
-The following diagram illustrates an implementation-independent design of the attributes of these entities:
-.. image:: auto-UC02-data2.jpg
-
-This next diagram shows the Python classes and attributes, as implemented by this Use Case (for all test cases):
-
-.. image:: auto-UC02-data3.jpg
-
-Test definition data is stored in serialization files (Python pickles), while test execution data is stored in CSV
-files, for easier post-analysis.
-
-The module design is straightforward: functions and classes for managing data, for interfacing with recipients,
-for executing tests, and for interacting with the test user (choosing a Test Definition, showing the details
-of a Test Definition, starting the execution).
-
-.. image:: auto-UC02-module1.jpg
-
-This last diagram shows the test user menu functions:
-
-.. image:: auto-UC02-module2.jpg
-
-In future releases of Auto, testing environments such as FuncTest and Yardstick might be leveraged.
-
-Also, anonymized test results could be collected from users willing to share them, and aggregates could be
-maintained as benchmarks.
-
-
-
-
-
-
-
-
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. SPDX-License-Identifier CC-BY-4.0
+.. (c) optionally add copywriters name
+
+.. contents::
+   :depth: 3
+   :local:
+
+
+================================================================
+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.
+
+
+Description
+===========
+
+This use case illustrates VNF failure recovery time reduction with ONAP, thanks to its automated monitoring and management.
+It simulates an underlying problem (failure, stress, etc.: any adverse condition in the network that can impact VNFs),
+tracks a VNF, and measures the amount of time it takes for ONAP to restore the VNF functionality.
+
+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).
+
+
+Preconditions:
+
+#. hardware environment in which Edge cloud may be deployed
+#. Edge cloud has been deployed and is ready for operation
+#. ONAP has been deployed onto a cloud and is interfaced (i.e. provisioned for API access) to the Edge cloud
+#. Components of ONAP have been deployed on the Edge cloud as necessary for specific test objectives
+
+In future releases, Auto Use cases will also include the deployment of ONAP (if not already installed), the deployment
+of test VNFs (pre-existing VNFs in pre-existing ONAP can be used in the test as well), the configuration of ONAP for
+monitoring these VNFs (policies, CLAMP, DCAE), in addition to the test scripts which simulate a problem and measures recovery time.
+
+Different types of problems can be simulated, hence the identification of multiple test cases corresponding to this use case,
+as illustrated in this diagram:
+
+.. image:: auto-UC02-testcases.jpg
+
+Description of simulated problems/challenges:
+
+* Physical Infra Failure
+
+  * Migration upon host failure: Compute host power is interrupted, and affected workloads are migrated to other available hosts.
+  * Migration upon disk failure: Disk volumes are unmounted, and affected workloads are migrated to other available hosts.
+  * Migration upon link failure: Traffic on links is interrupted/corrupted, and affected workloads are migrated to other available hosts.
+  * Migration upon NIC failure: NIC ports are disabled by host commands, and affected workloads are migrated to other available hosts.
+
+* Virtual Infra Failure
+
+  * OpenStack compute host service fail: Core OpenStack service processes on compute hosts are terminated, and auto-restored, or affected workloads are migrated to other available hosts.
+  * SDNC service fail: Core SDNC service processes are terminated, and auto-restored.
+  * OVS fail: OVS bridges are disabled, and affected workloads are migrated to other available hosts.
+  * etc.
+
+* Security
+
+  * Host tampering: Host tampering is detected, the host is fenced, and affected workloads are migrated to other available hosts.
+  * Host intrusion: Host intrusion attempts are detected, an offending workload, device, or flow is identified and fenced, and as needed affected workloads are migrated to other available hosts.
+  * Network intrusion: Network intrusion attempts are detected, and an offending flow is identified and fenced.
+
+
+
+
+Test execution high-level description
+=====================================
+
+The following two MSCs (Message Sequence Charts) show the actors and high-level interactions.
+
+The first MSC shows the preparation activities (assuming the hardware, network, cloud, and ONAP have already been installed):
+onboarding and deployment of VNFs (via ONAP portal and modules in sequence: SDC, VID, SO), and ONAP configuration
+(policy framework, closed-loops in CLAMP, activation of DCAE).
+
+.. image:: auto-UC02-preparation.jpg
+
+The second MSC illustrates the pattern of all test cases for the Resiliency Improvements:
+* 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),
+
+In parallel, the MSC also shows the sequence of events happening in ONAP, thanks to its configuration to provide Service
+Assurance for the VNF.
+
+.. image:: auto-UC02-pattern.jpg
+
+
+Test design: data model, implementation modules
+===============================================
+
+The high-level design of classes shows the identification of several entities:
+* 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)
+
+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)
+
+.. image:: auto-UC02-data1.jpg
+
+The following diagram illustrates an implementation-independent design of the attributes of these entities:
+.. image:: auto-UC02-data2.jpg
+
+This next diagram shows the Python classes and attributes, as implemented by this Use Case (for all test cases):
+
+.. image:: auto-UC02-data3.jpg
+
+Test definition data is stored in serialization files (Python pickles), while test execution data is stored in CSV
+files, for easier post-analysis.
+
+The module design is straightforward: functions and classes for managing data, for interfacing with recipients,
+for executing tests, and for interacting with the test user (choosing a Test Definition, showing the details
+of a Test Definition, starting the execution).
+
+.. image:: auto-UC02-module1.jpg
+
+This last diagram shows the test user menu functions:
+
+.. image:: auto-UC02-module2.jpg
+
+In future releases of Auto, testing environments such as FuncTest and Yardstick might be leveraged.
+
+Also, anonymized test results could be collected from users willing to share them, and aggregates could be
+maintained as benchmarks.
+
diff --git a/docs/release/userguide/UC03-feature.userguide.rst b/docs/release/userguide/UC03-feature.userguide.rst
index d7d47d3..246b2c5 100644
--- a/docs/release/userguide/UC03-feature.userguide.rst
+++ b/docs/release/userguide/UC03-feature.userguide.rst
@@ -1,24 +1,92 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-.. SPDX-License-Identifier CC-BY-4.0
-.. (c) optionally add copywriters name
-
-.. contents::
-   :depth: 3
-   :local:
-
-OPNFV Auto Use Case 3: Enterprise vCPE description
-=============================================================
-.. Describe the specific features and how it is realised in the scenario in a brief manner
-.. to ensure the user understand the context for the user guide instructions to follow.
-
-OPNFV Auto Use Case 3: Enterprise vCPE capabilities and usage
-=============================================================
-.. Describe the specific capabilities and usage for <XYZ> feature.
-.. Provide enough information that a user will be able to operate the feature on a deployed scenario.
-
-<Feature and API usage guidelines and example>
-=============================================================
-.. Describe with examples how to use specific features, provide API examples and details required to
-.. operate the feature on the platform.
-
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. SPDX-License-Identifier CC-BY-4.0
+.. (c) optionally add copywriters name
+
+.. contents::
+   :depth: 3
+   :local:
+
+
+===========================================
+Auto User Guide: Use Case 3 Enterprise vCPE
+===========================================
+
+This document provides the user guide for Fraser release of Auto,
+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.
+
+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.
+
+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.
+
+DCAE executes directives coming from policies described in the Policy Framework, and closed-loop controls
+described in the CLAMP component.
+
+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.
+
+
+Preconditions:
+
+#. hardware environment in which Edge cloud may be deployed
+#. an Edge cloud has been deployed and is ready for operation
+#. enterprise edge devices, such as ThinCPE, have access to the Edge cloud with WAN interfaces
+#. ONAP components (MSO, SDN-C, APP-C and VNFM) have been deployed onto a cloud and are interfaced (i.e. provisioned for API access) to the Edge cloud
+
+
+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
+
+* 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.
+
+
+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
+
+  * 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
+  * 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.
+
+* 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
+=====================================
+
+<TBC>
+
diff --git a/docs/release/userguide/index.rst b/docs/release/userguide/index.rst
index d59be9f..ba44e0b 100644
--- a/docs/release/userguide/index.rst
+++ b/docs/release/userguide/index.rst
@@ -1,29 +1,27 @@
-.. _auto-userguide:
-
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-.. (c) <optionally add copywriters name>
-
-
-============================================
-OPNFV Auto (ONAP-Automated OPNFV) User Guide
-============================================
-
-.. The feature user guide should provide an OPNFV user with enough information to
-.. use the features provided by the feature project in the supported scenarios.
-.. This guide should walk a user through the usage of the features once a scenario
-.. has been deployed and is active according to the installation guide provided
-.. by the installer project.
-
-.. toctree::
-   :maxdepth: 1
-
-   UC01-feature.userguide.rst
-   UC02-feature.userguide.rst
-   UC03-feature.userguide.rst
-   
-.. The feature.userguide.rst files should contain the text for this document
-.. additional documents can be added to this directory and added in the right order
-.. to this file as a list below.
-
-
+.. _auto-userguide:
+
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) <optionally add copywriters name>
+
+
+============================================
+OPNFV Auto (ONAP-Automated OPNFV) User Guide
+============================================
+
+.. The feature user guide should provide an OPNFV user with enough information to
+.. use the features provided by the feature project in the supported scenarios.
+.. This guide should walk a user through the usage of the features once a scenario
+.. has been deployed and is active according to the installation guide provided
+.. by the installer project.
+
+.. toctree::
+   :maxdepth: 1
+
+   UC01-feature.userguide.rst
+   UC02-feature.userguide.rst
+   UC03-feature.userguide.rst
+
+.. The feature.userguide.rst files should contain the text for this document
+.. additional documents can be added to this directory and added in the right order
+.. to this file as a list below.