.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
.. (c) <optionally add copywriters name>
+.. _barometer-docker-userguide:
===================================
OPNFV Barometer Docker User Guide
For steps to build and run VES and Kafka images please see section `Build and Run VES and Kafka Docker Images`_
-For overview of running VES application with Kafka please see the `VES Application User Guide
-<http://docs.opnfv.org/en/latest/submodules/barometer/docs/release/userguide/collectd.ves.userguide.html>`_
+For overview of running VES application with Kafka please see the :ref:`VES Application User Guide <barometer-ves-userguide>`
Barometer Docker Images Description
-----------------------------------
docker image has a dependancy on `Zookeeper <https://zookeeper.apache.org/>`_. Kafka must be able to
connect and register with an instance of Zookeeper that is either running on local or remote host.
Kafka recieves and stores metrics recieved from Collectd. VES application pulls latest metrics from Kafka
-which it normalizes into VES format for sending to a VES collector. Please see details in `VES Application User Guide
-<http://docs.opnfv.org/en/latest/submodules/barometer/docs/release/userguide/collectd.ves.userguide.html>`_
+which it normalizes into VES format for sending to a VES collector. Please see details in
+:ref:`VES Application User Guide <barometer-ves-userguide>`
+
+Download and Run Docker Images with Ansible-Playbook
+----------------------------------------------------
+
+Install Ansible
+^^^^^^^^^^^^^^^
+.. note::
+ * sudo permissions or root access are required to install ansible.
+ * ansible version needs to be 2.4+, because usage of import/include statements
+
+To install Ansible 2.6.3 on Ubuntu:
+
+.. code:: bash
+
+ $ sudo apt-get install python
+ $ sudo apt-get install python-pip
+ $ sudo pip install 'ansible==2.6.3'
+
+To install Ansible 2.6.3 on Centos:
+
+.. code:: bash
+
+ $ sudo yum install python
+ $ sudo yum install epel-release
+ $ sudo yum install python-pip
+ $ sudo pip install 'ansible==2.6.3'
+
+Clone barometer repo
+^^^^^^^^^^^^^^^^^^^^
+
+.. code:: bash
+
+ $ git clone https://gerrit.opnfv.org/gerrit/barometer
+ $ cd barometer/docker/ansible
+
+Edit inventory file
+^^^^^^^^^^^^^^^^^^^
+Edit inventory file and add hosts: ~/default.inv
+
+.. code:: bash
+
+ [collectd_hosts]
+ localhost
+
+ [collectd_hosts:vars]
+ install_mcelog=true
+ insert_ipmi_modules=true
+
+ [influxdb_hosts]
+ localhost
+
+ [grafana_hosts]
+ localhost
+
+ [prometheus_hosts]
+ #localhost
+
+ [kafka_hosts]
+ #localhost
+
+ [ves_hosts]
+ #localhost
+
+Change localhost to different hosts where neccessary.
+Hosts for influxdb and grafana are required only for collectd_service.yml.
+Hosts for kafka and ves are required only for collectd_ves.yml.
+
+To change host for kafka edit kafka_ip_addr in ./roles/config_files/vars/main.yml.
+
+Additional plugin dependencies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default ansible will try to fulfill dependencies for mcelog and ipmi plugin.
+For mcelog plugin it installs mcelog daemon. For ipmi it tries to insert ipmi_devintf
+and ipmi_si kernel modules.
+This can be changed in inventory file with use of variables install_mcelog
+and insert_ipmi_modules, both variables are independent:
+
+.. code:: bash
+
+ [collectd_hosts:vars]
+ install_mcelog=false
+ insert_ipmi_modules=false
+
+Configure ssh keys
+^^^^^^^^^^^^^^^^^^
+
+Generate ssh keys if not present, otherwise move onto next step.
+
+.. code:: bash
+
+ $ sudo ssh-keygen
+
+Coppy ssh key to all target hosts. It requires to provide root password. The example is for localhost.
+
+.. code:: bash
+
+ $ sudo ssh-copy-id root@localhost
+
+Download collectd+influxdb+grafana containers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code:: bash
+
+ $ sudo ansible-playbook -i ~/default.inv collectd_service.yml
+
+Check the three containers are running, the output of docker ps should be similar to:
+
+.. code:: bash
+
+ $ sudo docker ps
+ CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
+ a033aeea180d opnfv/barometer-grafana "/run.sh" 9 days ago Up 7 minutes bar-grafana
+ 1bca2e4562ab opnfv/barometer-influxdb "/entrypoint.sh in..." 9 days ago Up 7 minutes bar-influxdb
+ daeeb68ad1d5 opnfv/barometer-collectd "/run_collectd.sh ..." 9 days ago Up 7 minutes bar-collectd
+
+To make some changes when a container is running run:
+
+.. code:: bash
+
+ $ sudo docker exec -ti <CONTAINER ID> /bin/bash
+
+Connect to <host_ip>:3000 with a browser and log into grafana: admin/admin
+
+The collectd configuration files can be accessed directly on target system in '/opt/collectd/etc/collectd.conf.d'.
+It can be used for manual changes or enable/disable plugins. If configuration has been modified it is required to
+restart collectd:
+
+.. code:: bash
+
+ $ sudo docker restart bar-collectd
+
+Download collectd+kafka+ves containers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Before running Kafka an instance of zookeeper is required. See `Run Kafka docker image`_ for notes on how to run it.
+The 'zookeeper_hostname' and 'broker_id' can be set in ./roles/run_kafka/vars/main.yml.
+
+.. code:: bash
+
+ $ sudo ansible-playbook -i ~/default.inv collectd_ves.yml
+
+Check the three containers are running, the output of docker ps should be similar to:
+
+.. code:: bash
+
+ $ sudo docker ps
+ CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
+ 8b095ad94ea1 zookeeper:3.4.11 "/docker-entrypoin..." 7 minutes ago Up 7 minutes awesome_jennings
+ eb8bba3c0b76 opnfv/barometer-ves "./start_ves_app.s..." 21 minutes ago Up 6 minutes bar-ves
+ 86702a96a68c opnfv/barometer-kafka "/src/start_kafka.sh" 21 minutes ago Up 6 minutes bar-kafka
+ daeeb68ad1d5 opnfv/barometer-collectd "/run_collectd.sh ..." 13 days ago Up 6 minutes bar-collectd
+
+
+To make some changes when a container is running run:
+
+.. code:: bash
+
+ $ sudo docker exec -ti <CONTAINER ID> /bin/bash
+
+List of default plugins for collectd container
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default the collectd is started with default configuration which includes the followin plugins:
+ * csv, contextswitch, cpu, cpufreq, df, disk, ethstat, ipc, irq, load, memory, numa, processes,
+ swap, turbostat, uuid, uptime, exec, hugepages, intel_pmu, ipmi, write_kafka, logfile, mcelog,
+ network, intel_rdt, rrdtool, snmp_agent, syslog, virt, ovs_stats, ovs_events
+
+Some of the plugins are loaded depending on specific system requirements and can be omitted if
+dependency is not met, this is the case for:
+ * hugepages, ipmi, mcelog, intel_rdt, virt, ovs_stats, ovs_events
+
+List and description of tags used in ansible scripts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Tags can be used to run a specific part of the configuration without running the whole playbook.
+To run a specific parts only:
+
+.. code:: bash
+
+ $ sudo ansible-playbook -i ~/default.inv collectd_service.yml --tags "syslog,cpu,uuid"
+
+To disable some parts or plugins:
+
+.. code:: bash
+
+ $ sudo ansible-playbook -i ~/default.inv collectd_service.yml --skip-tags "en_default_all,syslog,cpu,uuid"
+
+List of available tags:
+
+install_docker
+ Install docker and required dependencies with package manager.
+
+add_docker_proxy
+ Configure proxy file for docker service if proxy is set on host environment.
+
+rm_config_dir
+ Remove collectd config files.
+
+copy_additional_configs
+ Copy additional configuration files to target system. Path to additional configuration
+ is stored in $barometer_dir/docker/ansible/roles/config_files/vars/main.yml as additional_configs_path.
+
+en_default_all
+ Set of default read plugins: contextswitch, cpu, cpufreq, df, disk, ethstat, ipc, irq,
+ load, memory, numa, processes, swap, turbostat, uptime.
+
+plugins tags
+ The following tags can be used to enable/disable plugins: csv, contextswitch, cpu,
+ cpufreq, df, disk, ethstat, ipc, irq, load, memory, numa, processes, swap, turbostat,
+ uptime, exec, hugepages, ipmi, kafka, logfile, mcelogs, network, pmu, rdt, rrdtool,
+ snmp, syslog, virt, ovs_stats, ovs_events, uuid.
Installing Docker
-----------------
$ sudo docker run -tid --net=host -v ${PWD}/custom.config:/opt/ves/config/ves_app_config.conf \
-v ${PWD}/yaml/:/opt/ves/yaml/ opnfv/barometer-ves custom.yaml
+Build and Run LocalAgent and Redis Docker Images
+-----------------------------------------------------
+
+Download LocalAgent docker images
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you wish to use pre-built barometer project's LocalAgent images, you can pull the
+images from https://hub.docker.com/r/opnfv/barometer-localagent/
+
+.. note::
+ If your preference is to build images locally please see sections `Build LocalAgent Docker Image`_
+
+.. code:: bash
+
+ $ docker pull opnfv/barometer-localagent
+
+.. note::
+ If you have pulled the pre-built images there is no requirement to complete steps outlined
+ in sections `Build LocalAgent Docker Image`_ and you can proceed directly to section
+ `Run LocalAgent Docker Image`_ If you wish to run the docker images via Docker Compose proceed directly to section `Docker Compose`_.
+
+Build LocalAgent docker image
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Build LocalAgent docker image:
+
+.. code:: bash
+
+ $ cd barometer/docker/barometer-dma
+ $ sudo docker build -t opnfv/barometer-dma --build-arg http_proxy=`echo $http_proxy` \
+ --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
+
+.. note::
+ In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs
+ to be passed only if system is behind an HTTP or HTTPS proxy server.
+
+Check the docker images:
+
+.. code:: bash
+
+ $ sudo docker images
+
+Output should contain a barometer image:
+
+.. code::
+
+ REPOSITORY TAG IMAGE ID CREATED SIZE
+ opnfv/barometer-dma latest 2f14fbdbd498 3 hours ago 941 MB
+
+Run Redis docker image
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+ Before running LocalAgent, Redis must be running.
+
+Run Redis docker image:
+
+.. code:: bash
+
+ $ sudo docker run -tid -p 6379:6379 --name barometer-redis redis
+
+Check your docker image is running
+
+.. code:: bash
+
+ sudo docker ps
+
+Run LocalAgent docker image
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. note::
+
+Run LocalAgent docker image with default configuration
+
+.. code:: bash
+
+ $ cd barometer/docker/barometer-dma
+ $ sudo mkdir /etc/barometer-dma
+ $ sudo cp ../../src/dma/examples/config.toml /etc/barometer-dma/
+ $ sudo vi /etc/barometer-dma/config.toml
+ (edit amqp_password and os_password:OpenStack admin password)
+
+ $ sudo su -
+ (When there is no key for SSH access authentication)
+ # ssh-keygen
+ (Press Enter until done)
+ (Backup if necessary)
+ # cp ~/.ssh/authorized_keys ~/.ssh/authorized_keys_org
+ # cat ~/.ssh/authorized_keys_org ~/.ssh/id_rsa.pub \
+ > ~/.ssh/authorized_keys
+ # exit
+
+ $ sudo docker run -tid --net=host --name server \
+ -v /etc/barometer-dma:/etc/barometer-dma \
+ -v /root/.ssh/id_rsa:/root/.ssh/id_rsa \
+ -v /etc/collectd/collectd.conf.d:/etc/collectd/collectd.conf.d \
+ opnfv/barometer-dma /server
+
+ $ sudo docker run -tid --net=host --name infofetch \
+ -v /etc/barometer-dma:/etc/barometer-dma \
+ -v /var/run/libvirt:/var/run/libvirt \
+ opnfv/barometer-dma /infofetch
+
+ (Execute when installing the threshold evaluation binary)
+ $ sudo docker cp infofetch:/threshold ./
+ $ sudo ln -s ${PWD}/threshold /usr/local/bin/
+
Docker Compose
--------------
Code Review / barometer.git / blobdiff