Author: Saravanan A <saravanan.a75@wipro.com>

Added documentation for SON Handler MS
Added Installation Steps, Configurations, Troubleshooting and Logging
Added prerequisites and changed file names

Change-Id: I35de88ae3ac3caa2d204717f445f7565209cd6e3
Issue-ID: DCAEGEN2-1116
Signed-off-by: Saravanan A <saravanan.a75@wipro.com>

7 files changed, 210 insertions, 0 deletions

diff --git a/docs/sections/services/son-handler/dcae_new.jpg b/docs/sections/services/son-handler/dcae_new.jpg
new file mode 100644
index 00000000..be619ed7
--- /dev/null
+++ b/docs/sections/services/son-handler/dcae_new.jpg
diff --git a/docs/sections/services/son-handler/flowdiagram.jpg b/docs/sections/services/son-handler/flowdiagram.jpg
new file mode 100644
index 00000000..4e660892
--- /dev/null
+++ b/docs/sections/services/son-handler/flowdiagram.jpg
diff --git a/docs/sections/services/son-handler/index.rst b/docs/sections/services/son-handler/index.rst
new file mode 100644
index 00000000..cd3bb469
--- /dev/null
+++ b/docs/sections/services/son-handler/index.rst
@@ -0,0 +1,31 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+
+SON-Handler MS
+==============
+
+.. Add or remove sections below as appropriate for the platform component.
+
+
+**SON-Handler MS** is introduced in ONAP for implementing the pre-processing and co-ordination actions of various RAN SON use cases.
+As of now PCI optimization and ANR updates are handled in Dublin release.
+OOF, SON Handler MS, DCAE, VES Collector, Policy, DMaaP and SDNR are involved in this use case implementation.
+
+.. image:: flowdiagram.jpg
+
+SON-Handler MS overview and functions
+-------------------------------------
+
+.. toctree::
+    :maxdepth: 1
+
+    son_handler_ms
+
+SON-Handler MS Installation Steps, Configurations, Troubleshooting Tips and Logging
+-----------------------------------------------------------------------------------
+
+.. toctree::
+    :maxdepth: 1
+
+    son_handler_ms_addl
diff --git a/docs/sections/services/son-handler/son_handler.jpg b/docs/sections/services/son-handler/son_handler.jpg
new file mode 100644
index 00000000..355af4a7
--- /dev/null
+++ b/docs/sections/services/son-handler/son_handler.jpg
diff --git a/docs/sections/services/son-handler/son_handler_installation.rst b/docs/sections/services/son-handler/son_handler_installation.rst
new file mode 100644
index 00000000..afb70a69
--- /dev/null
+++ b/docs/sections/services/son-handler/son_handler_installation.rst
@@ -0,0 +1,110 @@
+**** SON Handler ****
+
+** Instalation Steps **
+
+SON handler microservice can be deployed using cloudify blueprint using bootstrap container of an existing DCAE deployment
+
+Deployment Prerequisites:
+=========================
+
+	*SON-Handler service requires DMAAP and Policy components to be functional.
+
+	*SON-hadler service requires  the following dmaap topics to be present in the running DMAAP instance :
+
+		1.PCI-NOTIF-TOPIC-NGHBR-LIST-CHANGE-INFO
+
+		2.unauthenticated.SEC_FAULT_OUTPUT
+
+		3.unauthenticated.SEC_MEASUREMENT_OUTPUT
+
+		4.DCAE_CL_RSP
+
+	*Policy model required for SON-handler service should be created and pushed to policy component.Steps for creating and pushing the policy model:
+		1.Login to PDP container and execute
+			kubectl exec -ti --namespace onap policy-pdp-0 bash
+		2.Create policy model
+			curl -k -v --silent -X PUT --header 'Content-Type: application/json' --header 'Accept: text/plain' --header 'ClientAuth: cHl0aG9uOnRlc3Q=' --header 'Authorization: Basic dGVzdHBkcDphbHBoYTEyMw==' --header 'Environment: TEST' -d '{
+  "policyName": "com.PCIMS_CONFIG_POLICY",
+  "configBody": "{ \"PCI_NEIGHBOR_CHANGE_CLUSTER_TIMEOUT_IN_SECS\":60, \"PCI_MODCONFIG_POLICY_NAME\":\"ControlLoop-vPCI-fb41f388-a5f2-11e8-98d0-529269fb1459\", \"PCI_OPTMIZATION_ALGO_CATEGORY_IN_OOF\":\"OOF-PCI-OPTIMIZATION\", \"PCI_SDNR_TARGET_NAME\":\"SDNR\" }",
+  "policyType": "Config",
+  "attributes" : { "matching" : { "key1" : "value1" } },
+  "policyConfigType": "Base",
+  "onapName": "DCAE",
+  "configName": "PCIMS_CONFIG_POLICY",
+  "configBodyType": "JSON"
+}' 'https://pdp:8081/pdp/api/createPolicy'
+
+		3.Push policy model
+			curl -k -v --silent -X PUT --header 'Content-Type: application/json' --header 'Accept: text/plain' --header 'ClientAuth: cHl0aG9uOnRlc3Q=' --header 'Authorization: Basic dGVzdHBkcDphbHBoYTEyMw==' --header 'Environment: TEST' -d '{
+  "policyName": "com.PCIMS_CONFIG_POLICY",
+  "policyType": "Base"
+}' 'https://pdp:8081/pdp/api/pushPolicy'
+
+		4.Verify config policy is present
+
+			curl -k -v --silent -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'ClientAuth: cHl0aG9uOnRlc3Q=' --header 'Authorization: Basic dGVzdHBkcDphbHBoYTEyMw==' --header 'Environment: TEST' -d '{ "configName": "PCIMS_CONFIG_POLICY",    "policyName": "com.Config_PCIMS_CONFIG_POLICY1*",    "requestID":"e65cc45a-9efb-11e8-98d0-529269ffa459"  }' 'https://pdp:8081/pdp/api/getConfig'	
+
+Deployment steps:
+=================
+* Login to the bootstrap container
+        kubectl exec -ti --namespace onap <bootstrap pod name> bash
+* Copy the blueprints and inputs file to the bootstrap container. The blueprint and a sample input file can be found under dpo/blueprints directory of son-hanler project. (https://gerrit.onap.org/r/dcaegen2/services/son-handler)
+* Deploy the microservice into the cloudify using the following command
+        cfy install -d sonhms -b sonhms -i <inputs file path> <blueprint file path>
+* Deployment status of the microservice can be found from kubernetes pods status (MS will be deployed as a k8s pod in the kubernetes environment under the same namespace as the DCAE environment).
+        kubectl get pods --namespace onap
+* To uninstall the microservice
+        cfy uninstall sonhms
+* To delete the blueprint from the cloudify instance
+        cfy blueprints delete sonhms
+
+
+** Application Configurations **
+
+Streams_subscribes                Dmaap topics that the MS will consume messages
+
+Streams_publishes                 Dmaap topics that the MS will publish messages
+
+postgres.host                     Host where the postgres database is running
+
+postgres.port                     Host where the postgres database is running
+
+postgres.username                 Postgres username
+
+postgres.password                 Postgres password
+
+sonhandler.pollingInterval        Polling Interval for consuming dmaap messages
+
+sonhandler.pollingTimeout         Polling timeout for consuming dmaap messages
+
+sonhandler.numSolutions           Number for solutions for OOF optimization
+
+sonhandler.minCollision           Minimum collision criteria to trigger OOF
+
+sonhandler.minConfusion           Minimum confusion criteria to trigger OOF
+
+sonhandler.maximumClusters        Maximum number of clusters MS can process
+
+sonhandler.badThreshold           Bad threshold for Handover success rate
+
+sonhandler.poorThreshold          Poor threshold for Handover success rate
+
+sonhandler.namespace              Namespace where MS is going to be deployed
+
+sonhandler.sourceId               Source ID of the Microservice (Required for Sending request to OOF)
+
+sonhandler.dmaap.server           Location of message routers
+
+sonhandler.bufferTime             Buffer time for MS to wait for more notifications when the optimization criteria is not met
+
+sonhandler.cg                     Consumer group for the MS to consume message from dmaap
+
+sonhandler.cid                    Consumer ID for the MS to consume message from dmaap
+
+sonhandler.configDbService        Location of the config DB (protocol, host & port)
+ 
+sonhandler.oof.service            Location of OOF (protocol, host & port)
+
+sonhandler.optimizers             Optimizer to trigger in OOF
+
+
diff --git a/docs/sections/services/son-handler/son_handler_overview.rst b/docs/sections/services/son-handler/son_handler_overview.rst
new file mode 100644
index 00000000..23abbaa7
--- /dev/null
+++ b/docs/sections/services/son-handler/son_handler_overview.rst
@@ -0,0 +1,52 @@
+.. This work is licensed under a Creative Commons Attribution 4.0

+   International License. http://creativecommons.org/licenses/by/4.0

+   

+.. _docs_SON_Handler_MS:

+

+Architecture

+------------

+The architecture below depicts the SON-Handler MS as a part of DCAE. Only the relevant interactions and components are shown.

+

+.. image:: ./dcae_new.jpg

+

+The internal architecture of SON-Handler MS is shown below.

+

+.. image:: ./son_handler.jpg

+

+Description

+~~~~~~~~~~~

+The SON-Handler MS has a REST interface towards OOF as well as DMaaP interface towards Policy, VES-Collector and SDN-R. It has a database and core logic.

+

+Core logic

+~~~~~~~~~~

+The core logic is implemented as 3 threads - main thread, child thread(s) for handling neighbor-list updates and collision/confusion alarms from the RAN (via SDN-R), and a separate child for handling handover measurements (PM) inputs from the RAN (via VES-Collector). The Main Thread is responsible for spawning and terminating the Child Threads. The core logic is responsible for:

+(a) Performing all the pre-processing that is required before triggering OOF for PCI as well as PCI/ANR joint-optimization

+(b) Autonomously taking actions for ANR updates

+(c) Preparing the message contents required by SDN-R to re-configure the RAN nodes with PCI/ANR updates

+

+The logic may not be 100% fool-proof (i.e., cover all possible scenarios and boundary-counditions as in real field deployments), as well as the most efficient one. An attempt has been made to balance the usefulness for a PoC versus the complexity of handling all possible scenarios. It is intended to provide a good base for the community/users to enhance it further as required.

+

+The details of the state machines of all the threads in the core logic are available in https://wiki.onap.org/pages/viewpage.action?pageId=56131985.

+

+Database

+~~~~~~~~

+This is a PostgreSQL DB, and is intended to persist information such as the following:

+- PCI-Handler MS Config information (e.g., thresholds, timer values, OOF algorithm name, etc.)

+- Pre-processing results and other related information (e.g., neighbor list)

+- Buffered notifications (i.e., notifications not yet processed at all)

+- State information

+- Association between PNF-name and CellId

+- PM/FM data

+- Etc.

+

+DMaaP Client

+~~~~~~~~~~~~

+This is responsible for registering with the DMaaP client for the DMaaP notifications from SDN-R and VES-Collector, and to Policy.

+

+Deployment aspects

+------------------

+The SON-Handler MS will be deployed on DCAE using the mechanism described in "Option 3 - On-Demand deployment through DCAE-Controller cli" at https://wiki.onap.org/display/DW/Dublin+Deployment+Strategy.

+

+Known Issues and Resolutions

+----------------------------

+The scope and scenarios addressed are documented in the SON use case page for Dublin - https://wiki.onap.org/display/DW/OOF-PCI+Use+Case+-+Dublin+Release+-+ONAP+based+SON+for+PCI+and+ANR.
\ No newline at end of file
diff --git a/docs/sections/services/son-handler/son_handler_troubleshooting.rst b/docs/sections/services/son-handler/son_handler_troubleshooting.rst
new file mode 100644
index 00000000..6fcf5149
--- /dev/null
+++ b/docs/sections/services/son-handler/son_handler_troubleshooting.rst
@@ -0,0 +1,17 @@
+** Troubleshooting steps **
+
+1. Microservice stops and restarts during startup
+
+    Possible reasons & Solutions: 
+     1. Microservice is not registered with the consul 
+            - Check the consul if the microservice is registered with it and the MS is able to fetch the app config from the CBS. Check if CBS and consul are deployed properly and try to redeploy the MS
+     2. DMAAP topics are not created 
+            - Check the message router if the neccessary dmaap topics are present in the list of topics. Create the topics if not present.
+              List of topics can be queried from message router using the url "http://<host>:<port>/topics"
+
+
+** Logging **
+
+1. Logs can be found either from kubernetes UI or from kubectl. Since, the MS is deployed as a pod in the kubernetes, you can check the logs by using the command
+        kubectl logs <pod-name> --namespace onap
+