Page History

...

Expand

title	PM Mapper Sequence Diagram

Bulk PM Flow:

NF notifies DCAE that VES Collector that a PM file is available for upload.
Data File Collector uploads Collector downloads PM Files from the NF and stores publishes them in to Data Router.
PM-Mapper creates custom Performance events (VES) from the PM File data according to PM Mapping File.
Analytics Applications use these performance events for targeted analysis of network operations.

...

Deployment Steps

Execute bash on the Cloudify manager bootstrap Kubernetes pod.
Code Block
language bash
theme Emacs
kubectl -n onap exec -it <dev<dcaegen2-dcaegen2-dcae-cloudify-manager>bootstrap> bash
Download the pm-mapper blueprint and save to /blueprints directory.
Create an inputs file (see the configuration section for more information).
Run the Cloudify Install command to install the Check that the tag_version of pm-mapper in the pm-mapper blueprint is correct for the release of ONAP that it is being installed on see Nexus link for pm-mapper for tag_versions
Create an inputs file (see the configuration section for more information).

Run the Cloudify Install command to install the pm-mapper with the with the recently downloaded blueprints, and the newly created inputs files.

Code Block

language	bash
theme	Emacs

cfy install --blueprint-id pm-mapper --deployment-id pm-mapper -i inputs.yaml <pm-mapper-blueprint-path>

Expand

title	Sample output

$ cfy install k8s--blueprint-id pm-mapper.yaml --blueprintdeployment-id pm-mapper --deployment-id i inputs.yaml blueprints/k8s-pm-mapper.yaml

Uploading blueprint k8s-pm-mapper.yaml...
k8s-pm-mapper.yaml |###################################################| 100.0%
Blueprint uploaded. The blueprint's id is pm-mapper
Creating new deployment from blueprint pm-mapper...
Deployment created. The deployment's id is pm-mapper
Executing workflow install on deployment pm-mapper [timeout=900 seconds]
Deployment environment creation is pending...
2019-04-11 16:00:37.497 CFY <pm-mapper> Starting 'create_deployment_environment' workflow execution
2019-04-11 16:00:38.692 CFY <pm-mapper> Installing deployment plugins
2019-04-11 16:00:38.692 CFY <pm-mapper> [,] Sending task 'cloudify_agent.operations.install_plugins'
2019-04-11 16:00:38.692 CFY <pm-mapper> [,] Task started 'cloudify_agent.operations.install_plugins'
2019-04-11 16:00:38.354 LOG <pm-mapper> [,] INFO: Installing plugin: k8s
2019-04-11 16:00:39.654 LOG <pm-mapper> [,] INFO: Using existing installation of managed plugin: 29023340-17d9-4737-886a-abba002334cd [package_name: k8splugin, package_version: 1.4.5, supported_platform: linux_x86_64, distribution: centos, distribution_release: core]
2019-04-11 16:00:39.810 CFY <pm-mapper> [,] Task succeeded 'cloudify_agent.operations.install_plugins'
2019-04-11 16:00:40.717 CFY <pm-mapper> Skipping starting deployment policy engine core - no policies defined
2019-04-11 16:00:41.725 CFY <pm-mapper> Creating deployment work directory
2019-04-11 16:00:41.725 CFY <pm-mapper> 'create_deployment_environment' workflow execution succeeded
2019-04-11 16:00:45.447 CFY <pm-mapper> Starting 'install' workflow execution
2019-04-11 16:00:46.733 CFY <pm-mapper> [pm-mapper_twszsn] Creating node
2019-04-11 16:00:46.733 CFY <pm-mapper> [pm-mapper_twszsn.create] Sending task 'k8splugin.create_for_platforms'
2019-04-11 16:00:46.733 CFY <pm-mapper> [pm-mapper_twszsn.create] Task started 'k8splugin.create_for_platforms'
2019-04-11 16:00:47.563 LOG <pm-mapper> [pm-mapper_twszsn.create] INFO: Added config for dcae-pm-mapper
2019-04-11 16:00:48.675 LOG <pm-mapper> [pm-mapper_twszsn.create] INFO: Done setting up: dcae-pm-mapper
2019-04-11 16:00:48.470 CFY <pm-mapper> [pm-mapper_twszsn.create] Task succeeded 'k8splugin.create_for_platforms'
2019-04-11 16:00:48.745 CFY <pm-mapper> [pm-mapper_twszsn] Configuring node
2019-04-11 16:00:49.759 CFY <pm-mapper> [pm-mapper_twszsn] Starting node
2019-04-11 16:00:49.759 CFY <pm-mapper> [pm-mapper_twszsn.start] Sending task 'k8splugin.create_and_start_container_for_platforms'
2019-04-11 16:00:49.759 CFY <pm-mapper> [pm-mapper_twszsn.start] Task started 'k8splugin.create_and_start_container_for_platforms'
2019-04-11 16:00:51.693 LOG <pm-mapper> [pm-mapper_twszsn.start] INFO: Passing k8sconfig: {'tls': {u'cert_path': u'/opt/tls/shared', u'image': u'nexus3.onap.org:10001/onap/org.onap.dcaegen2.deployments.tls-init-container:1.0.1-STAGING-latest'}, 'consul_host': 'consul-server:8500', 'consul_dns_name': u'consul-server.onap', 'image_pull_secrets': [u'onap-docker-registry-key'], 'namespace': u'onap', 'filebeat': {u'config_map': u'dcae-filebeat-configmap', u'config_path': u'/usr/share/filebeat/filebeat.yml', u'log_path': u'/var/log/onap', u'image': u'docker.elastic.co/beats/filebeat:5.5.0', u'data_path': u'/usr/share/filebeat/data', u'config_subpath': u'filebeat.yml'}}
2019-04-11 16:00:51.339 LOG <pm-mapper> [pm-mapper_twszsn.start] INFO: Starting k8s deployment for dcae-pm-mapper, image: nexus3.onap.org:10001/onap/org.onap.dcaegen2.services.pm-mapper:1.0.0, env: {'CONSUL_HOST': u'consul-server.onap', 'CONFIG_BINDING_SERVICE': 'config-binding-service'}, kwargs: {'tls_info': {}, 'replicas': 1, 'labels': {'cfydeployment': u'pm-mapper', 'cfynodeinstance': u'pm-mapper_twszsn', 'cfynode': u'pm-mapper'}, 'ctx': <cloudify.context.CloudifyContext object at 0x7f5fb5bb7710>, 'always_pull_image': False, u'ports': [u'6162:0']}
2019-04-11 16:00:52.705 LOG <pm-mapper> [pm-mapper_twszsn.start] INFO: k8s deployment initiated successfully for dcae-pm-mapper: {'services': ['dcae-pm-mapper'], 'namespace': u'onap', 'deployment': 'dep-dcae-pm-mapper'}
2019-04-11 16:00:52.705 LOG <pm-mapper> [pm-mapper_twszsn.start] INFO: Waiting up to 300 secs for dcae-pm-mapper to become ready
2019-04-11 16:02:18.873 LOG <pm-mapper> [pm-mapper_twszsn.start] INFO: k8s deployment ready for: dcae-pm-mapper
2019-04-11 16:02:19.621 CFY <pm-mapper> [pm-mapper_twszsn.start] Task succeeded 'k8splugin.create_and_start_container_for_platforms'
2019-04-11 16:02:20.893 CFY <pm-mapper> 'install' workflow execution succeeded
Finished executing workflow install on deployment pm-mapper
* Run 'cfy events list -e 37da3f5f-a06b-4ce8-84d3-8b64ccd81c33' to retrieve the execution's events/logs

...

curl <dcaegen2-dcae-healthcheck> and check if pm-mapper is in 'ready' state.

Expand

title	See example

Code Block

theme	Emacs

$ curl 10.42.181.66 | jq

{
"type": "summary",
"count": 12,
"ready": 11,
"items": [
{
"name": "dev-dcaegen2-

 '.items[] | select(.name | contains("pm-mapper"))'
{
"name": "dev-dcaegen2-dcae-pm-mapper",


"ready": 1,


"unavailable": 0

,

{
"name": "dev-dcaegen2-dcae-config-binding-service",
"ready": 1,
"unavailable": 0
},
{
"name": "dev-dcaegen2-dcae-inventory-api",
"ready": 1,
"unavailable": 0
},
{
"name": "dev-dcaegen2-dcae-servicechange-handler",
"ready": 0,
"unavailable": 1
},
{
"name": "dev-dcaegen2-dcae-deployment-handler",
"ready": 1,
"unavailable": 0
},
{
"name": "dev-dcaegen2-dcae-policy-handler",
"ready": 1,
"unavailable": 0
},
{
"name": "dep-dcae-ves-collector",
"ready": 1,
"unavailable": 0
},
{
"name": "dep-dcae-tca-analytics",
"ready": 1,
"unavailable": 0
},
{
"name": "dep-dcae-prh",
"ready": 1,
"unavailable": 0
},
{
"name": "dep-dcae-hv-ves-collector",
"ready": 1,
"unavailable": 0
},
{
"name": "dep-dcae-datafile-collector",
"ready": 1,
"unavailable": 0
},
{
"name": "dep-dcae-snmptrap-collector",
"ready": 1,
"unavailable": 0
}
]
}

Configuration

Configuration of the service consists of generating an inputs file which will be used as part of the Cloudify install. The PM-Mapper blueprints were designed with sane defaults for the majority of the fields.
Below you will find some examples of fields which can be configured, and some of the fields which must be configured.

In the Dublin release information about the AAF user must be provided to enable publishing to authenticated topics. An Inputs file with this information included can look like:

Code Block
aaf_username: dcae@dcae.onap.org aaf_password: <dcae_password>

where <dcae_password> is replaced with a real password.

By default, the PM-Mapper will only allow inbound queries over HTTPS, however its possible to configure it to enable HTTP also. This configuration can look like:

Code Block
enable_http: true

The default behavior of the PM-Mapper is to map all measType in the received PM XML files, however, it's possible to provide filtering configuration which will reduce the VES event to the counters that the designer has expressed interest in. An example of this configuration:

Code Block
pm-mapper-filter: {"filters":[{"pmDefVsn":"targetVersion","nfType":"targetNodeType","vendor":"targetVendor","measTypes":["targetMeasType"]}]}

In this provided example a VES event containing the "targetMeasType" will only be generated and published if the following conditions are true:

The type of the node sending the file is "targetNodeType"
The vendor of the node sending the file is "targetVendor"

Additional Information on the filter model can be found here.

...

Verification

To verify that the PM-Mapper is working as it should, we can publish a 3GPP XML file to the PM-Mapper, and verify that the counters in the outputted VES match what we expect based on our filtering.

To publish a file to the PM-Mapper we can use the following example curl. Where <filename> Must begin with A or C and the file extension must be xml.

Panel

borderColor	white
borderWidth	20

Expand

title	Example type A file

<?xml version="1.0" encoding="UTF-8"?>
<measCollecFile xmlns="http://www.3gpp.org/ftp/specs/archive/32_series/32.435#measCollec">
    <fileHeader dnPrefix="some dnPrefix" vendorName="Acme Ltd"
                fileFormatVersion="32.435 V10.0">
        <fileSender localDn="Dublin"/>
        <measCollec beginTime="2018-10-02T12:00:00+01:00"/>
    </fileHeader>
    <measData>
        <managedElement swVersion="r0.1" localDn="Dublin"/>
        <measInfo measInfoId="some measInfoId">
            <job jobId="some Job Id"/>
            <granPeriod endTime="2018-10-02T12:15:00Z" duration="PT900S"/>
            <repPeriod duration="PT900S"/>
            <measType p="1">a</measType>
            <measType p="2">b</measType>
            <measType p="3">c</measType>
            <measValue measObjLdn="some measObjLdn">
                <r p="1">86</r>
                <r p="2">67</r>
                <r p="3">14</r>
                <suspect>false</suspect>
            </measValue>
        </measInfo>
    </measData>
    <fileFooter>
        <measCollec endTime="2018-10-02T12:15:00+01:00"/>
    </fileFooter>
</measCollecFile>

Anchor

	pmMapperIncomingRequest
	pmMapperIncomingRequest

Code Block

language	bash
theme	Emacs

curl -k -X PUT https://dcae-pm-mapper:8443/delivery/<filename> -H 'X-DMAAP-DR-META:{"productName": "AcmeNode","vendorName": "Acme","lastEpochMicrosec": "1538478000000","sourceName": "oteNB5309","startEpochMicrosec": "1538478900000","timeZoneOffset": "UTC+05:00","location": "ftpes://127.0.0.1:22/ftp/rop/A20161224.1045-1100.bin.gz","compression": "gzip","fileFormatType": "org.3GPP.32.435#measCollec","fileFormatVersion": "V9"}' -H "Content-Type:application/xml" --data-binary @<filename> -H 'X-ONAP-RequestID: 12345' -H 'X-DMAAP-DR-PUBLISH-ID: 12345'

Note

title	Note

The productName and vendorName specified in X-DMAAP-DR-META must match the nfType and vendor specified during configuration of the PM-Mapper

We can then check that the XML has been processed and published to Message Router as a VES event by curling the PM-Mapper topic on Message Router.

We first need to set up a subscriber to the PM-Mapper topic as this is not set up by default. We can do this with the following curl to Bus Controller:

Code Block

language	bash
theme	Emacs

curl -X POST http://dmaap-bc:8080/webapi/mr_clients -H "Content-Type:application/json" --data @sub-client.json

Expand

title	sub-client.json

<= R4 release

Code Block

theme	Emacs

{
"dcaeLocationName": "san-francisco",
"fqtn": "org.onap.dmaap.mr.PM_MAPPER",
"clientIdentity": "dcae@dcae.onap.org",
"action": "sub"
}

El Alto release:

Code Block

theme	Emacs

{
"dcaeLocationName": "san-francisco",
"fqtn": "org.onap.dmaap.mr.PERFORMANCE_MEASUREMENTS",
"clientIdentity": "dcae@dcae.onap.org",
"action": "sub"
}

Once the subscriber is set up, we can curl the topic on Message Router to retrieve the published event:

Code Block

language	bash
theme	Emacs

<= R4 release
curl -k https://message-router:3905/events/org.onap.dmaap.mr.PM_MAPPER -u 'dcae@dcae.onap.org:<dcae_password>'

El Alto release:
curl -k https://message-router:3905/events/org.onap.dmaap.mr.PERFORMANCE_MEASUREMENTS/$ConsumerGroup/$ID -u 'dcae@dcae.onap.org:<dcae_password>'
e.g. 
curl -k https://message-router:3905/events/org.onap.dmaap.mr.PERFORMANCE_MEASUREMENTS/1/1 -u 'dcae@dcae.onap.org:<dcae_password>'

This VES event can then be compared to the filter specified during configuration of the PM-Mapper to verify that only the specified counters have been published.

Expand

title	Example key/value configuration in consul

Code Block

theme	Emacs

{
  "pm-mapper-filter": {
    "filters": [
      {
        "pmDefVsn": "1.8",
        "nfType": "AcmeNode",
        "vendor": "Acme",
        "measTypes": [
          "a",
          "c"
        ]
      }
    ]
  },
  "trust_store_pass_path": "/opt/app/pm-mapper/etc/cert/trust.pass",
  "key_store_path": "/opt/app/pm-mapper/etc/cert/cert.jks.b64",
  "streams_subscribes": {
    "dmaap_subscriber": {
      "type": "data_router",
      "dmaap_info": {
        "username": "username",
        "password": "password",
        "location": "san-francisco",
        "delivery_url": "https://dcae-pm-mapper:8443/delivery",
        "subscriber_id": "1"
      }
    }
  },
  "trust_store_path": "/opt/app/pm-mapper/etc/cert/trust.jks.b64",
  "streams_publishes": {
    "dmaap_publisher": {
      "aaf_password": "password",
      "type": "message_router",
      "dmaap_info": {
        "topic_url": "http://message-router:3904/events/org.onap.dmaap.mr.PM_MAPPER",
        "client_role": "org.onap.dmaap.mr.PM_MAPPER.pub",
        "location": "san-francisco",
        "client_id": "dcae@dcae.onap.org"
      },
      "aaf_username": "username"
    }
  },
  "dmaap_dr_delete_endpoint": "https://dmaap-dr-node:8443/delete",
  "key_store_pass_path": "/opt/app/pm-mapper/etc/cert/jks.pass",
  "enable_http": false,
  "dmaap_dr_feed_name": "bulk_pm_feed"
}

Using the example type A file above, and the example key/value configuration in consul, the PM Mapper will produce the following VES output, note that only counter "a" and "c" were mapped, as specified in the filter configuration.

Expand

title	Example VES output based on above configuration

Code Block

theme	Emacs

{
  "event": {
    "commonEventHeader": {
      "domain": "perf3gpp",
      "eventId": "f544c442-9dc1-41d4-8f0d-6567e1ea7729",
      "sequence": 0,
      "eventName": "perf3gpp_AcmeNode-Acme_pmMeasResult",
      "sourceName": "oteNB5309",
      "reportingEntityName": "",
      "priority": "Normal",
      "startEpochMicrosec": 1538478000000,
      "lastEpochMicrosec": 1538478900000,
      "version": "4.0",
      "vesEventListenerVersion": "7.1",
      "timeZoneOffset": "UTC+05:00"
    },
    "perf3gppFields": {
      "perf3gppFieldsVersion": "1.0",
      "measDataCollection": {
        "granularityPeriod": 1538482500000,
        "measuredEntityUserName": "",
        "measuredEntityDn": "Dublin",
        "measuredEntitySoftwareVersion": "r0.1",
        "measInfoList": [
          {
            "measInfoId": {
              "sMeasInfoId": "some measInfoId"
            },
            "measTypes": {
              "sMeasTypesList": [
                "a",
                "c"
              ]
            },
            "measValuesList": [
              {
                "measObjInstId": "some measObjLdn",
                "suspectFlag": "false",
                "measResults": [
                  {
                    "p": 1,
                    "sValue": "86"
                  },
                  {
                    "p": 3,
                    "sValue": "14"
                  }
                ]
              }
            ]
          }
        ]
      }
    }
  }
}

...

Configuration

Configuration of the service consists of generating an inputs file (YAML) which will be used as part of the Cloudify install. The PM-Mapper blueprints were designed with sane defaults for the majority of the fields.
Below you will find some examples of fields which can be configured, and some of the fields which must be configured (These may change depending on the version of ONAP).

Property	Sample Value	Description	Required
aaf_username	dcae@dcae.onap.org	In the Dublin release information about the AAF user must be provided to enable publishing to authenticated topics.	Yes
aaf_password	<dcae_password>	This is the password for the given user e.g. The <dcae_password> is dcae@dcae.onap.org's password.	Yes
enable_http	true	By default, the PM-Mapper will only allow inbound queries over HTTPS. However, it is possible to configure it to enable HTTP also.	No
tag_version	nexus3.onap.org:10001/onap/org.onap.dcaegen2.services.pm-mapper:<version>	By default the latest Docker Images will be used when deploying the PM-Mapper. Replace <version> with the desired Docker image version.	No
pm-mapper-filter	{"filters": [{"pmDefVsn":"targetVersion", "nfType":"targetNodeType", "vendor":"targetVendor", "measTypes":["targetMeasType"]}]}	The default behavior of the PM-Mapper is to map all measType in the received PM XML files, however, it's possible to provide filtering configuration which will reduce the VES event to the counters that the designer has expressed interest in. In this provided example a VES event containing the "targetMeasType" will only be generated and published if the following conditions are true: The vendor of the node sending the file is "targetVendor" The type of the node sending the file is "targetNodeType" Additional Information on the filter model can be found here.	No

Expand

title	Sample cloudify configuration input (Dublin)

Code Block

language	yml
theme	RDark
title	inputs.yaml

aaf_username: dcae@dcae.onap.org

aaf_password: demo123456!

enable_http: false

tag_version: nexus3.onap.org:10001/onap/org.onap.dcaegen2.services.pm-mapper:1.0.1

filter: {"filters": []}

Expand

title	Sample cloudify configuration input (El Alto)

Code Block

language	yml
theme	RDark
title	inputs.yaml

client_password : demo123456!
 
filter: {"filters": []}

...

Offline ONAP Install workarounds

If you want to instantiate PM-Mapper (and Datafile Collector) they will need to be copied from a server with internet access to the ONAP deployment which doesnt.

OOM-2243 when completed will include the PM-Mapper and Datafile Collector packages in the offline deployment environment.

Create the docker image on a server which has internet access i.e.
# docker pull nexus3.onap.org:10001/onap/org.onap.dcaegen2.services.pm-mapper:1.2.0
1.2.0: Pulling from onap/org.onap.dcaegen2.services.pm-mapper
Digest: sha256:f6a9349b575d7a62525196fec4f610a773db0ec6ff49be0bc6d0b134fc52a76d
Status: Downloaded newer image for nexus3.onap.org:10001/onap/org.onap.dcaegen2.services.pm-mapper:1.2.0
nexus3.onap.org:10001/onap/org.onap.dcaegen2.services.pm-mapper:1.2.0
# docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
nexus3.onap.org:10001/onap/org.onap.dcaegen2.services.pm-mapper 1.2.0 2bb6a1b426ab 36 minutes ago 101MB
# docker save 2bb6a1b426ab > 1.2.0.mapper.tar

On each of the K8s worker nodes copy the docker image for mapper (and DFC).
i.e.
cd /dockerdata-nfs/onap-dcaegen2/
docker load -i 1.2.0.mapper.tar
docker images
docker tag 06776409bc03 dcaegen2/pmmapper.1.2.0

On on bootstrap pod. (Look at the imports that are required in the blueprints) i.e
imports:
- 'http://www.getcloudify.org/spec/cloudify/4.5.5/types.yaml'
- 'https://nexus.onap.org/service/local/repositories/raw/content/org.onap.dcaegen2.platform.plugins/R5/k8splugin/1.6.0/k8splugin_types.yaml'
- 'https://nexus.onap.org/service/local/repositories/raw/content/org.onap.ccsdk.platform.plugins/type_files/dmaap/dmaap.yaml'

For each of the above yaml files open them on a server that has internet access then create a corresponding file on the bootstrap pod and paste the contents into that yaml.

so it becomes
imports:
- 455types.yaml
- 1608splugin.yaml
- dmaap.yaml

And also change
tag_version:
type: string
description: Docker image to be used
default: dcaegen2/pmmapper.1.2.0By default the latest Docker Images will be used when deploying the PM-Mapper, however, this attribute can also be configured like:

Space shortcuts

Page tree

Versions Compared

Old Version 39

New Version Current

Key

Deployment Steps

Configuration

Verification

Configuration

Offline ONAP Install workarounds