From 6cf238429ab448de881e1458ea10697df8c9dcde Mon Sep 17 00:00:00 2001 From: dfarrelly Date: Wed, 27 Nov 2019 15:13:04 +0000 Subject: Add PMSH documentation *Add base PM Subscription Handler documentation Issue-ID: DCAEGEN2-1837 Change-Id: I17bb587ef56704e0a122d65c7d29a2998489ce9c Signed-off-by: dfarrelly --- .../pm-subscription-handler/configuration.rst | 203 +++++++++++++++++++++ .../services/pm-subscription-handler/delivery.rst | 16 ++ .../services/pm-subscription-handler/index.rst | 18 ++ .../pm-subscription-handler/installation.rst | 23 +++ .../services/pm-subscription-handler/logging.rst | 20 ++ .../services/pm-subscription-handler/overview.rst | 54 ++++++ .../pm-subscription-handler/troubleshooting.rst | 24 +++ docs/sections/services/serviceindex.rst | 1 + 8 files changed, 359 insertions(+) create mode 100644 docs/sections/services/pm-subscription-handler/configuration.rst create mode 100644 docs/sections/services/pm-subscription-handler/delivery.rst create mode 100644 docs/sections/services/pm-subscription-handler/index.rst create mode 100644 docs/sections/services/pm-subscription-handler/installation.rst create mode 100644 docs/sections/services/pm-subscription-handler/logging.rst create mode 100644 docs/sections/services/pm-subscription-handler/overview.rst create mode 100644 docs/sections/services/pm-subscription-handler/troubleshooting.rst 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`) 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` +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 -- cgit 1.2.3-korg