doc/MON_install_guide.rst

   1 ..
   2        # Copyright 2017 Intel Research and Development Ireland Limited
   3        # *************************************************************
   4        # This file is part of OSM Monitoring module
   5        # All Rights Reserved to Intel Corporation
   6        #
   7        # Licensed under the Apache License, Version 2.0 (the "License"); you
   8        # may not use this file except in compliance with the License. You may
   9        # obtain a copy of the License at
  10        #
  11        #         http://www.apache.org/licenses/LICENSE-2.0
  12        #
  13        # Unless required by applicable law or agreed to in writing, software
  14        # distributed under the License is distributed on an "AS IS" BASIS,
  15        # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
  16        # implied. See the License for the specific language governing
  17        # permissions and limitations under the License.
  18        #
  19        # For those usages not covered by the Apache License, Version 2.0 please
  20        # contact: helena.mcgough@intel.com or adrian.hoban@intel.com
  21
  22 OSM MON module
  23 **************
  24 This is a guide for using the OSM MON module source code to create a container
  25 for monitoring. It will allow the use of the three plugins available to the
  26 module; CloudWatch, OpenStack and vROPs.
  27
  28
  29 At the moment this process requires a number of steps, but in the future the
  30 process will become automated as it will become part of the osm installation
  31 script which is contained within the devops repo.
  32 : `</devops/installers/install_mon.sh>`
  33
  34
  35 For information on how to use this module refer to this usage guide:
  36 : `</MON/doc/MON_usage_guide.rst>`
  37
  38
  39 You can find the source code for MON by following the link below:
  40 https://osm.etsi.org/gitweb/?p=osm/MON.git;a=tree
  41
  42
  43 Requirements
  44 ------------
  45 * lxc setup
  46 * OSM deployment
  47
  48
  49 Creating a MON Container
  50 ------------------------
  51 To create a MON container and utilize the supported functionality, clone the
  52 MON repo and then run the provided script for container creation and
  53 installation:
  54
  55     ::
  56
  57         git clone https://osm.etsi.org/gerrit/osm/MON.git
  58         cd MON/scripts
  59         . install_mon.sh
  60
  61 This script will create a MON container, install all of the required packages,
  62 as well as initializing the Apache Kafka and the vROPs web service.
  63
  64
  65 Plugin Utilization
  66 ------------------
  67 There are three plugins supported by this monitoring module; CloudWatch,
  68 OpenStack and vROPs.
  69
  70 vROPs plugin
  71 ~~~~~~~~~~~~
  72 The vROPs plugin will automatically be installed after you have run the above
  73 installation script.
  74
  75 OpenStack Plugin
  76 ~~~~~~~~~~~~~~~~
  77 There are two OpenStack services supported within this module monitoring and
  78 alarming, which are supported by the Gnocchi and Aodh plugins respectively.
  79
  80 For more information on what metrics and alarms that these plugins support
  81 please refer to the following documentation:
  82 : `</MON/doc/OpenStack/>`.
  83
  84 These documents will also describe what alarming and monitoring functionality
  85 the plugins support.
  86
  87 The following steps will allow you to use the plugins:
  88
  89 * Pass your openstack deployment credentials to the MON container:
  90
  91       ::
  92
  93           lxc exec MON -- export OS_AUTH_URL=<AUTH_URL>
  94           lxc exec MON -- export OS_PASSWORD=<PASSWORD>
  95           lxc exec MON -- export OS_TENANT_NAME=<TENANT_NAME>
  96           lxc exec MON -- export OS_USERNAME=<USER_NAME>
  97
  98 * The Gnocchi and Aodh plugins work from a common KafkaConsumer that checks for
  99   the appropriate topics and keys. To run this consumer:
 100
 101       ::
 102
 103           lxc exec MON -- nohup python /root/MON/osm_mon/core/message_bus/common_consumer.py > /root/MON_plugins.log 2>&1 &
 104
 105 * To enable Aodh alarm notifications to be sent to SO:
 106
 107       ::
 108
 109           lxc exec MON - nohup python /root/MON/osm_mon/plugins/OpenStack/Aodh/notifier.py &
 110
 111 CloudWatch
 112 ~~~~~~~~~~
 113 The MON container supports a CloudWatch plugin on installation.
 114
 115
 116 Verification
 117 ------------
 118 * To confirm that you have created your MON container, run the following command
 119   and confirm that your container is in a RUNNING state:
 120
 121     ::
 122
 123         lxc list | grep MON
 124
 125 * Confirm that the kafka service is installed and running within the container:
 126
 127     ::
 128
 129         lxc exec MON -- service kafka status
 130
 131 * To check the logs of the plugins:
 132
 133     ::
 134
 135         lxc exec MON -- tail -f /root/MON_plugins.log