UniversalVesAdapter/README.md

   1 # DCAE VES Adapter (Mapper)
   2
   3 # Summary
   4 Different VNF vendors generates event and telemetry data in different formats. Out of the box all VNF vendors may not support ONAP VES format. The aim of this solution is to provide generic adapter(mapper) to VES which can convert different formats of event and telemetry data to VES format which is needed by ONAP. Currently supporting SNMP events JSON to VES
   5
   6 This release supports only SNMP format. DCAE existing SNMP traps receiver are pushing SNMP traps (converted to json format) to DMaaP. DCAE Universal VES Adapter (mapper) micro-service consumes snmp trap from dmaap topic and reads uploaded mapper file (for the specific vendor). After reading mapper file, converts snmp trap (JSON format) to VES format and publish on dmaap topic.
   7
   8 ONAP DCAE VES Adapter (Mapper) is delivered with **2 Docker container** having spring boot mocroservices, UniversalVesAdapter and snmpmapper. UniversalVesAdapter converts SNMP trap JSON to VES and snmpmapper is just helper application for uploading the mapping file to DB.
   9
  10 ### Build Instructions
  11
  12 This project is organized as a mvn project and has "org.onap.dcaegen2" as parent project. The build generate a jar and package into docker container.
  13
  14 ```
  15 git clone https://gerrit.onap.org/r/p/dcaegen2/services/mapper.git
  16 mvn clean install
  17 ```
  18
  19 ### Build Docker image
  20
  21 The following Maven command will build the JAR, build the Docker image to the local machine registry and then push the same image to the specified remote registry.
  22
  23 ```
  24 mvn clean package docker:build -DpushImageTag
  25 ```
  26
  27
  28 ### Run via Docker
  29
  30 Execute this to run.
  31
  32 ####UniversalVesAdapter
  33
  34 ```
  35  sudo docker run -d -p 8085:8085/tcp -e URL_JDBC=jdbc:postgresql://10.53.172.138:5432/postgres -e JDBC_USERNAME=postgres -e JDBC_PASSWORD=root -e DMAAPHOST=10.53.172.156 -e CONSUL_HOST=10.53.172.109 -e HOSTNAME=static-dcaegen2-services-mua -e MR_DEFAULT_PORT_NUMBER=3904 -e CONFIG_BINDING_SERVICE=config_binding_service nexus3.onap.org:10003/onap/org.onap.dcaegen2.services.mapper.vesadapter.universalvesadaptor:latest
  36 ```
  37
  38 ### Environment variables in Docker Container
  39 Most of the configuration of how UniversalVesAdapter should be started and managed is done through environment variables.
  40 Some of them are set during the image build process and some of them are defined manually or by
  41 a particular deployment system.
  42
  43 Variables set manually / coming from deployment system:
  44 - DMAAPHOST-should contain an address to DMaaP, so that event publishing can work
  45 - MR_PORT - DMaaP Exposed Port
  46 - URL_JDBC- JDBC URL
  47 - JDBC_USERNAME- Username for DB user
  48 - JDBC_PASSWORD-Password for DB user
  49 - CONSUL_HOST -
  50 - CONFIG_BINDING_SERVICE -
  51 - HOSTNAME -
  52
  53
  54
  55 ### Docker file system layout
  56 The main directory where all code resides in docker container
  57 looks like this and is located in /opt/app/VESAdapter
  58 ```
  59 <host>:/opt/app/VESAdapter# ls
  60 Dockerfile  bin  conf  lib  logs
  61 ```
  62 - bin contains startup script for running the application
  63 - conf contains default mapping file inserted to DB (defaultSnmpMappingFile.xml)
  64 - lib contains all libraries that are pulled into the app during maven build
  65 - logs contains application logs, DroppedEvents.log file contains invalid events which are drop during publishing events.
  66
  67
  68 ## How the application starts inside container
  69 General flow goes like this
  70 - Docker image is build, and it points run.sh as the entrypoint.
  71 - run.sh calls the spring boot starter class which in turns calls VESAdapterInitializer
  72 - Here entry point will be depending on the deployment type, Getting configuration from docker env var or from CBS
  73   configures a bunch of things and starts the application in a separate process
  74
  75 ### Release images
  76 For R1 - image/version  pushed to nexus3
  77
  78 ```
  79 nexus3.onap.org:10003/snapshots/onap/org.onap.dcaegen2.services.mapper.vesadapter.universalvesadaptor latest
  80 ```
  81
  82
  83 ### Deployment
  84 For testing purpose, the docker image includes preset configuration which can be ran without DCAEGEN2 platform.
  85
  86
  87 ### Testing
  88
  89
  90 ```
  91 STEPS FOR SETUP/TEST
  92 1)      Get the VESAdapter image from Nexus
  93                 docker pull nexus3.onap.org:10003/snapshots/onap/org.onap.dcaegen2.services.mapper.vesadapter.universalvesadaptor:latest
  94 2)      Start the container (change the DMAAPHOST and MR_DEFAULT_PORT_NUMBER environment value to running DMAAP instance host as well DB Details as mention in Running locally part)
  95
  96  sudo docker run -d -p 8085:8085/tcp -e URL_JDBC=jdbc:postgresql://10.53.172.138:5432/postgres -e JDBC_USERNAME=postgres -e JDBC_PASSWORD=root -e DMAAPHOST=10.53.172.156 -e CONSUL_HOST=10.53.172.109 -e HOSTNAME=static-dcaegen2-services-mua -e MR_DEFAULT_PORT_NUMBER=3904 -e CONFIG_BINDING_SERVICE=config_binding_service nexus3.onap.org:10003/onap/org.onap.dcaegen2.services.mapper.vesadapter.universalvesadaptor:latest
  97
  98 3)      Go inside container and tail /opt/app/VESCollector/logs/vesadaper.log
  99 4)      Post SNMP event JSON to DMaaP Topic ONAP-COLLECTOR-SNMPTRAP
 100 5) Subscribe to DMaaP topic unauthenticated.SEC_FAULT_OUTPUT you will get process VES JSON to this topic.
 101 ```