Merge "Add docs for participant intermediary, simulator" into istanbul

4 files changed, 184 insertions, 37 deletions

diff --git a/docs/development/devtools/apex-s3p.rst b/docs/development/devtools/apex-s3p.rst
index bfed24e0..ce61e55e 100644
--- a/docs/development/devtools/apex-s3p.rst
+++ b/docs/development/devtools/apex-s3p.rst
@@ -102,7 +102,7 @@ The following steps can be used to configure the parameters of test plan.
  wait                Wait time if required after a request (in milliseconds)
  threads             Number of threads to run test cases in parallel
  threadsTimeOutInMs  Synchronization timer for threads running in parallel (in milliseconds)
-===================  ================================================================================
+===================  ===============================================================================
 
 Run Test
 --------
diff --git a/docs/development/devtools/clamp-cl-participant-protocol-smoke.rst b/docs/development/devtools/clamp-cl-participant-protocol-smoke.rst
new file mode 100644
index 00000000..98d7fcda
--- /dev/null
+++ b/docs/development/devtools/clamp-cl-participant-protocol-smoke.rst
@@ -0,0 +1,144 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. _clamp-gui-controlloop-smoke-tests:
+CLAMP Participant Protocol Smoke Tests
+---------------------------
+1. Introduction
+***************
+The CLAMP Control Loop Participant protocol is an asynchronous protocol that is used by the CLAMP runtime
+to coordinate life cycle management of Control Loop instances.
+This document will serve as a guide to do smoke tests on the different usecases that are involved when
+working with the Participant protocol and outline how they operate.
+It will also show a developer how to set up their environment for carrying out smoke tests on the participants.
+
+2. Setup Guide
+**************
+This section will show the developer how to set up their environment to start testing participants with some instruction on how to carry out the tests. There are a number of prerequisites. Note that this guide is written by a Linux user - although the majority of the steps show will be exactly the same in Windows or other systems.
+
+2.1 Prerequisites
+=================
+- Java 11
+- Docker
+- Maven 3
+- Git
+- Refer to this guide for basic environment setup `Setting up dev environment <https://wiki.onap.org/display/DW/Setting+Up+Your+Development+Environment>`_
+
+2.2 Setting up the components
+=============================
+- Controlloop runtime component docker image is started and running.
+- Participant docker images policy-clamp-cl-pf-ppnt, policy-clamp-cl-http-ppnt, policy-clamp-cl-k8s-ppnt are started and running.
+- Dmaap simulator for communication between components.
+- mariadb docker container for policy and controlloop database.
+- policy-api for communication between policy participant and policy-framework
+In this setup guide, we will be setting up all the components technically required for a working convenient dev environment. We will not be setting up all of the participants - we will setup only the policy participant as an example.
+
+2.2.1 MariaDB Setup
+===================
+We will be using Docker to run our mariadb instance. It will have a total of two databases running in it.
+- controlloop: the runtime-controlloop db
+- policyadmin: the policy-api db
+
+3. Running Tests of protocol dialogues
+**************************************
+lloop type definitions and common property values for participant types
+In this section, we will run through the functionalities mentioned at the start of this document is section 1. Each functionality will be tested and we will confirm that they were carried out successfully. There is a tosca service template that can be used for this test
+:download:`Tosca Service Template <tosca/tosca-for-gui-smoke-tests.yaml>`
+
+3.1 Participant Registration
+============================
+Action: Bring up the participant
+Test result:
+- Observe PARTICIPANT_REGISTER going from participant to runtime
+- Observe PARTICIPANT_REGISTER_ACK going from runtime to participant
+- Observe PARTICIPANT_UPDATE going from runtime to participant
+
+3.2 Participant Deregistration
+==============================
+Action: Bring down the participant
+Test result:
+- Observe PARTICIPANT_DEREGISTER going from participant to runtime
+- Observe PARTICIPANT_DEREGISTER_ACK going from runtime to participant
+
+3.3 Participant Priming
+=======================
+When a control loop is primed, the portion of the Control Loop Type Definition and Common Property values for the participants
+of each participant type mentioned in the Control Loop Definition are sent to the participants.
+Action: Invoke a REST API to prime controlloop type definitions and set values of common properties
+Test result:
+- Observe PARTICIPANT_UPDATE going from runtime to participant with controlloop type definitions and common property values for participant types
+- Observe that the controlloop type definitions and common property values for participant types are stored on ParticipantHandler
+- Observe PARTICIPANT_UPDATE_ACK going from runtime to participant
+
+3.4 Participant DePriming
+=========================
+When a control loop is de-primed, the portion of the Control Loop Type Definition and Common Property values for the participants
+of each participant type mentioned in the Control Loop Definition are deleted on participants.
+Action: Invoke a REST API to deprime controlloop type definitions
+Test result:
+- If controlloop instances exist in runtime database, return a response for the REST API with error response saying "Cannot decommission controlloop type definition"
+- If no controlloop instances exist in runtime database, Observe PARTICIPANT_UPDATE going from runtime to participant with definitions as null
+- Observe that the controlloop type definitions and common property values for participant types are removed on ParticipantHandler
+- Observe PARTICIPANT_UPDATE_ACK going from runtime to participant
+
+3.5 Control Loop Update
+=======================
+Control Loop Update handles creation, change, and deletion of control loops on participants.
+Action: Trigger controlloop instantiation from GUI
+Test result:
+- Observe CONTROL_LOOP_UPDATE going from runtime to participant
+- Observe that the controlloop type instances and respective property values for participant types are stored on ControlLoopHandler
+- Observe that the controlloop state is UNINITIALISED
+- Observe CONTROL_LOOP_UPDATE_ACK going from participant to runtime
+
+3.6 Control Loop state change to PASSIVE
+========================================
+Control Loop Update handles creation, change, and deletion of control loops on participants.
+Action: Change state of the controlloop to PASSIVE
+Test result:
+- Observe CONTROL_LOOP_STATE_CHANGE going from runtime to participant
+- Observe that the ControlLoopElements state is PASSIVE
+- Observe that the controlloop state is PASSIVE
+- Observe CONTROL_LOOP_STATE_CHANGE_ACK going from participant to runtime
+
+3.7 Control Loop state change to RUNNING
+========================================
+Control Loop Update handles creation, change, and deletion of control loops on participants.
+Action: Change state of the controlloop to RUNNING
+Test result:
+- Observe CONTROL_LOOP_STATE_CHANGE going from runtime to participant
+- Observe that the ControlLoopElements state is RUNNING
+- Observe that the controlloop state is RUNNING
+- Observe CONTROL_LOOP_STATE_CHANGE_ACK going from participant to runtime
+
+3.8 Control Loop state change to PASSIVE
+========================================
+Control Loop Update handles creation, change, and deletion of control loops on participants.
+Action: Change state of the controlloop to PASSIVE
+Test result:
+- Observe CONTROL_LOOP_STATE_CHANGE going from runtime to participant
+- Observe that the ControlLoopElements state is PASSIVE
+- Observe that the controlloop state is PASSIVE
+- Observe CONTROL_LOOP_STATE_CHANGE_ACK going from participant to runtime
+
+3.9 Control Loop state change to UNINITIALISED
+==============================================
+Control Loop Update handles creation, change, and deletion of control loops on participants.
+Action: Change state of the controlloop to UNINITIALISED
+Test result:
+- Observe CONTROL_LOOP_STATE_CHANGE going from runtime to participant
+- Observe that the ControlLoopElements state is UNINITIALISED
+- Observe that the controlloop state is UNINITIALISED
+- Observe that the ControlLoopElements undeploy the instances from respective frameworks
+- Observe that the control loop instances are removed from participants
+- Observe CONTROL_LOOP_STATE_CHANGE_ACK going from participant to runtime
+
+3.10 Control Loop monitoring and reporting
+==========================================
+This dialogue is used as a heartbeat mechanism for participants, to monitor the status of Control Loop Elements, and to gather statistics on control loops. The ParticipantStatus message is sent periodically by each participant. The reporting interval for sending the message is configurable
+Action: Bring up participant
+Test result:
+- Observe that PARTICIPANT_STATUS message is sent from participants to runtime in a regular interval
+- Trigger a PARTICIPANT_STATUS_REQ from runtime and observe a PARTICIPANT_STATUS message with tosca definitions of control loop type definitions sent
+from all the participants to runtime
+
+This concluded the required smoke tests
+
diff --git a/docs/development/devtools/clamp-s3p.rst b/docs/development/devtools/clamp-s3p.rst
index e01848da..08f0953c 100644
--- a/docs/development/devtools/clamp-s3p.rst
+++ b/docs/development/devtools/clamp-s3p.rst
@@ -48,14 +48,14 @@ The following steps can be used to configure the parameters of test plan.
 - **HTTP Header Manager** - used to store headers which will be used for making HTTP requests.
 - **User Defined Variables** -  used to store following user defined parameters.
 
-===========   ===================================================================
- **Name**      **Description**
-===========   ===================================================================
- RUNTIME_HOST IP Address or host name of controlloop runtime component
- RUNTIME_PORT Port number of controlloop runtime components for making REST API calls
- POLICY_PARTICIPANT_HOST IP Address or host name of policy participant
- POLICY_PARTICIPANT_HOST_PORT Port number of policy participant
-===========   ===================================================================
+=============================  ========================================================================
+ **Name**                      **Description**
+=============================  ========================================================================
+ RUNTIME_HOST                  IP Address or host name of controlloop runtime component
+ RUNTIME_PORT                  Port number of controlloop runtime components for making REST API calls
+ POLICY_PARTICIPANT_HOST       IP Address or host name of policy participant
+ POLICY_PARTICIPANT_HOST_PORT  Port number of policy participant
+=============================  ========================================================================
 
 The test was run in the background via "nohup", to prevent it from being interrupted:
 
@@ -88,17 +88,17 @@ Stability test plan was triggered for 72 hours.
 
 **Controloop component Setup**
 
-================ =======================                            ==================                              ==========================
-**CONTAINER ID**  **IMAGE**                                             **PORTS**                                     **NAMES**
-================ =======================  ==================        ==================================              ==========================
- a9cb0cd103cf   onap/policy-clamp-cl-runtime:latest                     6969/tcp                                      policy-clamp-cl-runtime
- 886e572b8438   onap/policy-clamp-cl-pf-ppnt:latest                     6973/tcp                                      policy-clamp-cl-pf-ppnt
- 035707b1b95f   nexus3.onap.org:10001/onap/policy-api:latest            6969/tcp                                      policy-api
- d34204f95ff3   onap/policy-clamp-cl-http-ppnt:latest                   6971/tcp                                      policy-clamp-cl-http-ppnt
- 4470e608c9a8   onap/policy-clamp-cl-k8s-ppnt:latest                    6972/tcp, 8083/tcp                            policy-clamp-cl-k8s-ppnt
- 62229d46b79c   nexus3.onap.org:10001/onap/policy-models-simulator:latest 3905/tcp, 6666/tcp, 6668-6670/tcp, 6680/tcp simulator
- efaf0ca5e1f0   nexus3.onap.org:10001/mariadb:10.5.8                    3306/tcp                                      mariadb
-=======================  =================  ==================  ======================================              ===========================
+================  =========================================================  ===========================================  =========================
+**CONTAINER ID**  **IMAGE**                                                  **PORTS**                                    **NAMES**
+================  =========================================================  ===========================================  =========================
+ a9cb0cd103cf     onap/policy-clamp-cl-runtime:latest                        6969/tcp                                     policy-clamp-cl-runtime
+ 886e572b8438     onap/policy-clamp-cl-pf-ppnt:latest                        6973/tcp                                     policy-clamp-cl-pf-ppnt
+ 035707b1b95f     nexus3.onap.org:10001/onap/policy-api:latest               6969/tcp                                     policy-api
+ d34204f95ff3     onap/policy-clamp-cl-http-ppnt:latest                      6971/tcp                                     policy-clamp-cl-http-ppnt
+ 4470e608c9a8     onap/policy-clamp-cl-k8s-ppnt:latest                       6972/tcp, 8083/tcp                           policy-clamp-cl-k8s-ppnt
+ 62229d46b79c     nexus3.onap.org:10001/onap/policy-models-simulator:latest  3905/tcp, 6666/tcp, 6668-6670/tcp, 6680/tcp  simulator
+ efaf0ca5e1f0     nexus3.onap.org:10001/mariadb:10.5.8                       3306/tcp                                     mariadb
+================  =========================================================  ===========================================  =========================
 
 .. Note::
 
@@ -108,11 +108,11 @@ Stability test plan was triggered for 72 hours.
 
 **JMeter Screenshot**
 
-.. image:: clamp-s3p-results/controlloop_stability_jmeter.PNG
+.. image:: clamp-s3p-results/controlloop_stability_jmeter.png
 
 **JMeter Screenshot**
 
-.. image:: clamp-s3p-results/controlloop_stability_table.PNG
+.. image:: clamp-s3p-results/controlloop_stability_table.png
 
 **Memory and CPU usage**
 
@@ -120,11 +120,11 @@ The memory and CPU usage can be monitored by running "docker stats" command. A s
 
 Memory and CPU usage before test execution:
 
-.. image:: clamp-s3p-results/Stability_before_stats.PNG
+.. image:: clamp-s3p-results/Stability_before_stats.png
 
 Memory and CPU usage after test execution:
 
-.. image:: clamp-s3p-results/Stability_after_stats.PNG
+.. image:: clamp-s3p-results/Stability_after_stats.png
 
 
 Performance Test of Controlloop components
@@ -180,18 +180,18 @@ Test results are shown as below.
 
 **Controloop component Setup**
 
-================ =======================                            ==================                              ==========================
-**CONTAINER ID**  **IMAGE**                                             **PORTS**                                     **NAMES**
-================ =======================  ==================        ==================================              ==========================
- a9cb0cd103cf   onap/policy-clamp-cl-runtime:latest                     6969/tcp                                      policy-clamp-cl-runtime
- 886e572b8438   onap/policy-clamp-cl-pf-ppnt:latest                     6973/tcp                                      policy-clamp-cl-pf-ppnt
- 035707b1b95f   nexus3.onap.org:10001/onap/policy-api:latest            6969/tcp                                      policy-api
- d34204f95ff3   onap/policy-clamp-cl-http-ppnt:latest                   6971/tcp                                      policy-clamp-cl-http-ppnt
- 4470e608c9a8   onap/policy-clamp-cl-k8s-ppnt:latest                    6972/tcp, 8083/tcp                            policy-clamp-cl-k8s-ppnt
- 62229d46b79c   nexus3.onap.org:10001/onap/policy-models-simulator:latest 3905/tcp, 6666/tcp, 6668-6670/tcp, 6680/tcp simulator
- efaf0ca5e1f0   nexus3.onap.org:10001/mariadb:10.5.8                    3306/tcp                                      mariadb
-=======================  =================  ==================  ======================================              ===========================
+================  =========================================================  ===========================================  =========================
+**CONTAINER ID**  **IMAGE**                                                  **PORTS**                                    **NAMES**
+================  =========================================================  ===========================================  =========================
+ a9cb0cd103cf     onap/policy-clamp-cl-runtime:latest                        6969/tcp                                     policy-clamp-cl-runtime
+ 886e572b8438     onap/policy-clamp-cl-pf-ppnt:latest                        6973/tcp                                     policy-clamp-cl-pf-ppnt
+ 035707b1b95f     nexus3.onap.org:10001/onap/policy-api:latest               6969/tcp                                     policy-api
+ d34204f95ff3     onap/policy-clamp-cl-http-ppnt:latest                      6971/tcp                                     policy-clamp-cl-http-ppnt
+ 4470e608c9a8     onap/policy-clamp-cl-k8s-ppnt:latest                       6972/tcp, 8083/tcp                           policy-clamp-cl-k8s-ppnt
+ 62229d46b79c     nexus3.onap.org:10001/onap/policy-models-simulator:latest  3905/tcp, 6666/tcp, 6668-6670/tcp, 6680/tcp  simulator
+ efaf0ca5e1f0     nexus3.onap.org:10001/mariadb:10.5.8                       3306/tcp                                     mariadb
+================  =========================================================  ===========================================  =========================
 
 **JMeter Screenshot**
 
-.. image:: clamp-s3p-results/cl-s3p-performance-result-jmeter.PNG
+.. image:: clamp-s3p-results/cl-s3p-performance-result-jmeter.png
diff --git a/docs/development/devtools/devtools.rst b/docs/development/devtools/devtools.rst
index 5d6c94c9..dff8819d 100644
--- a/docs/development/devtools/devtools.rst
+++ b/docs/development/devtools/devtools.rst
@@ -303,6 +303,9 @@ familiar with the Policy Framework components and test any local changes.
 ..
    clamp-smoke.rst
 
+..
+   clamp-cl-participant-protocol-smoke.rst
+
 Running the Stability/Performance Tests
 ***************************************
 
@@ -321,7 +324,7 @@ familiar with the Policy Framework components and test any local changes.
    clamp-s3p.rst
 
 Running the Pairwise Tests
-***********************
+**************************
 
 The following links contain instructions on how to run the pairwise tests. These may be helpful to developers check that
 the Policy Framework works in a full ONAP deployment.