Merge "Update API documentation"
diff --git a/docs/development/devtools/distribution-s3p.rst b/docs/development/devtools/distribution-s3p.rst
new file mode 100644
index 0000000..f448690
--- /dev/null
+++ b/docs/development/devtools/distribution-s3p.rst
@@ -0,0 +1,272 @@
+.. This work is licensed under a
+.. Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+.. _distribution-s3p-label:
+
+Policy Distribution component
+#############################
+
+72 Hours Stability Test of Distribution
++++++++++++++++++++++++++++++++++++++++
+
+Introduction
+------------
+The 72 hour Stability Test for policy distribution has the goal of introducing a steady flow of transactions initiated from a test client server running JMeter. The policy distribution is configured with a special FileSystemReception plugin to monitor a local directory for newly added csar files to be processed by itself. The input CSAR will be added/removed by the test client(JMeter) and the result will be pulled from the backend(PAP and PolicyAPI) by the test client(JMeter).
+
+
+The test will be performed in an environment where Jmeter will continuously add/remove a test csar into the special directory where policy distribuion is monitoring and will then get the processed results from PAP and PolicyAPI to verify the successful deployment of the policy. The policy will then be undeployed and the test will loop continuously until 72 hours have elapsed.
+
+Setup details
+-------------
+
+The stability test is performed on VM's running in the OpenStack cloud environment in the ONAP integration lab. There are 2 separate VMs, one for running backend policy services which policy distribution needs, and the other is for policy distribution service itself and Jmeter.
+
+**OpenStack environment details**
+
+Version: Windriver Titanium
+
+**Policy Backend VM details(VM1)**
+
+OS:Ubuntu 18.04.4 LTS
+
+CPU: 8 core
+
+RAM: 32 GB
+
+HardDisk: 160 GB
+
+Docker version 19.03.8, build afacb8b7f0
+
+Java: openjdk version "11.0.7"
+
+**JMeter and Distribution VM details(VM2)**
+
+OS: Ubuntu 18.04.4 LTS
+
+CPU: 8 core
+
+RAM: 32 GB
+
+HardDisk: 160 GB
+
+Docker version 19.03.8, build afacb8b7f0
+
+Java: openjdk version "11.0.7"
+
+JMeter: 5.1.1
+
+Install Docker in VM1 & VM2
+---------------------------
+Make sure to execute below commands in VM1 & VM2 both.
+
+Update the ubuntu software installer
+
+.. code-block:: bash
+
+ $ apt-get update
+
+Install and check Java
+
+.. code-block:: bash
+
+ $ apt-get install -y openjdk-11-jdk
+ $ java -version
+
+Ensure that the Java version that is executing is OpenJDK version 11
+
+Install and check Docker
+
+.. code-block:: bash
+
+ $ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add - add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
+ $ apt-get update
+ $ apt-cache policy docker-ce
+ $ apt-get install -y docker-ce
+ $ systemctl status docker
+ $ docker ps
+
+Change the permissions of the Docker socket file
+
+.. code-block:: bash
+
+ $ sudo chmod 666 /var/run/docker.sock
+
+Check the status of the Docker service and ensure it is running correctly
+
+.. code-block:: bash
+
+ $ service docker status
+ $ docker ps
+
+Install Simulators, PAP, PolicyAPI and MariaDB in VM1
+-----------------------------------------------------
+
+To install all the components needed for Distribution, copy over the script and related files found within the simulatorsetup directory within $(REPOPATH)/distribution/testsuites/stability/src/main/resources
+
+Run setup_components.sh script to bring up the required docker containers
+
+After installation, ensure the following docker containers are up and running:
+
+.. code-block:: bash
+
+ CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
+ 11195b01300a nexus3.onap.org:10001/onap/policy-pap:2.2.2-SNAPSHOT "bash ./policy-pap.sh" 13 seconds ago Up 9 seconds 0.0.0.0:7000->6969/tcp policy-pap
+ 6266aa6b0137 nexus3.onap.org:10001/onap/policy-api:2.2.3-SNAPSHOT "bash ./policy-api.sh" 25 seconds ago Up 22 seconds 0.0.0.0:6969->6969/tcp policy-api
+ 6a85d155aa8a pdp/simulator:latest "bash pdp-sim.sh" About a minute ago Up About a minute pdp-simulator
+ 0b41992ccfd7 dmaap/simulator:latest "bash dmaap-sim.sh" About a minute ago Up About a minute 0.0.0.0:3904->3904/tcp message-router
+ 595056b2a094 mariadb:10.2.14 "docker-entrypoint.s…" About a minute ago Up About a minute 0.0.0.0:3306->3306/tcp mariadb
+
+Install Distribution in VM2
+---------------------------
+
+To install the Distribution service, copy over the script and related files found within the distributionsetup directory within $(REPOPATH)/distribution/testsuites/stability/src/main/resources
+
+Run setup_distribution.sh script to install the distribution service, provide the IP of VM1 as the arguments to the script.
+
+e.g
+.. code-block:: bash
+
+ $ ./setup_distribution.sh 10.2.0.24 10.2.0.24
+
+Ensure the distribution container is running.
+
+Install JMeter in VM2
+---------------------
+
+Download and install jMeter
+
+.. code-block:: bash
+
+ $ mkdir jMeter
+ $ cd jMeter
+ $ wget https://archive.apache.org/dist/jmeter/binaries/apache-jmeter-5.1.1.zip
+ $ unzip apache-jmeter-5.1.1.zip
+
+Install & configure visualVM in VM2
+-----------------------------------
+VisualVM needs to be installed in the virtual machine running Distrbution. It will be used to monitor CPU, Memory and GC for Distribution while the stability tests are running.
+
+.. code-block:: bash
+
+ $ sudo apt-get install visualVM
+
+Run these commands to configure permissions
+
+.. code-block:: bash
+
+ $ cd /usr/lib/jvm/java-11-openjdk-amd64/bin/
+ $ sudo touch visualvm.policy
+ $ sudo chmod 777 visualvm.policy
+
+ $ vi visualvm.policy
+
+ Add the following in visualvm.policy
+
+ grant codebase "file:/usr/lib/jvm/java-11-openjdk-amd64/lib/tools.jar" {
+ permission java.security.AllPermission;
+ };
+
+Run the following commands to start jstatd using port 1111
+
+.. code-block:: bash
+
+ $ cd /usr/lib/jvm/java-8-openjdk-amd64/bin/
+ $ ./jstatd -p 1111 -J-Djava.security.policy=visualvm.policy &
+
+Using the VM2 Desktop, run visualVM to connect to localhost:9090
+Run the command
+
+.. code-block:: bash
+
+ $ visualvm
+
+This will load up the visualVM GUI
+
+Connect to Distribution JMX Port.
+
+ 1. Right click on "Local" in the left panel of the screen and select "Add JMX Connection"
+ 2. Enter the Port 9090. this is the JMX port exposed by the dsitribution container
+ 3. Double click on the newly added nodes under "Local" to start monitoring CPU, Memory & GC.
+
+Example Screenshot
+
+Sample Screenshot of visualVM
+
+.. image:: images/distribution-s3p-vvm-sample.png
+
+Test Plan Setup
+---------------
+
+The 72 hours stability test will run the following steps sequentially in a single threaded loop.
+
+- **Delete Old CSAR** - Checks if CSAR already exists in the watched directory, if so it deletes it
+- **Add CSAR** - Adds CSAR to the directory that distribution is watching
+- **Get Healthcheck** - Ensures Healthcheck is returning 200 OK
+- **Get Statistics** - Ensures Statistics is returning 200 OK
+- **CheckPDPGroupQuery** - Checks that PDPGroupQuery contains the deployed policy
+- **CheckPolicyDeployed** - Checks that the policy is deployed
+- **Undeploy Policy** - Undeploys the policy
+- **Delete Policy** - Deletes the Policy for the next loop
+- **Check PDP Group for Deletion** - Ensures the policy has been removed and does not exist
+
+The following steps can be used to configure the parameters of the test plan.
+
+- **HTTP Authorization Manager** - used to store user/password authentication details.
+- **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**
+========== ===============================================
+ PAP_HOST IP Address or host name of PAP component
+ PAP_PORT Port number of PAP for making REST API calls
+ API_HOST IP Address or host name of API component
+ API_PORT Port number of API for making REST API calls
+ DURATION Duration of Test
+========== ===============================================
+
+Screenshot of Distribution stability test plan
+
+.. image:: images/distribution-s3p-testplan.png
+
+Running the Test Plan
+---------------------
+
+Copy the Test Plans folder onto VM2
+Edit the /tmp/ folder permissions to allow the Testplan to insert the CSAR into the /tmp/policydistribution/distributionmount/ folder
+
+.. code-block:: bash
+
+ $ sudo chmod a+trwx /tmp
+
+From the apache jMeter folder run the test, pointing it towards the stabiltiy.jmx file inside the testplans folder
+
+.. code-block:: bash
+
+ $ ./bin/jmeter -n -t /home/rossc/testplans/stability.jmx -Jduration=259200 -l testresults.jtl
+
+Test Results
+------------
+
+**Summary**
+
+Stability test plan was triggered for 72 hours.
+
+**Test Statistics**
+
+======================= ================= ================== ==================================
+**Total # of requests** **Success %** **Error %** **Average time taken per request**
+======================= ================= ================== ==================================
+194313 100 % 0 % 145 ms
+======================= ================= ================== ==================================
+
+**VisualVM Screenshot**
+
+.. image:: images/distribution-vvm-monitor.png
+.. image:: images/distribution-vvm-threads.png
+
+**JMeter Screenshot**
+
+.. image:: images/distribution-summary-report.png
+.. image:: images/distribution-results-tree.png
diff --git a/docs/development/devtools/images/distribution-results-tree.png b/docs/development/devtools/images/distribution-results-tree.png
new file mode 100644
index 0000000..324b6c1
--- /dev/null
+++ b/docs/development/devtools/images/distribution-results-tree.png
Binary files differ
diff --git a/docs/development/devtools/images/distribution-s3p-testplan.png b/docs/development/devtools/images/distribution-s3p-testplan.png
new file mode 100644
index 0000000..7a8559c
--- /dev/null
+++ b/docs/development/devtools/images/distribution-s3p-testplan.png
Binary files differ
diff --git a/docs/development/devtools/images/distribution-s3p-vvm-sample.png b/docs/development/devtools/images/distribution-s3p-vvm-sample.png
new file mode 100644
index 0000000..4b2aa66
--- /dev/null
+++ b/docs/development/devtools/images/distribution-s3p-vvm-sample.png
Binary files differ
diff --git a/docs/development/devtools/images/distribution-summary-report.png b/docs/development/devtools/images/distribution-summary-report.png
new file mode 100644
index 0000000..56e7595
--- /dev/null
+++ b/docs/development/devtools/images/distribution-summary-report.png
Binary files differ
diff --git a/docs/development/devtools/images/distribution-vvm-monitor.png b/docs/development/devtools/images/distribution-vvm-monitor.png
new file mode 100644
index 0000000..1afaa7d
--- /dev/null
+++ b/docs/development/devtools/images/distribution-vvm-monitor.png
Binary files differ
diff --git a/docs/development/devtools/images/distribution-vvm-threads.png b/docs/development/devtools/images/distribution-vvm-threads.png
new file mode 100644
index 0000000..d611d70
--- /dev/null
+++ b/docs/development/devtools/images/distribution-vvm-threads.png
Binary files differ
diff --git a/docs/development/devtools/images/xacml-s3p-jmeter.png b/docs/development/devtools/images/xacml-s3p-jmeter.png
new file mode 100644
index 0000000..8077757
--- /dev/null
+++ b/docs/development/devtools/images/xacml-s3p-jmeter.png
Binary files differ
diff --git a/docs/development/devtools/images/xacml-s3p-top.png b/docs/development/devtools/images/xacml-s3p-top.png
new file mode 100644
index 0000000..36dc403
--- /dev/null
+++ b/docs/development/devtools/images/xacml-s3p-top.png
Binary files differ
diff --git a/docs/development/devtools/images/xacml-s3p.PNG b/docs/development/devtools/images/xacml-s3p.PNG
deleted file mode 100644
index 9a1407c..0000000
--- a/docs/development/devtools/images/xacml-s3p.PNG
+++ /dev/null
Binary files differ
diff --git a/docs/development/devtools/xacml-s3p.rst b/docs/development/devtools/xacml-s3p.rst
index 5cca4af..7c29a45 100644
--- a/docs/development/devtools/xacml-s3p.rst
+++ b/docs/development/devtools/xacml-s3p.rst
@@ -8,59 +8,112 @@
:maxdepth: 2
Policy XACML PDP component
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+##########################
-Performance Test of Policy XACML PDP
-++++++++++++++++++++++++++++++++++++
-
-Summary
--------
-
-The Performance test was executed by performing requests against the Policy RESTful APIs residing on the XACML PDP installed in the windriver lab to get policy decisions for monitoring and guard policy types. This was running on a kubernetes host having the following configuration:
+Both the Performance and the Stability tests were executed by performing requests
+against the Policy RESTful APIs residing on the XACML PDP installed in the windriver
+lab. This was running on a kubernetes pod having the following configuration:
- 16GB RAM
- 8 VCPU
- 160GB Disk
-The performance test runs 10 simultaneous threads calling XACML PDP RESTful APIs to get decisions for Monitoring, Guard Min Max, and Guard Frequency Limiter policy types, with at duration of 6000 seconds. The test execution lasted approximately 50 minutes resulting in the following summary:
+Both tests were run via jmeter, which was installed on a separate VM so-as not
+to impact the performance of the XACML-PDP being tested.
-- 37,305 Healthcheck requests
-- 33,716 Statistics requests
-- 25,294 Monitoring decision requests
-- 25,288 Guard Min Max decisions
-- 25,286 Guard Frequency Limiter requests
+Performance Test of Policy XACML PDP
+************************************
-The average throughput was about 9.8 transactions per second. CPU and memory usage along with a screenshot of the JMeter Summary Report are provided in this document.
+Summary
+=======
-Results
--------
-
-**CPU Utilization**
-
-Total CPU used by the PDP was measured before and after the test, using "ps -l".
-
-=================== ================== ================ =================== =============== ==================
-**Intial CPU time** **Final CPU time** **Intial CPU %** **Intial Memory %** **Final CPU %** **Final Memory %**
-=================== ================== ================ =================== =============== ==================
-00:60:27 00:73:45 3.5% 4.0% 94.12.3% 4.0%
-=================== ================== ================ =================== =============== ==================
-
-**Memory Utilization**
+The Performance test was executed, and the result analyzed, via:
.. code-block:: bash
- Number of young garbage collections used during the test: 518
- Avg. Young garbage collection time: ~11.56ms per collection
- Total number of Full garbage collection: 32
- Avg. Full garbage collection time: ~315.06ms per collection
-
-
- S0C S1C S0U S1U EC EU OC OU MC MU CCSC CCSU YGC YGCT FGC FGCT GCT
-
- 16768.0 16768.0 0.0 5461.0 134144.0 71223.6 334692.0 138734.5 50008.0 48955.8 5760.0 5434.3 4043 45.793 32 10.082 55.875
-
- 16768.0 16768.0 0.0 4993.4 134144.0 66115.7 334692.0 252887.4 50264.0 49036.5 5760.0 5439.7 4561 53.686 32 10.082 63.768
+ jmeter -Jduration=1200 -Jusers=10 \
+ -Jxacml_ip=$ip -Jpap_ip=$ip -Japi_ip=$ip \
+ -Jxacml_port=31104 -Jpap_port=32425 -Japi_port=30709 \
+ -n -t perf.jmx
-**Jmeter Results Summary**
+ ./result.sh
-.. image:: images/xacml-s3p.PNG
+Note: the ports listed above correspond to port 6969 of the respective components.
+
+The performance test, perf.jmx, runs the following, all in parallel:
+
+- Healthcheck, 10 simultaneous threads
+- Statistics, 10 simultaneous threads
+- Decisions, 10 simultaneous threads, each running the following in sequence:
+
+ - Monitoring Decision
+ - Monitoring Decision, abbreviated
+ - Naming Decision
+ - Optimization Decision
+ - Default Guard Decision (always "Permit")
+ - Frequency Limiter Guard Decision
+ - Min/Max Guard Decision
+
+When the script starts up, it uses policy-api to create, and policy-pap to deploy,
+the policies that are needed by the test. It assumes that the "naming" policy has
+already been created and deployed. Once the test completes, it undeploys and deletes
+the policies that it previously created.
+
+Results
+=======
+
+The test was run for 20 minutes at a time, for different numbers of users (i.e.,
+threads), with the following results:
+
+.. csv-table::
+ :header: "Number of Users", "Throughput (requests/second)", "Average Latency (ms)"
+
+ 10, 6064, 4.1
+ 20, 6495, 7.2
+ 40, 6457, 12.2
+ 80, 5803, 21.3
+
+
+Stability Test of Policy XACML PDP
+************************************
+
+Summary
+=======
+
+The Stability test was run with the same pods/VMs and uses the same jmeter script as the
+performance test, except that it was run for 72 hours instead of 20 minutes. In
+addition, it was run in the background via "nohup", to prevent it from being interrupted:
+
+.. code-block:: bash
+
+ nohup jmeter -Jduration=259200 \
+ -Jxacml_ip=$ip -Jpap_ip=$ip -Japi_ip=$ip \
+ -Jxacml_port=31104 -Jpap_port=32425 -Japi_port=30709 \
+ -n -t perf.jmx &
+
+The memory and CPU usage can be monitored by running "top" on the xacml pod. By taking
+a snapshot before the test is started, and again when it completes, the total CPU used
+by all of the requests can be computed.
+
+Results
+=======
+
+The final output of the jmeter script is found in the nohup.out file:
+
+.. image:: images/xacml-s3p-jmeter.png
+
+The final memory and CPU from "top":
+
+.. image:: images/xacml-s3p-top.png
+
+The through-put reported by jmeter was 4849 requests/second, with 0 errors. In addition,
+the memory usage observed via "top" indicated that the virtual memory and resident set
+sizes remained virtually unchanged through-out the test.
+
+Unfortunately, the initial CPU usage was not recorded, so the CPU time reported in
+the "top" screen-shot includes XACML-PDP start-up time as well as requests that were
+executed before the stability test was started. Nevertheless, even including that, we find:
+
+.. code-block:: bash
+
+ 13,166 CPU minutes * 60sec/min * 1000ms/sec / 1,256,834,239 requests = 0.63ms/request
diff --git a/docs/index.rst b/docs/index.rst
index 59b3183..1bfdf30 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,5 +1,5 @@
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-
+.. _master_index:
.. _policy-framework-doc:
Policy Framework Architecture
diff --git a/integration/pom.xml b/integration/pom.xml
index 0af7539..d7496b0 100644
--- a/integration/pom.xml
+++ b/integration/pom.xml
@@ -27,7 +27,7 @@
<parent>
<groupId>org.onap.policy.parent</groupId>
<artifactId>policy-parent</artifactId>
- <version>3.1.3-SNAPSHOT</version>
+ <version>3.1.4-SNAPSHOT</version>
</parent>
<artifactId>integration</artifactId>
<packaging>pom</packaging>
diff --git a/pom.xml b/pom.xml
index 92aff3e..ce20c9f 100644
--- a/pom.xml
+++ b/pom.xml
@@ -28,7 +28,7 @@
</parent>
<groupId>org.onap.policy.parent</groupId>
<artifactId>policy-parent</artifactId>
- <version>3.1.3-SNAPSHOT</version>
+ <version>3.1.4-SNAPSHOT</version>
<packaging>pom</packaging>
<properties>
diff --git a/releases/3.1.3.yaml b/releases/3.1.3.yaml
new file mode 100644
index 0000000..e08078f
--- /dev/null
+++ b/releases/3.1.3.yaml
@@ -0,0 +1,4 @@
+distribution_type: 'maven'
+version: '3.1.3'
+project: 'policy-parent'
+log_dir: 'policy-parent-maven-stage-master/326/'
diff --git a/version.properties b/version.properties
index 9547659..7f9c490 100644
--- a/version.properties
+++ b/version.properties
@@ -4,7 +4,7 @@
major=3
minor=1
-patch=3
+patch=4
base_version=${major}.${minor}.${patch}
