From 375f07c018e209ae54391d4d0cb4898d4bdb79b4 Mon Sep 17 00:00:00 2001 From: Helena McGough Date: Fri, 13 Oct 2017 16:14:16 +0100 Subject: [PATCH] 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 --- README.rst | 4 +- doc/MON_install_guide.rst | 117 ++++++++++++++++++ doc/MON_usage_guide.rst | 95 ++++++++++++++ .../OpenStack/aodh_plugin_guide.rst | 8 ++ .../OpenStack/gnocchi_plugin_guide.rst | 0 .../OpenStack/openstack_plugins.rst | 0 plugins/OpenStack/Aodh/plugin_instance.py | 3 + plugins/OpenStack/Gnocchi/plugin_instance.py | 3 + scripts/install_mon.sh | 40 ++++++ 9 files changed, 268 insertions(+), 2 deletions(-) create mode 100644 doc/MON_install_guide.rst create mode 100644 doc/MON_usage_guide.rst rename doc/{plugins => }/OpenStack/aodh_plugin_guide.rst (89%) rename doc/{plugins => }/OpenStack/gnocchi_plugin_guide.rst (100%) rename doc/{plugins => }/OpenStack/openstack_plugins.rst (100%) create mode 100644 scripts/install_mon.sh diff --git a/README.rst b/README.rst index 99a910a..9093b6d 100644 --- a/README.rst +++ b/README.rst @@ -42,11 +42,11 @@ The MON module communication is classified as 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. +: `` + + +For information on how to use this module refer to this usage guide: +: `` + + +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: +: ``. + +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: +: `` + +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 89% 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 @@ metrics: | 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 -- 2.25.1