Add PMSH documentation

*Add base PM Subscription Handler documentation

Issue-ID: DCAEGEN2-1837
Change-Id: I17bb587ef56704e0a122d65c7d29a2998489ce9c
Signed-off-by: dfarrelly <david.farrelly@est.tech>

8 files changed, 359 insertions, 0 deletions

diff --git a/docs/sections/services/pm-subscription-handler/configuration.rst b/docs/sections/services/pm-subscription-handler/configuration.rst
new file mode 100644
index 00000000..876d9085
--- /dev/null
+++ b/docs/sections/services/pm-subscription-handler/configuration.rst
@@ -0,0 +1,203 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+.. Configuration:
+
+Configuration
+=============
+
+The PMSH is configured and deployed via CLAMP.
+
+Application specific configuration
+""""""""""""""""""""""""""""""""""
+
+The application config is the basic information that PMSH needs to run. The following parameters are required, they are
+specified in the CLAMP deployment GUI.
+
++------------------+--------------------------------------------------------------------------+---------+----------+-------------------------------------------------------------------------------+
+| Field            | Description                                                              | Type    | Required | Default                                                                       |
++==================+==========================================================================+=========+==========+===============================================================================+
+| tag_version      | Docker image to be used.                                                 | string  | True     | nexus3.onap.org:10001/onap/org.onap.dcaegen2.services.pm-subscription-handler |
++------------------+--------------------------------------------------------------------------+---------+----------+-------------------------------------------------------------------------------+
+| replicas         | Number of instances.                                                     | integer | True     | 1                                                                             |
++------------------+--------------------------------------------------------------------------+---------+----------+-------------------------------------------------------------------------------+
+| subscriber_topic | The topic that PMSH will subscribe to.                                   | string  | True     | AAI-EVENT                                                                     |
++------------------+--------------------------------------------------------------------------+---------+----------+-------------------------------------------------------------------------------+
+| publisher_topic  | The topic that PMSH will publish to, and which policy will subscribe to. | string  | True     | org.onap.dmaap.mr.PM_SUBSCRIPTIONS                                            |
++------------------+--------------------------------------------------------------------------+---------+----------+-------------------------------------------------------------------------------+
+| client_role      | Client role to request secure access to topic.                           | string  | True     |                                                                               |
++------------------+--------------------------------------------------------------------------+---------+----------+-------------------------------------------------------------------------------+
+| client_id        | Client id for given AAF client.                                          | string  | True     | dcae@dcae.onap.org                                                            |
++------------------+--------------------------------------------------------------------------+---------+----------+-------------------------------------------------------------------------------+
+| client_password  | Password for AAF client provided as client_id.                           | string  | True     |                                                                               |
++------------------+--------------------------------------------------------------------------+---------+----------+-------------------------------------------------------------------------------+
+
+Subscription configuraton
+"""""""""""""""""""""""""
+
+The subscription is configured within the monitoring policy in CLAMP. The subscription model schema is as follows:
+
+**subscription**
+
+::
+
+         {
+           "subscription": {
+             "subscriptionName": "someExtraPM-AllKista-gNB-R2B",
+             "administrativeState": "UNLOCKED",
+             "fileBasedGP": 15,
+             "fileLocation": "/pm/pm.xml",
+             "nfTypeModelInvariantId": "2829292",
+             "nfFilter": {
+               "swVersions": [
+                 "1.0.0",
+                 "1.0.1"
+               ],
+               "nfNames": [
+                 "ABC",
+                 "DEF",
+                 "foo.*"
+               ]
+             },
+             "measurementGroup": {
+               "measurementTypes": [
+                 {
+                   "measurementType": "EutranCell.*"
+                 },
+                 {
+                   "measurementType": "EutranCellRelation.pmCounter1"
+                 },
+                 {
+                   "measurementType": "EutranCellRelation.pmCounter2"
+                 }
+               ],
+               "managedObjectDNsBasic": [
+                 {
+                   "DN": "ManagedElement=1,ENodeBFunction=1,EUtranCell=CityCenter1"
+                 },
+                 {
+                   "DN": "ManagedElement=1,ENodeBFunction=1,EUtranCell=CityCenter1, EUtranCellRelation=CityCenter2"
+                 },
+                 {
+                   "DN": "ManagedElement=1,ENodeBFunction=1,EUtranCell=CityCenter1, EUtranCellRelation=CityCenter3"
+                 }
+               ]
+             }
+           }
+         }
+
++------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------+----------+--------+
+| Field                  | Description                                                                                                                                                                | Type | Required | Values |
++------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------+----------+--------+
+| subscriptionName       | Name of the subscription                                                                                                                                                   |      |          |        |
++------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------+----------+--------+
+| administrativeState    | Setting a subscription to UNLOCKED will apply the subscription to the NF instances immediately. If it is set to LOCKED, it will not be applied until it is later unlocked. |      |          |        |
++------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------+----------+--------+
+| fileBasedGP            | The frequency at which measurements are produced.                                                                                                                          |      |          |        |
++------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------+----------+--------+
+| fileLocation           | Location of Report Output Period file.                                                                                                                                     |      |          |        |
++------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------+----------+--------+
+| nfTypeModelInvariantId | The invariant ID will be used to filter nf's if a list of nf names is not provided, or if regex is used to specify all nf's of a specific type.                            |      |          |        |
++------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------+----------+--------+
+| nfFilter               | The network function filter will be used to filter the list of nf's stored in A&AI to produce a subset.                                                                    |      |          |        |
++------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------+----------+--------+
+| measurementGroup       | List of measurement types and managed object distinguished names                                                                                                           |      |          |        |
++------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------+----------+--------+
+
+**nfFilter**
+
+The ``nfFilter`` will be used in order to filter the list of NF's retrieved from A&AI. It will filter on the names
+specified in the ``nfNames`` field, which can also contain regex as seen below.
+
+::
+
+        "nfFilter": {
+            "swVersions": [
+                "1.0.0",
+                "1.0.1"
+            ],
+            "nfNames": [
+                "ABC",
+                "DEF",
+                "foo.*"
+            ]
+        }
+
++------------+-----------------------------------------------------------------------------+------+----------+
+| Field      | Description                                                                 | Type | Required |
++============+=============================================================================+======+==========+
+| swVersions | List of software versions                                                   | list | True     |
++------------+-----------------------------------------------------------------------------+------+----------+
+| nfNames    | List of NF names. These names are regexes, which will be parsed by the PMSH | list | True     |
++------------+-----------------------------------------------------------------------------+------+----------+
+
+**measurementGroup**
+
+``measurementGroup`` is used to specify the group of measurements that will be collected.
+
+::
+
+         "measurementGroup": {
+           "measurementTypes": [
+             {
+               "measurementType": "EutranCell.*"
+             },
+             {
+               "measurementType": "EutranCellRelation.pmCounter1"
+             },
+             {
+               "measurementType": "EutranCellRelation.pmCounter2"
+             }
+           ],
+           "managedObjectDNsBasic": [
+             {
+               "DN": "ManagedElement=1,ENodeBFunction=1,EUtranCell=CityCenter1"
+             },
+             {
+               "DN": "ManagedElement=1,ENodeBFunction=1,EUtranCell=CityCenter1, EUtranCellRelation=CityCenter2"
+             },
+             {
+               "DN": "ManagedElement=1,ENodeBFunction=1,EUtranCell=CityCenter1, EUtranCellRelation=CityCenter3"
+             }
+           ]
+         }
+
++-----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+------+----------+
+| Field                 | Description                                                                                                                                       | Type | Required |
++=======================+===================================================================================================================================================+======+==========+
+| measurementTypes      | List of measurement types. These are regexes, and it is expected that either the CDS blueprint, or NF can parse them. As the PMSH will not do so. | list | True     |
++-----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+------+----------+
+| managedObjectDNsBasic | List of managed object distinguished names.                                                                                                       | list | True     |
++-----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+------+----------+
+
+.. _Topics:
+
+MR Topics
+"""""""""""""""""""""
+
+Subscriber:
+^^^^^^^^^^^
+
+::
+
+        AAI-EVENT
+
+This topic is used so that the PMSH can listen for new NFs getting registered. If the NF matches the NF filter (See
+:ref:`Configuration<Configuration>`) it will be added to the relevant subscription. This topic is **AAI_EVENT**.
+
+::
+
+        org.onap.dmaap.mr.PM_SUBSCRIPTION_EVENTS
+
+This topic is used for locking and unlocking events. i.e if a user has previously created a locked
+subscription, they can publish an event to this topic to unlock it, or vice versa.
+
+Publisher:
+^^^^^^^^^^
+
+::
+
+        org.onap.dmaap.mr.PM_SUBSCRIPTIONS
+
+The PMSH publishes subscriptions to this topic. They will be consumed by a policy which will make a request to CDS to
+unlock the subscription.
\ No newline at end of file
diff --git a/docs/sections/services/pm-subscription-handler/delivery.rst b/docs/sections/services/pm-subscription-handler/delivery.rst
new file mode 100644
index 00000000..874efad8
--- /dev/null
+++ b/docs/sections/services/pm-subscription-handler/delivery.rst
@@ -0,0 +1,16 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+.. _Delivery:
+
+Delivery
+========
+
+Docker Container
+----------------
+
+The PMSH is delivered as a docker image that can be downloaded from ONAP docker registry.
+
+::
+
+    nexus3.onap.org:10001/onap/org.onap.dcaegen2.services.pm-subscription-handler
\ No newline at end of file
diff --git a/docs/sections/services/pm-subscription-handler/index.rst b/docs/sections/services/pm-subscription-handler/index.rst
new file mode 100644
index 00000000..83b831f1
--- /dev/null
+++ b/docs/sections/services/pm-subscription-handler/index.rst
@@ -0,0 +1,18 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+
+PM Subscription Handler
+=============================
+
+.. Add or remove sections below as appropriate for the platform component.
+
+.. toctree::
+   :maxdepth: 1
+
+   ./overview.rst
+   ./delivery.rst
+   ./logging.rst
+   ./installation.rst
+   ./configuration.rst
+   ./troubleshooting.rst
\ No newline at end of file
diff --git a/docs/sections/services/pm-subscription-handler/installation.rst b/docs/sections/services/pm-subscription-handler/installation.rst
new file mode 100644
index 00000000..49da2ea9
--- /dev/null
+++ b/docs/sections/services/pm-subscription-handler/installation.rst
@@ -0,0 +1,23 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+.. _Installation:
+
+Installation
+============
+
+The PMSH will be configured and instantiated through CLAMP. During instantiation, the PMSH will fetch its configuration
+from the Config Binding Service.
+
+Deployment Prerequisites
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+In order to succesfully deploy the PMSH, the following components are required to be running. They
+can be verified by running the healtchecks.
+
+    - DCAE Platform
+    - DMaaP
+    - SDC
+    - CLAMP
+    - A&AI
+    - AAF
diff --git a/docs/sections/services/pm-subscription-handler/logging.rst b/docs/sections/services/pm-subscription-handler/logging.rst
new file mode 100644
index 00000000..5fa5f3d7
--- /dev/null
+++ b/docs/sections/services/pm-subscription-handler/logging.rst
@@ -0,0 +1,20 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+.. _Logging:
+
+The PMSH logs will roll when the log file reaches 10Mb and a single backup will be kept. The logging level is not
+configurable.
+
+Logging
+=======
+
+There are four log files within the PMSH container, they are located in /var/log/ONAP/pmsh/
+
+.. code-block:: bash
+
+        /var/log/ONAP/pmsh/error.log (Level: Error)
+        /var/log/ONAP/pmsh/debug.log (Level: Debug)
+        /var/log/ONAP/pmsh/audit.log (Level: Info)
+        /var/log/ONAP/pmsh/metrics.log (Level: Info)
+
diff --git a/docs/sections/services/pm-subscription-handler/overview.rst b/docs/sections/services/pm-subscription-handler/overview.rst
new file mode 100644
index 00000000..076d384a
--- /dev/null
+++ b/docs/sections/services/pm-subscription-handler/overview.rst
@@ -0,0 +1,54 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+.. _Overview:
+
+Overview
+========
+
+Introduction
+""""""""""""
+The PM Subscription Handler (PMSH) is a micro service written in Python, which allows for the definition and unlocking
+of PM subscriptions on one or more network function (NF) instances.
+
+.. _Delivery: ./delivery.html
+
+Functionality
+"""""""""""""
+The PMSH allows for the definition of subscriptions on a network level, which enables the
+configuration of PM data on a set of NF instances.
+
+Interaction
+"""""""""""
+
+Config Binding Service
+^^^^^^^^^^^^^^^^^^^^^^
+
+The PMSH interacts with the Config Binding Service to retrieve it's configuration information, including the
+subscription information.
+
+DMaaP
+^^^^^
+
+The PMSH subscribes and publishes to various DMaaP Message Router topics (See :ref:`Topics<Topics>`
+for more information on which topics are used).
+
+A&AI
+^^^^
+
+The PMSH interacts with A&AI to fetch data about network functions. The ``nfFilter`` is then
+applied to this data to produce a targeted subset of NF's.
+
+Policy and CDS
+^^^^^^^^^^^^^^
+
+The PMSH will indirectly interact with Policy and CDS in order to push subscriptions to NF's. A policy will be used to
+make a request to CDS, which will apply the subscription to the NF.
+
+
+
+
+
+
+
+
diff --git a/docs/sections/services/pm-subscription-handler/troubleshooting.rst b/docs/sections/services/pm-subscription-handler/troubleshooting.rst
new file mode 100644
index 00000000..daf0cb07
--- /dev/null
+++ b/docs/sections/services/pm-subscription-handler/troubleshooting.rst
@@ -0,0 +1,24 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+.. _Troubleshooting:
+
+Troubleshooting
+===============
+
+Configuration Errors
+""""""""""""""""""""
+
+If the PMSH fails to start and is in CrashLoopBackOff, it is likely due to a configuration error.
+
+Unable to connect to Config Binding Service
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The PMSH may not be able to reach the Config Binding Service. If this is the case you will be able to
+see an error connecting to Config Binding Service in Kibana.
+
+Invalid Configuration
+^^^^^^^^^^^^^^^^^^^^^
+
+If the PMSH is able to connect to Config Binding Service, but is failing to start. It may be due to
+invalid configuration. Check Kibana for an incorrect configuration error.
\ No newline at end of file
diff --git a/docs/sections/services/serviceindex.rst b/docs/sections/services/serviceindex.rst
index c046157c..e7faca4a 100644
--- a/docs/sections/services/serviceindex.rst
+++ b/docs/sections/services/serviceindex.rst
@@ -18,6 +18,7 @@ DCAE Service components
    ./dfc/index.rst
    ./heartbeat-ms/index.rst
    ./pm-mapper/index.rst
+   ./pm-subscription-handler/index.rst
    ./bbs-event-processor/index.rst
    ./son-handler/index.rst
    ./restconf/index.rst