Include documentation and updates for MON manual installation.
- Provided documentation that can be included in the wiki
- Include installation for manual MON installation
Signed-off-by: Helena McGough <helena.mcgough@intel.com>
diff --git a/README.rst b/README.rst
index 99a910a..9093b6d 100644
--- a/README.rst
+++ b/README.rst
@@ -42,11 +42,11 @@
Supported Plugins
******************
-Supported VIMs are OpenStack, VMWare, AWS for now.MON can send/receive metrics
+Supported VIMs are OpenStack, VMWare, AWS for now. MON can send/receive metrics
and alarms from the following plugins in this release.
- Gnocchi, Aodh (OpenStack)
- - vrOps (VMWare)
+ - vROps (VMWare)
- CloudWatch (AWS)
Developers
diff --git a/doc/MON_install_guide.rst b/doc/MON_install_guide.rst
new file mode 100644
index 0000000..586fe2a
--- /dev/null
+++ b/doc/MON_install_guide.rst
@@ -0,0 +1,117 @@
+..
+ # Copyright 2017 Intel Research and Development Ireland Limited
+ # *************************************************************
+ # This file is part of OSM Monitoring module
+ # All Rights Reserved to Intel Corporation
+ #
+ # Licensed under the Apache License, Version 2.0 (the "License"); you
+ # may not use this file except in compliance with the License. You may
+ # obtain a copy of the License at
+ #
+ # http://www.apache.org/licenses/LICENSE-2.0
+ #
+ # Unless required by applicable law or agreed to in writing, software
+ # distributed under the License is distributed on an "AS IS" BASIS,
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ # implied. See the License for the specific language governing
+ # permissions and limitations under the License.
+ #
+ # For those usages not covered by the Apache License, Version 2.0 please
+ # contact: helena.mcgough@intel.com or adrian.hoban@intel.com
+
+OSM MON module
+**************
+This is a guide for using the OSM MON module source code to create a container
+for monitoring. It will allow the use of the three plugins available to the
+module; CloudWatch, OpenStack and vROPs.
+
+
+At the moment this process requires a number of steps, but in the future the
+process will become automated as it will become part of the osm installation
+script which is contained within the devops repo.
+: `</devops/installers/install_mon.sh>`
+
+
+For information on how to use this module refer to this usage guide:
+: `</MON/doc/MON_usage_guide.rst>`
+
+
+You can find the source code for MON by following the link below:
+https://osm.etsi.org/gitweb/?p=osm/MON.git;a=tree
+
+
+Requirements
+------------
+* lxc setup
+* OSM deployment
+
+
+Creating a MON Container
+------------------------
+To create a MON container and utilize the supported functionality, clone the
+MON repo and then run the provided script for container creation and
+installation:
+
+ ::
+
+ git clone https://osm.etsi.org/gerrit/osm/MON.git
+ cd MON/scripts
+ . install_mon.sh
+
+This script will create a MON container, install all of the required packages,
+as well as initializing the Apache Kafka and the vROPs web service.
+
+
+Plugin Utilization
+------------------
+There are three plugins supported by this monitoring module; CloudWatch,
+OpenStack and vROPs.
+
+vROPs plugin
+~~~~~~~~~~~~
+The vROPs plugin will automatically be installed after you have run the above
+installation script.
+
+OpenStack Plugin
+~~~~~~~~~~~~~~~~
+There are two OpenStack services supported within this module monitoring and
+alarming, which are supported by the Gnocchi and Aodh plugins respectively.
+
+For more information on what metrics and alarms that these plugins support
+please refer to the following documentation:
+: `</MON/doc/OpenStack/>`.
+
+These documents will also describe what alarming and monitoring functionality
+the plugins support.
+
+* To run the Gnocchi plugin run the following command:
+
+ ::
+
+ lxc exec MON - python /root/MON/plugins/OpenStack/Gnocchi/plugin_instance.py
+
+* To run the Aodh plugin run the following command:
+
+ ::
+
+ lxc exec MON - python /root/MON/plugins/OpenStack/Aodh/plugin_instance.py
+
+CloudWatch
+~~~~~~~~~~
+The MON container supports a CloudWatch plugin as well.
+
+
+Verification
+------------
+* To confirm that you have created your MON container, run the following command
+ and confirm that your container is in a RUNNING state:
+
+ ::
+
+ lxc list | grep MON
+
+* Confirm that the kafka service is installed and running within the container:
+
+ ::
+
+ lxc exec MON -- service kafka status
diff --git a/doc/MON_usage_guide.rst b/doc/MON_usage_guide.rst
new file mode 100644
index 0000000..0a28318
--- /dev/null
+++ b/doc/MON_usage_guide.rst
@@ -0,0 +1,95 @@
+..
+ # Copyright 2017 Intel Research and Development Ireland Limited
+ # *************************************************************
+ # This file is part of OSM Monitoring module
+ # All Rights Reserved to Intel Corporation
+ #
+ # Licensed under the Apache License, Version 2.0 (the "License"); you
+ # may not use this file except in compliance with the License. You may
+ # obtain a copy of the License at
+ #
+ # http://www.apache.org/licenses/LICENSE-2.0
+ #
+ # Unless required by applicable law or agreed to in writing, software
+ # distributed under the License is distributed on an "AS IS" BASIS,
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ # implied. See the License for the specific language governing
+ # permissions and limitations under the License.
+ #
+ # For those usages not covered by the Apache License, Version 2.0 please
+ # contact: helena.mcgough@intel.com or adrian.hoban@intel.com
+
+MON Usage Guide
+***************
+This is a guide on how to use the MON module and its three plugins.
+
+The MON module sends requests to an from the SO via an Apache Kafka message
+bus. Currently each message is sent on the message bus in json format, along
+with a unique request key and its topic.
+
+The topics that the plugins will consume messages based on are:
+
+* alarm_request
+* metric_request
+
+In return the plugins will send messages back to the SO with the following
+topics:
+
+* alarm_response
+* metric_response
+
+Each type of request has it's own unique key:
+* create_alarm_request
+* create_metric_request
+* list_alarm_request
+* list_metric_request
+* delete_alarm_request
+* delete_metric_request
+* update_alarm_request
+* update_metric_request
+* acknowledge_alarm_request
+* read_metric_data_request
+
+Sending Messages
+----------------
+For each of the request message that can be sent there is a json schema defined
+in the models directory of the MON repo:
+: `</MON/core/models/>`
+
+To send a valid message to the MON module for use by one of the plugins, your
+message must match the json schema for that request type.
+
+Once you have created a valid json object with your message you can send it on
+the message bus with the required topic and key.
+
+To ensure that the correct plugin uses your message you must also specify the
+vim_type correctly:
+
+ +----------------------+----------------------+
+ | Plugin | vim_type |
+ +----------------------+----------------------+
+ | CloudWatch | cloudwatch |
+ | | |
+ | OpenStack | openstack |
+ | | |
+ | vROPs | vrops |
+ +----------------------+----------------------+
+
+
+* Example
+ A create alarm request for the vROPs plugin would be sent with the following
+ information:
+
+ - topic: alarm_request
+ - create_alarm_request
+ - message: a valid message that matches the json schema, with the vim_type
+ specified as vrops
+
+A KafkaProducer is used to send the message and it will be consumed by a
+KafkaConsumer which is running for each plugin
+
+
+ .. note::
+
+ The SO support for sending and receiving messages is currently not
+ supported. Support will be added in a later release.
diff --git a/doc/plugins/OpenStack/aodh_plugin_guide.rst b/doc/OpenStack/aodh_plugin_guide.rst
similarity index 88%
rename from doc/plugins/OpenStack/aodh_plugin_guide.rst
rename to doc/OpenStack/aodh_plugin_guide.rst
index b19eca3..544a8e8 100644
--- a/doc/plugins/OpenStack/aodh_plugin_guide.rst
+++ b/doc/OpenStack/aodh_plugin_guide.rst
@@ -36,13 +36,21 @@
| Gnocchi Metric | Aodh Alarm |
+-----------------------------+---------------------------------+
| AVERAGE_MEMORY_UTILIZATION | AVERAGE_MEMORY_UTILIZATION |
+ | | |
| DISK_READ_OPS | DISK_READ_OPS |
+ | | |
| DISK_WRITE_OPS | DISK_WRITE_OPS |
+ | | |
| DISK_READ_BYTES | DISK_READ_BYTES |
+ | | |
| DISK_WRITE_BYTES | DISK_WRITE_BYTES |
+ | | |
| PACKETS_DROPPED | NET_PACKETS_DROPPED |
+ | | |
| PACKETS_RECEIVED | PACKETS_IN_ABOVE_THRESHOLD |
+ | | |
| PACKETS_SENT | PACKETS_OUT_ABOVE_THRESHOLD |
+ | | |
| CPU_UTILIZATION | CPU_UTILIZATION_ABOVE_THRESHOLD |
+-----------------------------+---------------------------------+
diff --git a/doc/plugins/OpenStack/gnocchi_plugin_guide.rst b/doc/OpenStack/gnocchi_plugin_guide.rst
similarity index 100%
rename from doc/plugins/OpenStack/gnocchi_plugin_guide.rst
rename to doc/OpenStack/gnocchi_plugin_guide.rst
diff --git a/doc/plugins/OpenStack/openstack_plugins.rst b/doc/OpenStack/openstack_plugins.rst
similarity index 100%
rename from doc/plugins/OpenStack/openstack_plugins.rst
rename to doc/OpenStack/openstack_plugins.rst
diff --git a/plugins/OpenStack/Aodh/plugin_instance.py b/plugins/OpenStack/Aodh/plugin_instance.py
index aaba1e4..b3a02ac 100644
--- a/plugins/OpenStack/Aodh/plugin_instance.py
+++ b/plugins/OpenStack/Aodh/plugin_instance.py
@@ -22,6 +22,9 @@
"""Aodh plugin for the OSM monitoring module."""
import logging
+import sys
+
+sys.path.append("MON/")
logging.basicConfig(filename='aodh_MON.log', format='%(asctime)s %(message)s',
datefmt='%m/%d/%Y %I:%M:%S %p', filemode='a',
diff --git a/plugins/OpenStack/Gnocchi/plugin_instance.py b/plugins/OpenStack/Gnocchi/plugin_instance.py
index 983af3d..eb8b0e3 100644
--- a/plugins/OpenStack/Gnocchi/plugin_instance.py
+++ b/plugins/OpenStack/Gnocchi/plugin_instance.py
@@ -22,6 +22,9 @@
"""Gnocchi plugin for the OSM monitoring module."""
import logging
+import sys
+
+sys.path.append("MON/")
logging.basicConfig(filename='gnocchi_MON.log', datefmt='%m/%d/%Y %I:%M:%S %p',
format='%(asctime)s %(message)s', filemode='a',
diff --git a/scripts/install_mon.sh b/scripts/install_mon.sh
new file mode 100644
index 0000000..2a99b8a
--- /dev/null
+++ b/scripts/install_mon.sh
@@ -0,0 +1,40 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+# Copyright 2017 Intel Research and Development Ireland Limited
+# *************************************************************
+
+# This file is part of OSM Monitoring module
+# All Rights Reserved to Intel Corporation
+
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+
+# http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitation
+
+# under the License.
+
+# For those usages not covered by the Apache License, Version 2.0 please
+# contact: prithiv.mohan@intel.com or adrian.hoban@intel.com
+
+#__author__ = "Prithiv Mohan"
+#__date__ = "13/Oct/2017"
+
+#This is a temporary installation script for the MON Module. From the next
+#point release, MON will be a part of the OSM Module and can be installed
+#through the install_osm.sh script, just like any other modules.
+
+lxc launch ubuntu:16.04 MON
+lxc exec MON -- apt-get --yes update
+lxc exec MON -- apt-get --yes install git python python-pip libmysqlclient-dev
+lxc exec MON -- git clone https://osm.etsi.org/gerrit/osm/MON.git
+lxc exec MON -- pip install -r /root/MON/requirements.txt
+lxc exec MON -- python /root/MON/kafkad
+lxc exec MON -- . /root/MON/scripts/kafka.sh
+lxc exec MON -- . /root/MON/plugins/vRealiseOps/vROPs_Webservice/install.sh