Adds osm-common dependency
[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 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