1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
2 .. http://creativecommons.org/licenses/by/4.0
3 .. (c) <optionally add copywriters name>
4 .. _barometer-oneclick-userguide:
6 =======================================
7 OPNFV Barometer One Click Install Guide
8 =======================================
14 The intention of this user guide is to outline how to use the ansible playbooks for a one click installation of Barometer. A more in-depth installation guide is available with the :ref:`Docker user guide <barometer-docker-userguide>`.
17 One Click Install with Ansible
18 ------------------------------
21 Proxy for package manager on host
22 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
24 This step has to be performed only if host is behind HTTP/HTTPS proxy
26 Proxy URL have to be set in dedicated config file
28 1. CentOS - /etc/yum.conf
32 proxy=http://your.proxy.domain:1234
34 2. Ubuntu - /etc/apt/apt.conf
38 Acquire::http::Proxy "http://your.proxy.domain:1234"
40 After update of config file, apt mirrors have to be updated via 'apt-get update'
46 Proxy environment variables (for docker and pip)
47 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
49 This step has to be performed only if host is behind HTTP/HTTPS proxy
51 Configuring proxy for packaging system is not enough, also some proxy
52 environment variables have to be set in the system before ansible scripts
54 Barometer configures docker proxy automatically via ansible task as a part
55 of 'one click install' process - user only has to provide proxy URL using common
56 shell environment variables and ansible will automatically configure proxies
57 for docker(to be able to fetch barometer images). Another component used by
58 ansible (e.g. pip is used for downloading python dependencies) will also benefit
59 from setting proxy variables properly in the system.
61 Proxy variables used by ansible One Click Install:
67 Variables mentioned above have to be visible for superuser (because most
68 actions involving ansible-barometer installation require root privileges).
69 Proxy variables are commonly defined in '/etc/environment' file (but any other
70 place is good as long as variables can be seen by commands using 'su').
72 Sample proxy configuration in /etc/environment:
76 http_proxy=http://your.proxy.domain:1234
77 https_proxy=http://your.proxy.domain:1234
78 ftp_proxy=http://your.proxy.domain:1234
84 * sudo permissions or root access are required to install ansible.
85 * ansible version needs to be 2.4+, because usage of import/include statements
87 The following steps have been verified with Ansible 2.6.3 on Ubuntu 16.04 and 18.04.
88 To install Ansible 2.6.3 on Ubuntu:
92 $ sudo apt-get install python
93 $ sudo apt-get install python-pip
94 $ sudo -H pip install 'ansible==2.6.3'
95 $ sudo apt-get install git
97 The following steps have been verified with Ansible 2.6.3 on Centos 7.5.
98 To install Ansible 2.6.3 on Centos:
102 $ sudo yum install python
103 $ sudo yum install epel-release
104 $ sudo yum install python-pip
105 $ sudo -H pip install 'ansible==2.6.3'
106 $ sudo yum install git
109 When using multi-node-setup, please make sure that 'python' package is
110 installed on all of the target nodes (ansible during 'Gathering facts'
111 phase is using python2 and it may not be installed by default on some
112 distributions - e.g. on Ubuntu 16.04 it has to be installed manually)
119 $ git clone https://gerrit.opnfv.org/gerrit/barometer
120 $ cd barometer/docker/ansible
124 Edit inventory file and add hosts: $barometer_dir/docker/ansible/default.inv
131 [collectd_hosts:vars]
133 insert_ipmi_modules=true
134 #to use master or experimental container set the collectd flavor below
135 #possible values: stable|master|experimental
139 #hostname or ip must be used.
140 #using localhost will cause issues with collectd network plugin.
144 #NOTE: As per current support, Grafana and Influxdb should be same host.
151 #NOTE: currently one zookeeper host is supported
160 Change localhost to different hosts where neccessary.
161 Hosts for influxdb and grafana are required only for collectd_service.yml.
162 Hosts for zookeeper, kafka and ves are required only for collectd_ves.yml.
165 Zookeeper, Kafka and VES need to be on the same host, there is no
166 support for multi node setup.
168 To change host for kafka edit kafka_ip_addr in ./roles/config_files/vars/main.yml.
170 Additional plugin dependencies
171 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
173 By default ansible will try to fulfill dependencies for mcelog and ipmi plugin.
174 For mcelog plugin it installs mcelog daemon. For ipmi it tries to insert ipmi_devintf
175 and ipmi_si kernel modules.
176 This can be changed in inventory file with use of variables install_mcelog
177 and insert_ipmi_modules, both variables are independent:
181 [collectd_hosts:vars]
183 insert_ipmi_modules=false
186 On Ubuntu 18.04 the deb package for mcelog daemon is not available in official
187 Ubuntu repository. In that case ansible scripts will try to download, make and
188 install the daemon from mcelog git repository.
193 Generate ssh keys if not present, otherwise move onto next step.
194 ssh keys are required for Ansible to connect the host you use for Barometer Installation.
200 Copy ssh key to all target hosts. It requires to provide root password.
201 The example is for localhost.
206 $ ssh-copy-id root@localhost
208 Verify that key is added and password is not required to connect.
212 $ sudo ssh root@localhost
215 Keys should be added to every target host and [localhost] is only used as an
216 example. For multinode installation keys need to be copied for each node:
217 [collectd_hostname], [influxdb_hostname] etc.
219 Download and run Collectd+Influxdb+Grafana containers
220 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
222 The One Click installation features easy and scalable deployment of Collectd,
223 Influxdb and Grafana containers using Ansible playbook. The following steps goes
224 through more details.
228 $ sudo -H ansible-playbook -i default.inv collectd_service.yml
230 Check the three containers are running, the output of docker ps should be similar to:
235 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
236 a033aeea180d opnfv/barometer-grafana "/run.sh" 9 days ago Up 7 minutes bar-grafana
237 1bca2e4562ab opnfv/barometer-influxdb "/entrypoint.sh in..." 9 days ago Up 7 minutes bar-influxdb
238 daeeb68ad1d5 opnfv/barometer-collectd "/run_collectd.sh ..." 9 days ago Up 7 minutes bar-collectd
240 To make some changes when a container is running run:
244 $ sudo docker exec -ti <CONTAINER ID> /bin/bash
246 Connect to <host_ip>:3000 with a browser and log into Grafana: admin/admin.
247 For short introduction please see the:
248 `Grafana guide <http://docs.grafana.org/guides/getting_started/>`_.
250 The collectd configuration files can be accessed directly on target system in '/opt/collectd/etc/collectd.conf.d'.
251 It can be used for manual changes or enable/disable plugins. If configuration has been modified it is required to
256 $ sudo docker restart bar-collectd
258 Download and run collectd+kafka+ves containers
259 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
263 $ sudo ansible-playbook -i default.inv collectd_ves.yml
265 Check the containers are running, the output of docker ps should be similar to:
270 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
271 29035be2dab5 zookeeper:3.4.11 "/docker-entrypoint._" 7 minutes ago Up 7 minutes bar-zookeeper
272 eb8bba3c0b76 opnfv/barometer-ves "./start_ves_app.s..." 6 minutes ago Up 6 minutes bar-ves
273 86702a96a68c opnfv/barometer-kafka "/src/start_kafka.sh" 6 minutes ago Up 6 minutes bar-kafka
274 daeeb68ad1d5 opnfv/barometer-collectd "/run_collectd.sh ..." 6 minutes ago Up 6 minutes bar-collectd
277 To make some changes when a container is running run:
281 $ sudo docker exec -ti <CONTAINER ID> /bin/bash
283 List of default plugins for collectd container
284 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
286 The dpdk plugins dpdkevents and dpdkstat were tested with DPDK v16.11.
288 By default the collectd is started with default configuration which includes the followin plugins:
289 * csv, contextswitch, cpu, cpufreq, df, disk, ethstat, ipc, irq, load, memory, numa, processes,
290 swap, turbostat, uuid, uptime, exec, hugepages, intel_pmu, ipmi, write_kafka, logfile, mcelog,
291 network, intel_rdt, rrdtool, snmp_agent, syslog, virt, ovs_stats, ovs_events, dpdkevents,
294 Some of the plugins are loaded depending on specific system requirements and can be omitted if
295 dependency is not met, this is the case for:
296 * hugepages, ipmi, mcelog, intel_rdt, virt, ovs_stats, ovs_events
298 List and description of tags used in ansible scripts
299 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
301 Tags can be used to run a specific part of the configuration without running the whole playbook.
302 To run a specific parts only:
306 $ sudo ansible-playbook -i default.inv collectd_service.yml --tags "syslog,cpu,uuid"
308 To disable some parts or plugins:
312 $ sudo ansible-playbook -i default.inv collectd_service.yml --skip-tags "en_default_all,syslog,cpu,uuid"
314 List of available tags:
317 Install docker and required dependencies with package manager.
320 Configure proxy file for docker service if proxy is set on host environment.
323 Remove collectd config files.
325 copy_additional_configs
326 Copy additional configuration files to target system. Path to additional configuration
327 is stored in $barometer_dir/docker/ansible/roles/config_files/vars/main.yml as additional_configs_path.
330 Set of default read plugins: contextswitch, cpu, cpufreq, df, disk, ethstat, ipc, irq,
331 load, memory, numa, processes, swap, turbostat, uptime.
334 The following tags can be used to enable/disable plugins: csv, contextswitch, cpu,
335 cpufreq, df, disk, ethstat, ipc, irq, load, memory, numa, processes, swap, turbostat,
336 uptime, exec, hugepages, ipmi, kafka, logfile, mcelogs, network, pmu, rdt, rrdtool,
337 snmp, syslog, virt, ovs_stats, ovs_events, uuid, dpdkevents, dpdkstat.