1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
2 .. http://creativecommons.org/licenses/by/4.0
3 .. (c) Anuket and others
4 .. _barometer-oneclick-userguide:
6 ========================================
7 Anuket Barometer One Click Install Guide
8 ========================================
14 The intention of this user guide is to outline how to use the ansible
15 playbooks for a one click installation of Barometer. A more in-depth
16 installation guide is available with the
17 :ref:`Docker user guide <barometer-docker-userguide>`.
20 One Click Install with Ansible
21 ------------------------------
24 Proxy for package manager on host
25 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
27 This step has to be performed only if host is behind HTTP/HTTPS proxy
29 Proxy URL have to be set in dedicated config file
31 1. CentOS - ``/etc/yum.conf``
35 proxy=http://your.proxy.domain:1234
37 2. Ubuntu - ``/etc/apt/apt.conf``
41 Acquire::http::Proxy "http://your.proxy.domain:1234"
43 After update of config file, apt mirrors have to be updaited via
50 Proxy environment variables (for docker and pip)
51 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
53 This step has to be performed only if host is behind HTTP/HTTPS proxy
55 Configuring proxy for packaging system is not enough, also some proxy
56 environment variables have to be set in the system before ansible scripts
58 Barometer configures docker proxy automatically via ansible task as a part
59 of *one click install* process - user only has to provide proxy URL using common
60 shell environment variables and ansible will automatically configure proxies
61 for docker(to be able to fetch barometer images). Another component used by
62 ansible (e.g. pip is used for downloading python dependencies) will also benefit
63 from setting proxy variables properly in the system.
65 Proxy variables used by ansible One Click Install:
71 Variables mentioned above have to be visible for superuser (because most
72 actions involving ``ansible-barometer`` installation require root privileges).
73 Proxy variables are commonly defined in ``/etc/environment`` file (but any other
74 place is good as long as variables can be seen by commands using ``su``).
76 Sample proxy configuration in ``/etc/environment``:
80 http_proxy=http://your.proxy.domain:1234
81 https_proxy=http://your.proxy.domain:1234
82 ftp_proxy=http://your.proxy.domain:1234
88 * sudo permissions or root access are required to install ansible.
89 * ansible version needs to be 2.4+, because usage of import/include statements
91 The following steps have been verified with Ansible 2.6.3 on Ubuntu 16.04 and 18.04.
92 To install Ansible 2.6.3 on Ubuntu:
96 $ sudo apt-get install python
97 $ sudo apt-get install python-pip
98 $ sudo -H pip install 'ansible==2.6.3'
99 $ sudo apt-get install git
101 The following steps have been verified with Ansible 2.6.3 on Centos 7.5.
102 To install Ansible 2.6.3 on Centos:
106 $ sudo yum install python
107 $ sudo yum install epel-release
108 $ sudo yum install python-pip
109 $ sudo -H pip install 'ansible==2.6.3'
110 $ sudo yum install git
113 When using multi-node-setup, please make sure that ``python`` package is
114 installed on all of the target nodes (ansible during 'Gathering facts'
115 phase is using ``python2`` and it may not be installed by default on some
116 distributions - e.g. on Ubuntu 16.04 it has to be installed manually)
123 $ git clone https://gerrit.opnfv.org/gerrit/barometer
126 Install ansible dependencies
127 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
129 To run the ansible playbooks for the one-click install, additional dependencies are needed.
130 There are listed in requirements.yml and can be installed using::
132 $ ansible-galaxy install -r $barometer_dir/requirements.yml
137 Edit inventory file and add hosts:
138 ``$barometer_dir/docker/ansible/default.inv``
145 [collectd_hosts:vars]
147 insert_ipmi_modules=true
148 #to use master or experimental container set the collectd flavor below
149 #possible values: stable|master|experimental
153 #hostname or ip must be used.
154 #using localhost will cause issues with collectd network plugin.
158 #NOTE: As per current support, Grafana and Influxdb should be same host.
165 #NOTE: currently one zookeeper host is supported
174 Change localhost to different hosts where neccessary.
175 Hosts for influxdb and grafana are required only for ``collectd_service.yml``.
176 Hosts for zookeeper, kafka and ves are required only for ``collectd_ves.yml``.
179 Zookeeper, Kafka and VES need to be on the same host, there is no
180 support for multi node setup.
182 To change host for kafka edit ``kafka_ip_addr`` in
183 ``./roles/config_files/vars/main.yml``.
185 Additional plugin dependencies
186 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
188 By default ansible will try to fulfill dependencies for ``mcelog`` and
189 ``ipmi`` plugin. For ``mcelog`` plugin it installs mcelog daemon. For ipmi it
190 tries to insert ``ipmi_devintf`` and ``ipmi_si`` kernel modules.
191 This can be changed in inventory file with use of variables ``install_mcelog``
192 and ``insert_ipmi_modules``, both variables are independent:
196 [collectd_hosts:vars]
198 insert_ipmi_modules=false
201 On Ubuntu 18.04 the deb package for mcelog daemon is not available in official
202 Ubuntu repository. In that case ansible scripts will try to download, make and
203 install the daemon from mcelog git repository.
208 Generate ssh keys if not present, otherwise move onto next step.
209 ssh keys are required for Ansible to connect the host you use for Barometer Installation.
215 Copy ssh key to all target hosts. It requires to provide root password.
216 The example is for ``localhost``.
221 $ ssh-copy-id root@localhost
223 Verify that key is added and password is not required to connect.
227 $ sudo ssh root@localhost
230 Keys should be added to every target host and [localhost] is only used as an
231 example. For multinode installation keys need to be copied for each node:
232 [collectd_hostname], [influxdb_hostname] etc.
234 Build the Collectd containers
235 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
237 This is an optional step, if you do not wish to build the containers locally, please continue to `Download and run Collectd+Influxdb+Grafana containers`_.
238 This step will build the container images locally, allowing for testing of new changes to collectd.
239 This is particularly useful for the ``experimental`` flavour for testing PRs, and for building a ``collectd-6`` container.
241 To run the playbook and build the containers, run::
242 sudo ansible-playbook docker/ansible/collectd_build.yml
244 By default, all contaienrs will be built.
245 Since this can take a while, it is recommended that you choose a flavor to build using tags::
247 sudo ansible-playbook docker/ansible/collectd_build.yml --tags='collectd-6,latest'
249 The available tags are:
251 * *stable* builds the ``barometer-collectd`` image
252 * *latest* builds the ``barometer-collectd-latest`` image
253 * *experimental* builds the ``barometer-collectd-experimental`` container, with optional PRs
254 * *collectd-6* builds the ``baromter-collectd-6`` container, with optional PR(s)
256 * *flask_test* builds a small webapp that displays the metrics sent via the write_http plugin
259 The flask_test tag must be explicitly enabled.
260 This can be done either through the ``--tags='flask_test'`` (to build just
261 this container) or with ``--tags=all`` to build this and all the other
264 Download and run Collectd+Influxdb+Grafana containers
265 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
267 The One Click installation features easy and scalable deployment of Collectd,
268 Influxdb and Grafana containers using Ansible playbook. The following steps goes
269 through more details.
273 $ sudo -H ansible-playbook -i default.inv collectd_service.yml
275 Check the three containers are running, the output of ``docker ps`` should be similar to:
280 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
281 4c2143fb6bbd anuket/barometer-grafana "/run.sh" 59 minutes ago Up 4 minutes bar-grafana
282 5e356cb1cb04 anuket/barometer-influxdb "/entrypoint.sh infl…" 59 minutes ago Up 4 minutes bar-influxdb
283 2ddac8db21e2 anuket/barometer-collectd "/run_collectd.sh" About an hour ago Up 4 minutes bar-collectd
285 To make some changes when a container is running run:
289 $ sudo docker exec -ti <CONTAINER ID> /bin/bash
291 Connect to ``<host_ip>:3000`` with a browser and log into Grafana: admin/admin.
292 For short introduction please see the:
293 `Grafana guide <https://grafana.com/docs/grafana/latest/guides/getting_started/>`_.
295 The collectd configuration files can be accessed directly on target system in
296 ``/opt/collectd/etc/collectd.conf.d``. It can be used for manual changes or
297 enable/disable plugins. If configuration has been modified it is required to
302 $ sudo docker restart bar-collectd
304 Download and run collectd+kafka+ves containers
305 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
309 $ sudo ansible-playbook -i default.inv collectd_ves.yml
311 Check the containers are running, the output of ``docker ps`` should be similar to:
316 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
317 d041d8fff849 zookeeper:3.4.11 "/docker-entrypoint.…" 2 minutes ago Up 2 minutes bar-zookeeper
318 da67b81274bc anuket/barometer-ves "./start_ves_app.sh …" 2 minutes ago Up 2 minutes bar-ves
319 2c25e0c79f93 anuket/barometer-kafka "/src/start_kafka.sh" 2 minutes ago Up 2 minutes bar-kafka
320 b161260c90ed anuket/barometer-collectd "/run_collectd.sh" 2 minutes ago Up 2 minutes bar-collectd
323 To make some changes when a container is running run:
327 $ sudo docker exec -ti <CONTAINER ID> /bin/bash
329 List of default plugins for collectd container
330 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
332 From Jerma release, the supported dpdk version is 19.11
334 If you would like to use v18.11, make the following changes:
336 1. Update the dpdk version to v18.11 in ``<barometer>/src/package-list.mk``
337 2. Replace all ``common_linux`` string with ``common_linuxapp`` in ``<barometer>/src/dpdk/Makefile``
339 If you would like to downgrade to a version lower than v18.11, make the following changes:
341 1. Update the dpdk version to a version lower than v18.11 (e.g.:- v16.11) in ``<barometer>/src/package-list.mk``
342 2. Replace all ``common_linux`` string with ``common_linuxapp`` in ``<barometer>/src/dpdk/Makefile``
343 3. Change the Makefile path from ``(WORKDIR)/kernel/linux/kni/Makefile`` to ``(WORKDIR)/lib/librte_eal/linuxapp/kni/Makefile`` in ``(WORK_DIR)/src/dpdk/Makefile``.
345 By default the collectd is started with default configuration which includes
346 the following plugins:
348 * ``csv``, ``contextswitch``, ``cpu``, ``cpufreq``, ``df``, ``disk``,
349 ``ethstat``, ``ipc``, ``irq``, ``load``, ``memory``, ``numa``,
350 ``processes``, ``swap``, ``turbostat``, ``uuid``, ``uptime``, ``exec``,
351 ``hugepages``, ``intel_pmu``, ``ipmi``, ``write_kafka``, ``logfile``,
352 ``logparser``, ``mcelog``, ``network``, ``intel_rdt``, ``rrdtool``,
353 ``snmp_agent``, ``syslog``, ``virt``, ``ovs_stats``, ``ovs_events``,
357 Some of the plugins are loaded depending on specific system requirements and can be omitted if
358 dependency is not met, this is the case for:
360 * ``hugepages``, ``ipmi``, ``mcelog``, ``intel_rdt``, ``virt``, ``ovs_stats``, ``ovs_events``
362 For instructions on how to disable certain plugins see the `List and description of tags used in ansible scripts`_ section.
364 List and description of tags used in ansible scripts
365 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
367 Tags can be used to run a specific part of the configuration without running
368 the whole playbook. To run a specific parts only:
372 $ sudo ansible-playbook -i default.inv collectd_service.yml --tags "syslog,cpu,uuid"
374 To disable some parts or plugins:
378 $ sudo ansible-playbook -i default.inv collectd_service.yml --skip-tags "en_default_all,syslog,cpu,uuid"
380 List of available tags:
383 Install docker and required dependencies with package manager.
386 Configure proxy file for docker service if proxy is set on host environment.
389 Remove collectd config files.
391 ``copy_additional_configs``
392 Copy additional configuration files to target system. Path to additional
393 configuration is stored in
394 ``$barometer_dir/docker/ansible/roles/config_files/docs/main.yml`` as
395 ``additional_configs_path``.
398 Set of default read plugins: ``contextswitch``, ``cpu``, ``cpufreq``, ``df``,
399 ``disk``, ``ethstat``, ``ipc``, ``irq``, ``load``, ``memory``, ``numa``,
400 ``processes``, ``swap``, ``turbostat``, ``uptime``.
403 The following tags can be used to enable/disable plugins: ``csv``,
404 ``contextswitch``, ``cpu``, ``cpufreq``, ``df``, ``disk,`` ``ethstat``,
405 ``ipc``, ``irq``, ``load``, ``memory``, ``numa``, ``processes``, ``swap``,
406 ``turbostat``, ``uptime``, ``exec``, ``hugepages``, ``ipmi``, ``kafka``,
407 ``logfile``, ``logparser``, ``mcelog``, ``network``, ``pmu``, ``rdt``,
408 ``rrdtool``, ``snmp``, ``syslog``, ``unixsock``, ``virt``, ``ovs_stats``,
409 ``ovs_events``, ``uuid``, ``dpdk_telemetry``.