docs/sections/services/pm-subscription-handler/installation.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright 2022 Nordix Foundation
   4
   5
   6 Installation and Configuration
   7 ==============================
   8
   9 PM Subscription Handler (PMSH) microservice can be deployed using helm charts in oom repository.
  10
  11
  12 Deployment Prerequisites
  13 ~~~~~~~~~~~~~~~~~~~~~~~~
  14
  15 - PMSH service requires config-binding-service, policy, dmaap, cds, aai and aaf components to be running.
  16
  17
  18
  19
  20 Deployment Steps
  21 ~~~~~~~~~~~~~~~~
  22
  23 - Default app config values can be updated in oom/kubernetes/dcaegen2-services/components/dcae-pmsh/values.yaml
  24
  25
  26 - Enable PMSH component in oom/kubernetes/dcaegen2-services/values.yaml
  27
  28   .. code-block:: bash
  29
  30     dcae-pmsh:
  31         enabled: true
  32
  33 - Make the chart and deploy using the following command:
  34
  35   .. code-block:: bash
  36
  37     cd oom/kubernetes/
  38     make dcaegen2-services
  39     helm install dev-dcaegen2-services dcaegen2-services --namespace <namespace> --set global.masterPassword=<password>
  40
  41 - To deploy only PMSH:
  42
  43   .. code-block:: bash
  44
  45     helm install dev-pmsh dcaegen2-services/components/dcae-pmsh --namespace <namespace> --set global.masterPassword=<password>
  46
  47 - To uninstall:
  48
  49   .. code-block:: bash
  50
  51     helm uninstall dev-pmsh
  52
  53
  54 .. _Subscription:
  55
  56 Subscription configuration
  57 """"""""""""""""""""""""""
  58
  59 The subscription is configured within the monitoring policy. The subscription model schema is as follows:
  60
  61 **subscription**
  62
  63 .. code-block:: json
  64
  65     {
  66        "subscription":{
  67           "subscriptionName":"someExtraPM-All-gNB-R2B",
  68           "operationalPolicyName":"operational-policy-name",
  69           "controlLoopName":"controlLoop-name",
  70           "nfFilter":{
  71              "nfNames":[
  72                 "^pnf1.*"
  73              ],
  74              "modelInvariantIDs":[
  75                 "5845y423-g654-6fju-po78-8n53154532k6",
  76                 "7129e420-d396-4efb-af02-6b83499b12f8"
  77              ],
  78              "modelVersionIDs":[
  79                 "e80a6ae3-cafd-4d24-850d-e14c084a5ca9"
  80              ],
  81             "modelNames": [
  82                 "pnf102"
  83             ]
  84           },
  85           "measurementGroups":[
  86              {
  87                 "measurementGroup":{
  88                    "measurementGroupName":"msgroupname",
  89                    "administrativeState":"UNLOCKED",
  90                    "fileBasedGP":15,
  91                    "fileLocation":"/pm/pm.xml",
  92                    "measurementTypes":[
  93                       {
  94                          "measurementType":"EutranCell.*"
  95                       },
  96                       {
  97                          "measurementType":"EutranCellRelation.pmCounter1"
  98                       },
  99                       {
 100                          "measurementType":"EutranCellRelation.pmCounter2"
 101                       }
 102                    ],
 103                    "managedObjectDNsBasic":[
 104                       {
 105                          "DN":"ManagedElement=1,ENodeBFunction=1,EUtranCell=CityCenter1"
 106                       },
 107                       {
 108                          "DN":"ManagedElement=1,ENodeBFunction=1,EUtranCell=CityCenter1, EUtranCellRelation=CityCenter2"
 109                       },
 110                       {
 111                          "DN":"ManagedElement=1,ENodeBFunction=1,EUtranCell=CityCenter1, EUtranCellRelation=CityCenter3"
 112                       }
 113                    ]
 114                 }
 115              }
 116           ]
 117        }
 118     }
 119
 120
 121 +-----------------------+---------------------------------------------------------------------------------------------------------+--------+----------+--------------------------+
 122 | Field                 | Description                                                                                             | Type   | Required | Values                   |
 123 +-----------------------+---------------------------------------------------------------------------------------------------------+--------+----------+--------------------------+
 124 | subscriptionName      | Name of the subscription.                                                                               | string | True     | subscriptionName         |
 125 +-----------------------+---------------------------------------------------------------------------------------------------------+--------+----------+--------------------------+
 126 | operationalPolicyName | Name of the operational policy to be executed.                                                          | string | True     | operationalPolicyName    |
 127 +-----------------------+---------------------------------------------------------------------------------------------------------+--------+----------+--------------------------+
 128 | controlLoopName       | Name of the control loop.                                                                               | string | False    | controlLoopName          |
 129 +-----------------------+---------------------------------------------------------------------------------------------------------+--------+----------+--------------------------+
 130 | nfFilter              | The network function filter will be used to filter the list of nf's stored in A&AI to produce a subset. |  list  | True     |                          |
 131 +-----------------------+---------------------------------------------------------------------------------------------------------+--------+----------+--------------------------+
 132 | measurementGroups     | List containing measurementGroup.                                                                       |  list  | True     | List of measurementGroup |
 133 +-----------------------+---------------------------------------------------------------------------------------------------------+--------+----------+--------------------------+
 134
 135 .. note::
 136   Since release Istanbul of ONAP, PMSH Subscriptions model schema is updated.
 137   Subscription model is centric to ``measurementGroup``, for instance any update on attributes administrativeState, fileBasedGP,
 138   fileLocation, nfFilter will be applicable to only individual measurementGroup object.
 139
 140 **nfFilter**
 141
 142 The ``nfFilter`` will be used in order to filter the list of NF's retrieved from A&AI. There are four criteria that
 143 can be filtered on, nfNames, modelInvariantIDs, modelVersionIDs and/or modelNames.  All 4 of these are optional fields but at
 144 least 1 must be present for the filter to work.
 145
 146 .. code-block:: json
 147
 148     "nfFilter": {
 149         "nfNames":[
 150            "^pnf.*",
 151            "^vnf.*"
 152         ],
 153         "modelInvariantIDs": [
 154            "5845y423-g654-6fju-po78-8n53154532k6",
 155            "7129e420-d396-4efb-af02-6b83499b12f8"
 156         ],
 157         "modelVersionIDs": [
 158            "e80a6ae3-cafd-4d24-850d-e14c084a5ca9"
 159         ],
 160         "modelNames": [
 161             "pnf102"
 162         ]
 163     }
 164
 165 +------------------------+-----------------------------------------------------------------------------------------------+------+----------+
 166 | Field                  | Description                                                                                   | Type | Required |
 167 +========================+===============================================================================================+======+==========+
 168 | nfNames                | List of NF names. These names are regexes, which will be parsed by the PMSH.                  | list | True     |
 169 +------------------------+-----------------------------------------------------------------------------------------------+------+----------+
 170 | modelInvariantIDs      | List of modelInvariantIDs. These UUIDs will be checked for exact matches with AAI entities.   | list | True     |
 171 +------------------------+-----------------------------------------------------------------------------------------------+------+----------+
 172 | modelVersionIDs        | List of modelVersionIDs. These IDs will be checked for exact matches with AAI entities.       | list | True     |
 173 +------------------------+-----------------------------------------------------------------------------------------------+------+----------+
 174 | modelNames             | List of modelNames. These names will be checked for exact matches with AAI entities.          | list | True     |
 175 +------------------------+-----------------------------------------------------------------------------------------------+------+----------+
 176
 177 **measurementGroup**
 178
 179 ``measurementGroup`` is used to specify the group of measurements that will be collected.
 180
 181 .. code-block:: json
 182
 183     "measurementGroup": {
 184        "measurementGroupName":"msgroupname",
 185        "administrativeState":"UNLOCKED",
 186        "fileBasedGP":15,
 187        "fileLocation":"/pm/pm.xml",
 188        "measurementTypes": [
 189          {
 190            "measurementType": "EutranCell.*"
 191          },
 192          {
 193            "measurementType": "EutranCellRelation.pmCounter1"
 194          },
 195          {
 196            "measurementType": "EutranCellRelation.pmCounter2"
 197          }
 198        ],
 199        "managedObjectDNsBasic": [
 200          {
 201            "DN": "ManagedElement=1,ENodeBFunction=1,EUtranCell=CityCenter1"
 202          },
 203          {
 204            "DN": "ManagedElement=1,ENodeBFunction=1,EUtranCell=CityCenter1, EUtranCellRelation=CityCenter2"
 205          },
 206          {
 207            "DN": "ManagedElement=1,ENodeBFunction=1,EUtranCell=CityCenter1, EUtranCellRelation=CityCenter3"
 208          }
 209        ]
 210     }
 211
 212 +-----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------+----------+--------+
 213 | Field                 | Description                                                                                                                                                                            | Type | Required | Values |
 214 +=======================+========================================================================================================================================================================================+======+==========+========+
 215 | measurementGroupName  | Unique identifier for measurementGroup.                                                                                                                                                |      | True     |        |
 216 +-----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------+----------+--------+
 217 | administrativeState   | Setting a measurementGroup to UNLOCKED will apply the subscription changes to the NF instances immediately. If it is set to LOCKED, it will not be applied until it is later unlocked. |      | True     |        |
 218 +-----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------+----------+--------+
 219 | fileBasedGP           | The frequency at which measurements are produced.                                                                                                                                      |      | True     |        |
 220 +-----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------+----------+--------+
 221 | fileLocation          | Location of Report Output Period file.                                                                                                                                                 |      | True     |        |
 222 +-----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------+----------+--------+
 223 | 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     |        |
 224 +-----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------+----------+--------+
 225 | managedObjectDNsBasic | List of managed object distinguished names.                                                                                                                                            | list | True     |        |
 226 +-----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------+----------+--------+
 227
 228 .. _Topics:
 229
 230 MR Topics
 231 """""""""
 232
 233 Subscriber:
 234 ^^^^^^^^^^^
 235
 236 ::
 237
 238         AAI-EVENT
 239
 240 This topic is used so that the PMSH can listen for new NFs getting added or deleted. If the NF matches the NF filter it will be added to the relevant subscription.
 241
 242 ::
 243
 244         unauthenticated.PMSH_CL_INPUT
 245
 246 This topic enables the operational policy to provide feedback on the status of a subscription attempt, back to
 247 PMSH, with a message of either success or failed.
 248
 249 Example of successful CREATE event sent from policy:
 250
 251 .. code-block:: json
 252
 253     {
 254         "name": "ResponseEvent",
 255         "nameSpace": "org.onap.policy.apex.onap.pmcontrol",
 256         "source": "APEX",
 257         "target": "DCAE",
 258         "version": "0.0.1",
 259         "status": {
 260             "subscriptionName": "subscriptiona",
 261             "measurementGroupName":"msgroupname",
 262             "nfName": "PNF104",
 263             "changeType": "CREATE",
 264             "message": "success"
 265         }
 266     }
 267
 268
 269 Publisher:
 270 ^^^^^^^^^^
 271
 272 .. _DCAE_CL_OUTPUT_Topic:
 273
 274 ::
 275
 276         unauthenticated.DCAE_CL_OUTPUT
 277
 278 PMSH publishes subscriptions to this topic. They will be consumed by an operational policy which will make a request to CDS to
 279 change the state of the subscription.
 280
 281 .. note::
 282   Since release Istanbul of ONAP, PMSH Publish Subscriptions event format is updated.
 283   A new attribute ``measurementGroupName`` is added as a unique identifier for ``measurementGroup`` and a single ``measurementGroup`` is associated with
 284   PMSH Subscription event.
 285
 286 Example event sent from PMSH:
 287
 288 .. code-block:: json
 289
 290     {
 291        "nfName":"PNF104",
 292        "ipv4Address": "10.12.13.12",
 293        "policyName":"operational-policy-name",
 294        "closedLoopControlName":"controlLoop-name",
 295        "blueprintName":"pm_control",
 296        "blueprintVersion":"1.2.4",
 297        "changeType":"CREATE",
 298        "subscription":{
 299           "administrativeState":"UNLOCKED",
 300           "subscriptionName":"subscriptiona",
 301           "fileBasedGP":15,
 302           "fileLocation":"/pm/pm.xml",
 303           "measurementGroup":{
 304              "measurementGroupName":"msgroupname",
 305              "measurementTypes":[
 306                 {
 307                    "measurementType":"countera"
 308                 },
 309                 {
 310                    "measurementType":"counterb"
 311                 }
 312              ],
 313              "managedObjectDNsBasic":[
 314                 {
 315                    "DN":"dna"
 316                 },
 317                 {
 318                    "DN":"dnb"
 319                 }
 320              ]
 321           }
 322        }
 323     }