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-docker-userguide:
6 ===================================
7 OPNFV Barometer Docker User Guide
8 ===================================
14 The intention of this user guide is to outline how to install and test the Barometer project's
15 docker images. The `OPNFV docker hub <https://hub.docker.com/u/opnfv/?page=1>`_ contains 5 docker
16 images from the Barometer project:
18 1. `Collectd docker image <https://hub.docker.com/r/opnfv/barometer-collectd/>`_
19 2. `Influxdb docker image <https://hub.docker.com/r/opnfv/barometer-influxdb/>`_
20 3. `Grafana docker image <https://hub.docker.com/r/opnfv/barometer-grafana/>`_
21 4. `Kafka docker image <https://hub.docker.com/r/opnfv/barometer-kafka/>`_
22 5. `VES application docker image <https://hub.docker.com/r/opnfv/barometer-ves/>`_
24 For description of images please see section `Barometer Docker Images Description`_
26 For steps to build and run Collectd image please see section `Build and Run Collectd Docker Image`_
28 For steps to build and run InfluxDB and Grafana images please see section `Build and Run InfluxDB and Grafana Docker Images`_
30 For steps to build and run VES and Kafka images please see section `Build and Run VES and Kafka Docker Images`_
32 For overview of running VES application with Kafka please see the :ref:`VES Application User Guide <barometer-ves-userguide>`
34 Barometer Docker Images Description
35 -----------------------------------
37 .. Describe the specific features and how it is realised in the scenario in a brief manner
38 .. to ensure the user understand the context for the user guide instructions to follow.
40 Barometer Collectd Image
41 ^^^^^^^^^^^^^^^^^^^^^^^^
42 The barometer collectd docker image gives you a collectd installation that includes all
43 the barometer plugins.
46 The Dockerfile is available in the docker/barometer-collectd directory in the barometer repo.
47 The Dockerfile builds a CentOS 7 docker image.
48 The container MUST be run as a privileged container.
50 Collectd is a daemon which collects system performance statistics periodically
51 and provides a variety of mechanisms to publish the collected metrics. It
52 supports more than 90 different input and output plugins. Input plugins
53 retrieve metrics and publish them to the collectd deamon, while output plugins
54 publish the data they receive to an end point. Collectd also has infrastructure
55 to support thresholding and notification.
57 Collectd docker image has enabled the following collectd plugins (in addition
58 to the standard collectd plugins):
61 * Open vSwitch events Plugin
62 * Open vSwitch stats Plugin
70 Plugins and third party applications in Barometer repository that will be available in the
73 * Open vSwitch PMD stats
74 * ONAP VES application
79 InfluxDB + Grafana Docker Images
80 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
82 The Barometer project's InfluxDB and Grafana docker images are 2 docker images that database and graph
83 statistics reported by the Barometer collectd docker. InfluxDB is an open-source time series database
84 tool which stores the data from collectd for future analysis via Grafana, which is a open-source
85 metrics anlytics and visualisation suite which can be accessed through any browser.
87 VES + Kafka Docker Images
88 ^^^^^^^^^^^^^^^^^^^^^^^^^
90 The Barometer project's VES application and Kafka docker images are based on a CentOS 7 image. Kafka
91 docker image has a dependancy on `Zookeeper <https://zookeeper.apache.org/>`_. Kafka must be able to
92 connect and register with an instance of Zookeeper that is either running on local or remote host.
93 Kafka recieves and stores metrics recieved from Collectd. VES application pulls latest metrics from Kafka
94 which it normalizes into VES format for sending to a VES collector. Please see details in
95 :ref:`VES Application User Guide <barometer-ves-userguide>`
97 One Click Install with Ansible
98 ------------------------------
100 Proxy for package manager on host
101 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
103 This step has to be performed only if host is behind HTTP/HTTPS proxy
105 Proxy URL have to be set in dedicated config file
107 1. CentOS - /etc/yum.conf
111 proxy=http://your.proxy.domain:1234
113 2. Ubuntu - /etc/apt/apt.conf
117 Acquire::http::Proxy "http://your.proxy.domain:1234"
119 After update of config file, apt mirrors have to be updated via 'apt-get update'
123 $ sudo apt-get update
125 Proxy environment variables(for docker and pip)
126 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
128 This step has to be performed only if host is behind HTTP/HTTPS proxy
130 Configuring proxy for packaging system is not enough, also some proxy
131 environment variables have to be set in the system before ansible scripts
133 Barometer configures docker proxy automatically via ansible task as a part
134 of 'one click install' process - user only has to provide proxy URL using common
135 shell environment variables and ansible will automatically configure proxies
136 for docker(to be able to fetch barometer images). Another component used by
137 ansible (e.g. pip is used for downloading python dependencies) will also benefit
138 from setting proxy variables properly in the system.
140 Proxy variables used by ansible One Click Install:
146 Variables mentioned above have to be visible for superuser (because most
147 actions involving ansible-barometer installation require root privileges).
148 Proxy variables are commonly defined in '/etc/environment' file (but any other
149 place is good as long as variables can be seen by commands using 'su').
151 Sample proxy configuration in /etc/environment:
155 http_proxy=http://your.proxy.domain:1234
156 https_proxy=http://your.proxy.domain:1234
157 ftp_proxy=http://your.proxy.domain:1234
163 * sudo permissions or root access are required to install ansible.
164 * ansible version needs to be 2.4+, because usage of import/include statements
166 The following steps have been verified with Ansible 2.6.3 on Ubuntu 16.04 and 18.04.
167 To install Ansible 2.6.3 on Ubuntu:
171 $ sudo apt-get install python
172 $ sudo apt-get install python-pip
173 $ sudo -H pip install 'ansible==2.6.3'
175 The following steps have been verified with Ansible 2.6.3 on Centos 7.5.
176 To install Ansible 2.6.3 on Centos:
180 $ sudo yum install python
181 $ sudo yum install epel-release
182 $ sudo yum install python-pip
183 $ sudo -H pip install 'ansible==2.6.3'
184 $ sudo yum install git
191 $ git clone https://gerrit.opnfv.org/gerrit/barometer
192 $ cd barometer/docker/ansible
196 Edit inventory file and add hosts: $barometer_dir/docker/ansible/default.inv
203 [collectd_hosts:vars]
205 insert_ipmi_modules=true
222 Change localhost to different hosts where neccessary.
223 Hosts for influxdb and grafana are required only for collectd_service.yml.
224 Hosts for kafka and ves are required only for collectd_ves.yml.
226 To change host for kafka edit kafka_ip_addr in ./roles/config_files/vars/main.yml.
228 Additional plugin dependencies
229 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
231 By default ansible will try to fulfill dependencies for mcelog and ipmi plugin.
232 For mcelog plugin it installs mcelog daemon. For ipmi it tries to insert ipmi_devintf
233 and ipmi_si kernel modules.
234 This can be changed in inventory file with use of variables install_mcelog
235 and insert_ipmi_modules, both variables are independent:
239 [collectd_hosts:vars]
241 insert_ipmi_modules=false
244 On Ubuntu 18.04 to use mcelog plugin the user has to install mcelog daemon
245 manually ahead of installing from ansible scripts as the deb package is not
246 available in official Ubuntu 18.04 repo. It means that setting install_mcelog
252 Generate ssh keys if not present, otherwise move onto next step.
258 Copy ssh key to all target hosts. It requires to provide root password.
259 The example is for localhost.
264 $ ssh-copy-id root@localhost
266 Verify that key is added and password is not required to connect.
270 $ sudo ssh root@localhost
273 Keys should be added to every target host and [localhost] is only used as an
274 example. For multinode installation keys need to be copied for each node:
275 [collectd_hostname], [influxdb_hostname] etc.
277 Download and run Collectd+Influxdb+Grafana containers
278 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
280 The One Click installation features easy and scalable deployment of Collectd,
281 Influxdb and Grafana containers using Ansible playbook. The following steps goes
282 through more details.
286 $ sudo -H ansible-playbook -i default.inv collectd_service.yml
288 Check the three containers are running, the output of docker ps should be similar to:
293 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
294 a033aeea180d opnfv/barometer-grafana "/run.sh" 9 days ago Up 7 minutes bar-grafana
295 1bca2e4562ab opnfv/barometer-influxdb "/entrypoint.sh in..." 9 days ago Up 7 minutes bar-influxdb
296 daeeb68ad1d5 opnfv/barometer-collectd "/run_collectd.sh ..." 9 days ago Up 7 minutes bar-collectd
298 To make some changes when a container is running run:
302 $ sudo docker exec -ti <CONTAINER ID> /bin/bash
304 Connect to <host_ip>:3000 with a browser and log into Grafana: admin/admin.
305 For short introduction please see the:
306 `Grafana guide <http://docs.grafana.org/guides/getting_started/>`_.
308 The collectd configuration files can be accessed directly on target system in '/opt/collectd/etc/collectd.conf.d'.
309 It can be used for manual changes or enable/disable plugins. If configuration has been modified it is required to
314 $ sudo docker restart bar-collectd
316 Download collectd+kafka+ves containers
317 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
319 Before running Kafka an instance of zookeeper is required. See `Run Kafka docker image`_ for notes on how to run it.
320 The 'zookeeper_hostname' and 'broker_id' can be set in ./roles/run_kafka/vars/main.yml.
324 $ sudo ansible-playbook -i default.inv collectd_ves.yml
326 Check the three containers are running, the output of docker ps should be similar to:
331 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
332 8b095ad94ea1 zookeeper:3.4.11 "/docker-entrypoin..." 7 minutes ago Up 7 minutes awesome_jennings
333 eb8bba3c0b76 opnfv/barometer-ves "./start_ves_app.s..." 21 minutes ago Up 6 minutes bar-ves
334 86702a96a68c opnfv/barometer-kafka "/src/start_kafka.sh" 21 minutes ago Up 6 minutes bar-kafka
335 daeeb68ad1d5 opnfv/barometer-collectd "/run_collectd.sh ..." 13 days ago Up 6 minutes bar-collectd
338 To make some changes when a container is running run:
342 $ sudo docker exec -ti <CONTAINER ID> /bin/bash
344 List of default plugins for collectd container
345 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
347 By default the collectd is started with default configuration which includes the followin plugins:
348 * csv, contextswitch, cpu, cpufreq, df, disk, ethstat, ipc, irq, load, memory, numa, processes,
349 swap, turbostat, uuid, uptime, exec, hugepages, intel_pmu, ipmi, write_kafka, logfile, mcelog,
350 network, intel_rdt, rrdtool, snmp_agent, syslog, virt, ovs_stats, ovs_events
352 Some of the plugins are loaded depending on specific system requirements and can be omitted if
353 dependency is not met, this is the case for:
354 * hugepages, ipmi, mcelog, intel_rdt, virt, ovs_stats, ovs_events
356 List and description of tags used in ansible scripts
357 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
359 Tags can be used to run a specific part of the configuration without running the whole playbook.
360 To run a specific parts only:
364 $ sudo ansible-playbook -i default.inv collectd_service.yml --tags "syslog,cpu,uuid"
366 To disable some parts or plugins:
370 $ sudo ansible-playbook -i default.inv collectd_service.yml --skip-tags "en_default_all,syslog,cpu,uuid"
372 List of available tags:
375 Install docker and required dependencies with package manager.
378 Configure proxy file for docker service if proxy is set on host environment.
381 Remove collectd config files.
383 copy_additional_configs
384 Copy additional configuration files to target system. Path to additional configuration
385 is stored in $barometer_dir/docker/ansible/roles/config_files/vars/main.yml as additional_configs_path.
388 Set of default read plugins: contextswitch, cpu, cpufreq, df, disk, ethstat, ipc, irq,
389 load, memory, numa, processes, swap, turbostat, uptime.
392 The following tags can be used to enable/disable plugins: csv, contextswitch, cpu,
393 cpufreq, df, disk, ethstat, ipc, irq, load, memory, numa, processes, swap, turbostat,
394 uptime, exec, hugepages, ipmi, kafka, logfile, mcelogs, network, pmu, rdt, rrdtool,
395 snmp, syslog, virt, ovs_stats, ovs_events, uuid.
399 .. Describe the specific capabilities and usage for <XYZ> feature.
400 .. Provide enough information that a user will be able to operate the feature on a deployed scenario.
403 The below sections provide steps for manual installation and configuration
404 of docker images. They are not neccessary if docker images were installed with
405 use of Ansible-Playbook.
410 * sudo permissions are required to install docker.
411 * These instructions are for Ubuntu 16.10
417 $ sudo apt-get install curl
418 $ sudo curl -fsSL https://get.docker.com/ | sh
419 $ sudo usermod -aG docker <username>
420 $ sudo systemctl status docker
422 Replace <username> above with an appropriate user name.
427 * sudo permissions are required to install docker.
428 * These instructions are for CentOS 7
434 $ sudo yum remove docker docker-common docker-selinux docker-engine
435 $ sudo yum install -y yum-utils device-mapper-persistent-data lvm2
436 $ sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
437 $ sudo yum-config-manager --enable docker-ce-edge
438 $ sudo yum-config-manager --enable docker-ce-test
439 $ sudo yum install docker-ce
440 $ sudo usermod -aG docker <username>
441 $ sudo systemctl status docker
443 Replace <username> above with an appropriate user name.
446 If this is the first time you are installing a package from a recently added
447 repository, you will be prompted to accept the GPG key, and the key’s
448 fingerprint will be shown. Verify that the fingerprint is correct, and if so,
449 accept the key. The fingerprint should match060A 61C5 1B55 8A7F 742B 77AA C52F
452 Retrieving key from https://download.docker.com/linux/centos/gpg
453 Importing GPG key 0x621E9F35:
454 Userid : "Docker Release (CE rpm) <docker@docker.com>"
455 Fingerprint: 060a 61c5 1b55 8a7f 742b 77aa c52f eb6b 621e 9f35
456 From : https://download.docker.com/linux/centos/gpg
459 Manual proxy configuration for docker
460 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
463 This applies for both CentOS and Ubuntu.
465 If you are behind an HTTP or HTTPS proxy server, you will need to add this
466 configuration in the Docker systemd service file.
468 1. Create a systemd drop-in directory for the docker service:
472 $ sudo mkdir -p /etc/systemd/system/docker.service.d
475 called /etc/systemd/system/docker.service.d/http-proxy.conf that adds
476 the HTTP_PROXY environment variable:
481 Environment="HTTP_PROXY=http://proxy.example.com:80/"
483 Or, if you are behind an HTTPS proxy server, create a file
484 called /etc/systemd/system/docker.service.d/https-proxy.conf that adds
485 the HTTPS_PROXY environment variable:
490 Environment="HTTPS_PROXY=https://proxy.example.com:443/"
492 Or create a single file with all the proxy configurations:
493 /etc/systemd/system/docker.service.d/proxy.conf
498 Environment="HTTP_PROXY=http://proxy.example.com:80/"
499 Environment="HTTPS_PROXY=https://proxy.example.com:443/"
500 Environment="FTP_PROXY=ftp://proxy.example.com:443/"
501 Environment="NO_PROXY=localhost"
507 $ sudo systemctl daemon-reload
513 $ sudo systemctl restart docker
515 5. Check docker environment variables:
519 sudo systemctl show --property=Environment docker
521 Test docker installation
522 ^^^^^^^^^^^^^^^^^^^^^^^^
524 This applies for both CentOS and Ubuntu.
528 $ sudo docker run hello-world
530 The output should be something like:
534 Unable to find image 'hello-world:latest' locally
535 latest: Pulling from library/hello-world
536 5b0f327be733: Pull complete
537 Digest: sha256:07d5f7800dfe37b8c2196c7b1c524c33808ce2e0f74e7aa00e603295ca9a0972
538 Status: Downloaded newer image for hello-world:latest
541 This message shows that your installation appears to be working correctly.
543 To generate this message, Docker took the following steps:
544 1. The Docker client contacted the Docker daemon.
545 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
546 3. The Docker daemon created a new container from that image which runs the
547 executable that produces the output you are currently reading.
548 4. The Docker daemon streamed that output to the Docker client, which sent it
551 To try something more ambitious, you can run an Ubuntu container with:
555 $ docker run -it ubuntu bash
557 Build and Run Collectd Docker Image
558 -----------------------------------
560 Download the collectd docker image
561 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
562 If you wish to use a pre-built barometer image, you can pull the barometer
563 image from https://hub.docker.com/r/opnfv/barometer-collectd/
567 $ docker pull opnfv/barometer-collectd
569 Build the collectd docker image
570 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
574 $ git clone https://gerrit.opnfv.org/gerrit/barometer
575 $ cd barometer/docker/barometer-collectd
576 $ sudo docker build -t opnfv/barometer-collectd --build-arg http_proxy=`echo $http_proxy` \
577 --build-arg https_proxy=`echo $https_proxy` --network=host -f Dockerfile .
580 Main directory of barometer source code (directory that contains 'docker',
581 'docs', 'src' and systems sub-directories) will be referred as
582 ``<BAROMETER_REPO_DIR>``
586 In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs to be
587 passed only if system is behind an HTTP or HTTPS proxy server.
589 Check the docker images:
595 Output should contain a barometer-collectd image:
599 REPOSITORY TAG IMAGE ID CREATED SIZE
600 opnfv/barometer-collectd latest 05f2a3edd96b 3 hours ago 1.2GB
601 centos 7 196e0ce0c9fb 4 weeks ago 197MB
602 centos latest 196e0ce0c9fb 4 weeks ago 197MB
603 hello-world latest 05a3bd381fc2 4 weeks ago 1.84kB
605 Run the collectd docker image
606 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
609 $ cd <BAROMETER_REPO_DIR>
610 $ sudo docker run -ti --net=host -v \
611 `pwd`/src/collectd/collectd_sample_configs:/opt/collectd/etc/collectd.conf.d \
612 -v /var/run:/var/run -v /tmp:/tmp --privileged opnfv/barometer-collectd
615 The docker collectd image contains configuration for all the collectd
616 plugins. In the command above we are overriding
617 /opt/collectd/etc/collectd.conf.d by mounting a host directory
618 src/collectd/collectd_sample_configs that contains only the sample
619 configurations we are interested in running.
621 *If some dependencies for plugins listed in configuration directory
622 aren't met, then collectd startup may fail(collectd tries to
623 initialize plugins configurations for all given config files that can
624 be found in shared configs directory and may fail if some dependency
627 If `DPDK` or `RDT` can't be installed on host, then corresponding config
628 files should be removed from shared configuration directory
629 (`<BAROMETER_REPO_DIR>/src/collectd/collectd_sample_configs/`) prior
630 to starting barometer-collectd container. By example: in case of missing
631 `DPDK` functionality on the host, `dpdkstat.conf` and `dpdkevents.conf`
634 Sample configurations can be found at:
635 https://github.com/opnfv/barometer/tree/master/src/collectd/collectd_sample_configs
637 List of barometer-collectd dependencies on host for various plugins
639 https://wiki.opnfv.org/display/fastpath/Barometer-collectd+host+dependencies
641 Check your docker image is running
647 To make some changes when the container is running run:
651 sudo docker exec -ti <CONTAINER ID> /bin/bash
653 Build and Run InfluxDB and Grafana docker images
654 ------------------------------------------------
658 The barometer-influxdb image is based on the influxdb:1.3.7 image from the influxdb dockerhub. To
659 view detils on the base image please visit
660 `https://hub.docker.com/_/influxdb/ <https://hub.docker.com/_/influxdb/>`_ Page includes details of
661 exposed ports and configurable enviromental variables of the base image.
663 The barometer-grafana image is based on grafana:4.6.3 image from the grafana dockerhub. To view
664 details on the base image please visit
665 `https://hub.docker.com/r/grafana/grafana/ <https://hub.docker.com/r/grafana/grafana/>`_ Page
666 includes details on exposed ports and configurable enviromental variables of the base image.
668 The barometer-grafana image includes pre-configured source and dashboards to display statistics exposed
669 by the barometer-collectd image. The default datasource is an influxdb database running on localhost
670 but the address of the influxdb server can be modified when launching the image by setting the
671 environmental variables influxdb_host to IP or hostname of host on which influxdb server is running.
673 Additional dashboards can be added to barometer-grafana by mapping a volume to /opt/grafana/dashboards.
674 Incase where a folder is mounted to this volume only files included in this folder will be visible
675 inside barometer-grafana. To ensure all default files are also loaded please ensure they are included in
676 volume folder been mounted. Appropriate example are given in section `Run the Grafana docker image`_
678 Download the InfluxDB and Grafana docker images
679 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
680 If you wish to use pre-built barometer project's influxdb and grafana images, you can pull the
681 images from https://hub.docker.com/r/opnfv/barometer-influxdb/ and https://hub.docker.com/r/opnfv/barometer-grafana/
684 If your preference is to build images locally please see sections `Build InfluxDB Docker Image`_ and
685 `Build Grafana Docker Image`_
689 $ docker pull opnfv/barometer-influxdb
690 $ docker pull opnfv/barometer-grafana
693 If you have pulled the pre-built barometer-influxdb and barometer-grafana images there is no
694 requirement to complete steps outlined in sections `Build InfluxDB Docker Image`_ and
695 `Build Grafana Docker Image`_ and you can proceed directly to section
696 `Run the Influxdb and Grafana Images`_
698 Build InfluxDB docker image
699 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
701 Build influxdb image from Dockerfile
705 $ cd barometer/docker/barometer-influxdb
706 $ sudo docker build -t opnfv/barometer-influxdb --build-arg http_proxy=`echo $http_proxy` \
707 --build-arg https_proxy=`echo $https_proxy` --network=host -f Dockerfile .
710 In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs to
711 be passed only if system is behind an HTTP or HTTPS proxy server.
713 Check the docker images:
719 Output should contain an influxdb image:
723 REPOSITORY TAG IMAGE ID CREATED SIZE
724 opnfv/barometer-influxdb latest 1e4623a59fe5 3 days ago 191MB
726 Build Grafana docker image
727 ^^^^^^^^^^^^^^^^^^^^^^^^^^
729 Build Grafana image from Dockerfile
733 $ cd barometer/docker/barometer-grafana
734 $ sudo docker build -t opnfv/barometer-grafana --build-arg http_proxy=`echo $http_proxy` \
735 --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
738 In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs to
739 be passed only if system is behind an HTTP or HTTPS proxy server.
741 Check the docker images:
747 Output should contain an influxdb image:
751 REPOSITORY TAG IMAGE ID CREATED SIZE
752 opnfv/barometer-grafana latest 05f2a3edd96b 3 hours ago 1.2GB
754 Run the Influxdb and Grafana Images
755 -----------------------------------
757 Run the InfluxDB docker image
758 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
761 $ sudo docker run -tid -v /var/lib/influxdb:/var/lib/influxdb --net=host\
762 --name bar-influxdb opnfv/barometer-influxdb
764 Check your docker image is running
770 To make some changes when the container is running run:
774 sudo docker exec -ti <CONTAINER ID> /bin/bash
776 When both collectd and InfluxDB containers are located
777 on the same host, then no additional configuration have to be added and you
778 can proceed directly to `Run the Grafana docker image`_ section.
780 Modify collectd to support InfluxDB on another host
781 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
782 If InfluxDB and collectd containers are located on separate hosts, then
783 additional configuration have to be done in ``collectd`` container - it
784 normally sends data using network plugin to 'localhost/127.0.0.1' therefore
785 changing output location is required:
787 1. Stop and remove running bar-collectd container (if it is running)
791 $ sudo docker ps #to get collectd container name
792 $ sudo docker rm -f <COLLECTD_CONTAINER_NAME>
794 2. Go to location where shared collectd config files are stored
798 $ cd <BAROMETER_REPO_DIR>
799 $ cd src/collectd/collectd_sample_configs
801 3. Edit content of ``network.conf`` file.
802 By default this file looks like that:
808 Server "127.0.0.1" "25826"
811 ``127.0.0.1`` string has to be replaced with the IP address of host where
812 InfluxDB container is running (e.g. ``192.168.121.111``). Edit this using your
813 favorite text editor.
815 4. Start again collectd container like it is described in
816 `Run the collectd docker image`_ chapter
820 $ cd <BAROMETER_REPO_DIR>
821 $ sudo docker run -ti --name bar-collectd --net=host -v \
822 `pwd`/src/collectd/collectd_sample_configs:/opt/collectd/etc/collectd.conf.d \
823 -v /var/run:/var/run -v /tmp:/tmp --privileged opnfv/barometer-collectd
825 Now collectd container will be sending data to InfluxDB container located on
826 remote Host pointed by IP configured in step 3.
828 Run the Grafana docker image
829 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
831 Connecting to an influxdb instance running on local system and adding own custom dashboards
835 $ cd <BAROMETER_REPO_DIR>
836 $ sudo docker run -tid -v /var/lib/grafana:/var/lib/grafana \
837 -v ${PWD}/docker/barometer-grafana/dashboards:/opt/grafana/dashboards \
838 --name bar-grafana --net=host opnfv/barometer-grafana
840 Connecting to an influxdb instance running on remote system with hostname of someserver and IP address
845 $ sudo docker run -tid -v /var/lib/grafana:/var/lib/grafana --net=host -e \
846 influxdb_host=someserver --add-host someserver:192.168.121.111 --name \
847 bar-grafana opnfv/barometer-grafana
849 Check your docker image is running
855 To make some changes when the container is running run:
859 sudo docker exec -ti <CONTAINER ID> /bin/bash
861 Connect to <host_ip>:3000 with a browser and log into grafana: admin/admin
863 Cleanup of influxdb/grafana configuration
864 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
866 When user wants to remove current grafana and influxdb configuration,
867 folowing actions have to be performed
869 1. Stop and remove running influxdb and grafana containers
873 sudo docker rm -f bar-grafana bar-influxdb
875 2. Remove shared influxdb and grafana folders from the Host
879 sudo rm -rf /var/lib/grafana
880 sudo rm -rf /var/lib/influxdb
883 Shared folders are storing configuration of grafana and influxdb
884 containers. In case of changing influxdb or grafana configuration
885 (e.g. moving influxdb to another host) it is good to perform cleanup
886 on shared folders to not affect new setup with an old configuration.
888 Build and Run VES and Kafka Docker Images
889 ------------------------------------------
891 Download VES and Kafka docker images
892 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
894 If you wish to use pre-built barometer project's VES and kafka images, you can pull the
895 images from https://hub.docker.com/r/opnfv/barometer-ves/ and https://hub.docker.com/r/opnfv/barometer-kafka/
898 If your preference is to build images locally please see sections `Build the Kafka Image`_ and
903 $ docker pull opnfv/barometer-kafka
904 $ docker pull opnfv/barometer-ves
907 If you have pulled the pre-built images there is no requirement to complete steps outlined
908 in sections `Build Kafka Docker Image`_ and `Build VES Docker Image`_ and you can proceed directly to section
909 `Run Kafka Docker Image`_
911 Build Kafka docker image
912 ^^^^^^^^^^^^^^^^^^^^^^^^
914 Build Kafka docker image:
918 $ cd barometer/docker/barometer-kafka
919 $ sudo docker build -t opnfv/barometer-kafka --build-arg http_proxy=`echo $http_proxy` \
920 --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
923 In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs
924 to be passed only if system is behind an HTTP or HTTPS proxy server.
926 Check the docker images:
932 Output should contain a barometer image:
936 REPOSITORY TAG IMAGE ID CREATED SIZE
937 opnfv/barometer-kafka latest 05f2a3edd96b 3 hours ago 1.2GB
939 Build VES docker image
940 ^^^^^^^^^^^^^^^^^^^^^^
942 Build VES application docker image:
946 $ cd barometer/docker/barometer-ves
947 $ sudo docker build -t opnfv/barometer-ves --build-arg http_proxy=`echo $http_proxy` \
948 --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
951 In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs
952 to be passed only if system is behind an HTTP or HTTPS proxy server.
954 Check the docker images:
960 Output should contain a barometer image:
964 REPOSITORY TAG IMAGE ID CREATED SIZE
965 opnfv/barometer-ves latest 05f2a3edd96b 3 hours ago 1.2GB
967 Run Kafka docker image
968 ^^^^^^^^^^^^^^^^^^^^^^
971 Before running Kafka an instance of Zookeeper must be running for the Kafka broker to register
972 with. Zookeeper can be running locally or on a remote platform. Kafka's broker_id and address of
973 its zookeeper instance can be configured by setting values for environmental variables 'broker_id'
974 and 'zookeeper_node'. In instance where 'broker_id' and/or 'zookeeper_node' is not set the default
975 setting of broker_id=0 and zookeeper_node=localhost is used. In intance where Zookeeper is running
976 on same node as Kafka and there is a one to one relationship between Zookeeper and Kafka, default
977 setting can be used. The docker argument `add-host` adds hostname and IP address to
978 /etc/hosts file in container
980 Run zookeeper docker image:
984 $ sudo docker run -tid --net=host -p 2181:2181 zookeeper:3.4.11
986 Run kafka docker image which connects with a zookeeper instance running on same node with a 1:1 relationship
990 $ sudo docker run -tid --net=host -p 9092:9092 opnfv/barometer-kafka
993 Run kafka docker image which connects with a zookeeper instance running on a node with IP address of
994 192.168.121.111 using broker ID of 1
998 $ sudo docker run -tid --net=host -p 9092:9092 --env broker_id=1 --env zookeeper_node=zookeeper --add-host \
999 zookeeper:192.168.121.111 opnfv/barometer-kafka
1001 Run VES Application docker image
1002 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1004 VES application uses configuration file ves_app_config.conf from directory
1005 barometer/3rd_party/collectd-ves-app/ves_app/config/ and host.yaml file from
1006 barometer/3rd_party/collectd-ves-app/ves_app/yaml/ by default. If you wish to use a custom config
1007 file it should be mounted to mount point /opt/ves/config/ves_app_config.conf. To use an alternative yaml
1008 file from folder barometer/3rd_party/collectd-ves-app/ves_app/yaml the name of the yaml file to use
1009 should be passed as an additional command. If you wish to use a custom file the file should be
1010 mounted to mount point /opt/ves/yaml/ Please see examples below
1012 Run VES docker image with default configuration
1016 $ sudo docker run -tid --net=host opnfv/barometer-ves
1018 Run VES docker image with guest.yaml files from barometer/3rd_party/collectd-ves-app/ves_app/yaml/
1022 $ sudo docker run -tid --net=host opnfv/barometer-ves guest.yaml
1025 Run VES docker image with using custom config and yaml files. In example below yaml/ folder cotains
1026 file named custom.yaml
1030 $ sudo docker run -tid --net=host -v ${PWD}/custom.config:/opt/ves/config/ves_app_config.conf \
1031 -v ${PWD}/yaml/:/opt/ves/yaml/ opnfv/barometer-ves custom.yaml
1033 Run VES Test Collector application
1034 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1036 VES Test Collector application can be used for displaying platform
1037 wide metrics that are collected by barometer-ves container.
1038 Setup instructions are located in: :ref:`Setup VES Test Collector`
1040 Build and Run DMA and Redis Docker Images
1041 -----------------------------------------------------
1043 Download DMA docker images
1044 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1046 If you wish to use pre-built barometer project's DMA images, you can pull the
1047 images from https://hub.docker.com/r/opnfv/barometer-dma/
1050 If your preference is to build images locally please see sections `Build DMA Docker Image`_
1054 $ docker pull opnfv/barometer-dma
1057 If you have pulled the pre-built images there is no requirement to complete steps outlined
1058 in sections `Build DMA Docker Image`_ and you can proceed directly to section
1059 `Run DMA Docker Image`_
1061 Build DMA docker image
1062 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1064 Build DMA docker image:
1068 $ cd barometer/docker/barometer-dma
1069 $ sudo docker build -t opnfv/barometer-dma --build-arg http_proxy=`echo $http_proxy` \
1070 --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
1073 In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs
1074 to be passed only if system is behind an HTTP or HTTPS proxy server.
1076 Check the docker images:
1080 $ sudo docker images
1082 Output should contain a barometer image:
1086 REPOSITORY TAG IMAGE ID CREATED SIZE
1087 opnfv/barometer-dma latest 2f14fbdbd498 3 hours ago 941 MB
1089 Run Redis docker image
1090 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1093 Before running DMA, Redis must be running.
1095 Run Redis docker image:
1099 $ sudo docker run -tid -p 6379:6379 --name barometer-redis redis
1101 Check your docker image is running
1107 Run DMA docker image
1108 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1111 Run DMA docker image with default configuration
1115 $ cd barometer/docker/barometer-dma
1116 $ sudo mkdir /etc/barometer-dma
1117 $ sudo cp ../../src/dma/examples/config.toml /etc/barometer-dma/
1118 $ sudo vi /etc/barometer-dma/config.toml
1119 (edit amqp_password and os_password:OpenStack admin password)
1122 (When there is no key for SSH access authentication)
1124 (Press Enter until done)
1125 (Backup if necessary)
1126 # cp ~/.ssh/authorized_keys ~/.ssh/authorized_keys_org
1127 # cat ~/.ssh/authorized_keys_org ~/.ssh/id_rsa.pub \
1128 > ~/.ssh/authorized_keys
1131 $ sudo docker run -tid --net=host --name server \
1132 -v /etc/barometer-dma:/etc/barometer-dma \
1133 -v /root/.ssh/id_rsa:/root/.ssh/id_rsa \
1134 -v /etc/collectd/collectd.conf.d:/etc/collectd/collectd.conf.d \
1135 opnfv/barometer-dma /server
1137 $ sudo docker run -tid --net=host --name infofetch \
1138 -v /etc/barometer-dma:/etc/barometer-dma \
1139 -v /var/run/libvirt:/var/run/libvirt \
1140 opnfv/barometer-dma /infofetch
1142 (Execute when installing the threshold evaluation binary)
1143 $ sudo docker cp infofetch:/threshold ./
1144 $ sudo ln -s ${PWD}/threshold /usr/local/bin/
1148 .. [1] https://docs.docker.com/engine/admin/systemd/#httphttps-proxy
1149 .. [2] https://docs.docker.com/engine/installation/linux/docker-ce/centos/#install-using-the-repository
1150 .. [3] https://docs.docker.com/engine/userguide/