Updated the manual installation process and documentation
[osm/MON.git] / 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 Gnocchi and Aodh plugins work from a common KafkaConsumer that checks for
88   the appropriate topics and keys. To run this consumer:
89
90       ::
91
92           lxc exec MON -- nohup python /root/MON/osm_mon/core/message_bus/common_consumer &
93
94 * To enable Aodh alarm notifications to be sent to SO:
95
96       ::
97
98           lxc exec MON - nohup python /root/MON/osm_mon/plugins/OpenStack/Aodh/notifier.py &
99
100 CloudWatch
101 ~~~~~~~~~~
102 The MON container supports a CloudWatch plugin on installation.
103
104
105 Verification
106 ------------
107 * To confirm that you have created your MON container, run the following command
108   and confirm that your container is in a RUNNING state:
109
110     ::
111
112         lxc list | grep MON
113
114 * Confirm that the kafka service is installed and running within the container:
115
116     ::
117
118         lxc exec MON -- service kafka status
119
120 * To check the logs of the plugins:
121
122     ::
123
124         lxc exec MON -- tail -f /root/MON_plugins.log