docs/release/userguide/docker.userguide.rst

   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:
   5
   6 ===================================
   7 OPNFV Barometer Docker User Guide
   8 ===================================
   9
  10 .. contents::
  11    :depth: 3
  12    :local:
  13
  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:
  17
  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/>`_
  23
  24 For description of images please see section `Barometer Docker Images Description`_
  25
  26 For steps to build and run Collectd image please see section `Build and Run Collectd Docker Image`_
  27
  28 For steps to build and run InfluxDB and Grafana images please see section `Build and Run InfluxDB and Grafana Docker Images`_
  29
  30 For steps to build and run VES and Kafka images please see section `Build and Run VES and Kafka Docker Images`_
  31
  32 For overview of running VES application with Kafka please see the :ref:`VES Application User Guide <barometer-ves-userguide>`
  33
  34 Barometer Docker Images Description
  35 -----------------------------------
  36
  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.
  39
  40 Barometer Collectd Image
  41 ^^^^^^^^^^^^^^^^^^^^^^^^
  42 The barometer collectd docker image gives you a collectd installation that includes all
  43 the barometer plugins.
  44
  45 .. note::
  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.
  49
  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.
  56
  57 Collectd docker image has enabled the following collectd plugins (in addition
  58 to the standard collectd plugins):
  59
  60 * hugepages plugin
  61 * Open vSwitch events Plugin
  62 * Open vSwitch stats Plugin
  63 * mcelog plugin
  64 * PMU plugin
  65 * RDT plugin
  66 * virt
  67 * SNMP Agent
  68 * Kafka_write plugin
  69
  70 Plugins and third party applications in Barometer repository that will be available in the
  71 docker image:
  72
  73 * Open vSwitch PMD stats
  74 * ONAP VES application
  75 * gnocchi plugin
  76 * aodh plugin
  77 * Legacy/IPMI
  78
  79 InfluxDB + Grafana Docker Images
  80 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  81
  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.
  86
  87 VES + Kafka Docker Images
  88 ^^^^^^^^^^^^^^^^^^^^^^^^^
  89
  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>`
  96
  97 One Click Install with Ansible
  98 ------------------------------
  99
 100 Install Ansible
 101 ^^^^^^^^^^^^^^^
 102 .. note::
 103    * sudo permissions or root access are required to install ansible.
 104    * ansible version needs to be 2.4+, because usage of import/include statements
 105
 106 The following steps have been verified with Ansible 2.6.3 on Ubuntu 16.04 and 18.04.
 107 To install Ansible 2.6.3 on Ubuntu:
 108
 109 .. code:: bash
 110
 111     $ sudo apt-get install python
 112     $ sudo apt-get install python-pip
 113     $ sudo pip install 'ansible==2.6.3'
 114
 115 The following steps have been verified with Ansible 2.6.3 on Centos 7.5.
 116 To install Ansible 2.6.3 on Centos:
 117
 118 .. code:: bash
 119
 120     $ sudo yum install python
 121     $ sudo yum install epel-release
 122     $ sudo yum install python-pip
 123     $ sudo pip install 'ansible==2.6.3'
 124
 125 Clone barometer repo
 126 ^^^^^^^^^^^^^^^^^^^^
 127
 128 .. code:: bash
 129
 130     $ git clone https://gerrit.opnfv.org/gerrit/barometer
 131     $ cd barometer/docker/ansible
 132
 133 Edit inventory file
 134 ^^^^^^^^^^^^^^^^^^^
 135 Edit inventory file and add hosts: $barometer_dir/docker/ansible/default.inv
 136
 137 .. code:: bash
 138
 139     [collectd_hosts]
 140     localhost
 141
 142     [collectd_hosts:vars]
 143     install_mcelog=true
 144     insert_ipmi_modules=true
 145
 146     [influxdb_hosts]
 147     localhost
 148
 149     [grafana_hosts]
 150     localhost
 151
 152     [prometheus_hosts]
 153     #localhost
 154
 155     [kafka_hosts]
 156     #localhost
 157
 158     [ves_hosts]
 159     #localhost
 160
 161 Change localhost to different hosts where neccessary.
 162 Hosts for influxdb and grafana are required only for collectd_service.yml.
 163 Hosts for kafka and ves are required only for collectd_ves.yml.
 164
 165 To change host for kafka edit kafka_ip_addr in ./roles/config_files/vars/main.yml.
 166
 167 Additional plugin dependencies
 168 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 169
 170 By default ansible will try to fulfill dependencies for mcelog and ipmi plugin.
 171 For mcelog plugin it installs mcelog daemon. For ipmi it tries to insert ipmi_devintf
 172 and ipmi_si kernel modules.
 173 This can be changed in inventory file with use of variables install_mcelog
 174 and insert_ipmi_modules, both variables are independent:
 175
 176 .. code:: bash
 177
 178     [collectd_hosts:vars]
 179     install_mcelog=false
 180     insert_ipmi_modules=false
 181
 182 .. note::
 183    On Ubuntu 18.04 to use mcelog plugin the user has to install mcelog daemon
 184    manually ahead of installing from ansible scripts as the deb package is not
 185    available in official Ubuntu 18.04 repo. It means that setting install_mcelog
 186    to true is ignored.
 187
 188 Configure ssh keys
 189 ^^^^^^^^^^^^^^^^^^
 190
 191 Generate ssh keys if not present, otherwise move onto next step.
 192
 193 .. code:: bash
 194
 195     $ sudo ssh-keygen
 196
 197 Copy ssh key to all target hosts. It requires to provide root password.
 198 The example is for localhost.
 199
 200 .. code:: bash
 201
 202     $ sudo ssh-copy-id root@localhost
 203
 204 Verify that key is added and password is not required to connect.
 205
 206 .. code:: bash
 207
 208     $ sudo ssh root@localhost
 209
 210 .. note::
 211    Keys should be added to every target host and [localhost] is only used as an
 212    example. For multinode installation keys need to be copied for each node:
 213    [collectd_hostname], [influxdb_hostname] etc.
 214
 215 Download and run Collectd+Influxdb+Grafana containers
 216 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 217
 218 The One Click installation features easy and scalable deployment of Collectd,
 219 Influxdb and Grafana containers using Ansible playbook. The following steps goes
 220 through more details.
 221
 222 .. code:: bash
 223
 224     $ sudo ansible-playbook -i default.inv collectd_service.yml
 225
 226 Check the three containers are running, the output of docker ps should be similar to:
 227
 228 .. code:: bash
 229
 230     $ sudo docker ps
 231     CONTAINER ID        IMAGE                      COMMAND                  CREATED             STATUS              PORTS               NAMES
 232     a033aeea180d        opnfv/barometer-grafana    "/run.sh"                9 days ago          Up 7 minutes                            bar-grafana
 233     1bca2e4562ab        opnfv/barometer-influxdb   "/entrypoint.sh in..."   9 days ago          Up 7 minutes                            bar-influxdb
 234     daeeb68ad1d5        opnfv/barometer-collectd   "/run_collectd.sh ..."   9 days ago          Up 7 minutes                            bar-collectd
 235
 236 To make some changes when a container is running run:
 237
 238 .. code:: bash
 239
 240     $ sudo docker exec -ti <CONTAINER ID> /bin/bash
 241
 242 Connect to <host_ip>:3000 with a browser and log into Grafana: admin/admin.
 243 For short introduction please see the:
 244 `Grafana guide <http://docs.grafana.org/guides/getting_started/>`_.
 245
 246 The collectd configuration files can be accessed directly on target system in '/opt/collectd/etc/collectd.conf.d'.
 247 It can be used for manual changes or enable/disable plugins. If configuration has been modified it is required to
 248 restart collectd:
 249
 250 .. code:: bash
 251
 252     $ sudo docker restart bar-collectd
 253
 254 Download collectd+kafka+ves containers
 255 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 256
 257 Before running Kafka an instance of zookeeper is required. See `Run Kafka docker image`_ for notes on how to run it.
 258 The 'zookeeper_hostname' and 'broker_id' can be set in ./roles/run_kafka/vars/main.yml.
 259
 260 .. code:: bash
 261
 262     $ sudo ansible-playbook -i default.inv collectd_ves.yml
 263
 264 Check the three containers are running, the output of docker ps should be similar to:
 265
 266 .. code:: bash
 267
 268     $ sudo docker ps
 269     CONTAINER ID        IMAGE                      COMMAND                  CREATED             STATUS                     PORTS               NAMES
 270     8b095ad94ea1        zookeeper:3.4.11           "/docker-entrypoin..."   7 minutes ago       Up 7 minutes                                   awesome_jennings
 271     eb8bba3c0b76        opnfv/barometer-ves        "./start_ves_app.s..."   21 minutes ago      Up 6 minutes                                   bar-ves
 272     86702a96a68c        opnfv/barometer-kafka      "/src/start_kafka.sh"    21 minutes ago      Up 6 minutes                                   bar-kafka
 273     daeeb68ad1d5        opnfv/barometer-collectd   "/run_collectd.sh ..."   13 days ago         Up 6 minutes                                   bar-collectd
 274
 275
 276 To make some changes when a container is running run:
 277
 278 .. code:: bash
 279
 280     $ sudo docker exec -ti <CONTAINER ID> /bin/bash
 281
 282 List of default plugins for collectd container
 283 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 284
 285 By default the collectd is started with default configuration which includes the followin plugins:
 286    * csv, contextswitch, cpu, cpufreq, df, disk, ethstat, ipc, irq, load, memory, numa, processes,
 287      swap, turbostat, uuid, uptime, exec, hugepages, intel_pmu, ipmi, write_kafka, logfile, mcelog,
 288      network, intel_rdt, rrdtool, snmp_agent, syslog, virt, ovs_stats, ovs_events
 289
 290 Some of the plugins are loaded depending on specific system requirements and can be omitted if
 291 dependency is not met, this is the case for:
 292    * hugepages, ipmi, mcelog, intel_rdt, virt, ovs_stats, ovs_events
 293
 294 List and description of tags used in ansible scripts
 295 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 296
 297 Tags can be used to run a specific part of the configuration without running the whole playbook.
 298 To run a specific parts only:
 299
 300 .. code:: bash
 301
 302     $ sudo ansible-playbook -i default.inv collectd_service.yml --tags "syslog,cpu,uuid"
 303
 304 To disable some parts or plugins:
 305
 306 .. code:: bash
 307
 308     $ sudo ansible-playbook -i default.inv collectd_service.yml --skip-tags "en_default_all,syslog,cpu,uuid"
 309
 310 List of available tags:
 311
 312 install_docker
 313   Install docker and required dependencies with package manager.
 314
 315 add_docker_proxy
 316   Configure proxy file for docker service if proxy is set on host environment.
 317
 318 rm_config_dir
 319   Remove collectd config files.
 320
 321 copy_additional_configs
 322   Copy additional configuration files to target system. Path to additional configuration
 323   is stored in $barometer_dir/docker/ansible/roles/config_files/vars/main.yml as additional_configs_path.
 324
 325 en_default_all
 326   Set of default read plugins: contextswitch, cpu, cpufreq, df, disk, ethstat, ipc, irq,
 327   load, memory, numa, processes, swap, turbostat, uptime.
 328
 329 plugins tags
 330   The following tags can be used to enable/disable plugins: csv, contextswitch, cpu,
 331   cpufreq, df, disk, ethstat, ipc, irq, load, memory, numa, processes, swap, turbostat,
 332   uptime, exec, hugepages, ipmi, kafka, logfile, mcelogs, network, pmu, rdt, rrdtool,
 333   snmp, syslog, virt, ovs_stats, ovs_events, uuid.
 334
 335 Installing Docker
 336 -----------------
 337 .. Describe the specific capabilities and usage for <XYZ> feature.
 338 .. Provide enough information that a user will be able to operate the feature on a deployed scenario.
 339
 340 .. note::
 341    The below sections provide steps for manual installation and configuration
 342    of docker images. They are not neccessary if docker images were installed with
 343    use of Ansible-Playbook.
 344
 345 On Ubuntu
 346 ^^^^^^^^^^
 347 .. note::
 348    * sudo permissions are required to install docker.
 349    * These instructions are for Ubuntu 16.10
 350
 351 To install docker:
 352
 353 .. code:: bash
 354
 355     $ sudo apt-get install curl
 356     $ sudo curl -fsSL https://get.docker.com/ | sh
 357     $ sudo usermod -aG docker <username>
 358     $ sudo systemctl status docker
 359
 360 Replace <username> above with an appropriate user name.
 361
 362 On CentOS
 363 ^^^^^^^^^^
 364 .. note::
 365    * sudo permissions are required to install docker.
 366    * These instructions are for CentOS 7
 367
 368 To install docker:
 369
 370 .. code:: bash
 371
 372     $ sudo yum remove docker docker-common docker-selinux docker-engine
 373     $ sudo yum install -y yum-utils  device-mapper-persistent-data  lvm2
 374     $ sudo yum-config-manager   --add-repo    https://download.docker.com/linux/centos/docker-ce.repo
 375     $ sudo yum-config-manager --enable docker-ce-edge
 376     $ sudo yum-config-manager --enable docker-ce-test
 377     $ sudo yum install docker-ce
 378     $ sudo usermod -aG docker <username>
 379     $ sudo systemctl status docker
 380
 381 Replace <username> above with an appropriate user name.
 382
 383 .. note::
 384    If this is the first time you are installing a package from a recently added
 385    repository, you will be prompted to accept the GPG key, and the key’s
 386    fingerprint will be shown. Verify that the fingerprint is correct, and if so,
 387    accept the key. The fingerprint should match060A 61C5 1B55 8A7F 742B 77AA C52F
 388    EB6B 621E 9F35.
 389
 390         Retrieving key from https://download.docker.com/linux/centos/gpg
 391         Importing GPG key 0x621E9F35:
 392          Userid     : "Docker Release (CE rpm) <docker@docker.com>"
 393          Fingerprint: 060a 61c5 1b55 8a7f 742b 77aa c52f eb6b 621e 9f35
 394          From       : https://download.docker.com/linux/centos/gpg
 395         Is this ok [y/N]: y
 396
 397 Proxy Configuration:
 398 ^^^^^^^^^^^^^^^^^^^^
 399 .. note::
 400    This applies for both CentOS and Ubuntu.
 401
 402 If you are behind an HTTP or HTTPS proxy server, you will need to add this
 403 configuration in the Docker systemd service file.
 404
 405 1. Create a systemd drop-in directory for the docker service:
 406
 407 .. code:: bash
 408
 409    $ sudo mkdir -p /etc/systemd/system/docker.service.d
 410
 411 2. Create a file
 412 called /etc/systemd/system/docker.service.d/http-proxy.conf that adds
 413 the HTTP_PROXY environment variable:
 414
 415 .. code:: bash
 416
 417    [Service]
 418    Environment="HTTP_PROXY=http://proxy.example.com:80/"
 419
 420 Or, if you are behind an HTTPS proxy server, create a file
 421 called /etc/systemd/system/docker.service.d/https-proxy.conf that adds
 422 the HTTPS_PROXY environment variable:
 423
 424 .. code:: bash
 425
 426     [Service]
 427     Environment="HTTPS_PROXY=https://proxy.example.com:443/"
 428
 429 Or create a single file with all the proxy configurations:
 430 /etc/systemd/system/docker.service.d/proxy.conf
 431
 432 .. code:: bash
 433
 434     [Service]
 435     Environment="HTTP_PROXY=http://proxy.example.com:80/"
 436     Environment="HTTPS_PROXY=https://proxy.example.com:443/"
 437     Environment="FTP_PROXY=ftp://proxy.example.com:443/"
 438     Environment="NO_PROXY=localhost"
 439
 440 3. Flush changes:
 441
 442 .. code:: bash
 443
 444     $ sudo systemctl daemon-reload
 445
 446 4. Restart Docker:
 447
 448 .. code:: bash
 449
 450     $ sudo systemctl restart docker
 451
 452 5. Check docker environment variables:
 453
 454 .. code:: bash
 455
 456     sudo systemctl show --property=Environment docker
 457
 458 Test docker installation
 459 ^^^^^^^^^^^^^^^^^^^^^^^^
 460 .. note::
 461    This applies for both CentOS and Ubuntu.
 462
 463 .. code:: bash
 464
 465    $ sudo docker run hello-world
 466
 467 The output should be something like:
 468
 469 .. code:: bash
 470
 471    Unable to find image 'hello-world:latest' locally
 472    latest: Pulling from library/hello-world
 473    5b0f327be733: Pull complete
 474    Digest: sha256:07d5f7800dfe37b8c2196c7b1c524c33808ce2e0f74e7aa00e603295ca9a0972
 475    Status: Downloaded newer image for hello-world:latest
 476
 477    Hello from Docker!
 478    This message shows that your installation appears to be working correctly.
 479
 480    To generate this message, Docker took the following steps:
 481     1. The Docker client contacted the Docker daemon.
 482     2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
 483     3. The Docker daemon created a new container from that image which runs the
 484        executable that produces the output you are currently reading.
 485     4. The Docker daemon streamed that output to the Docker client, which sent it
 486        to your terminal.
 487
 488 To try something more ambitious, you can run an Ubuntu container with:
 489
 490 .. code:: bash
 491
 492     $ docker run -it ubuntu bash
 493
 494 Build and Run Collectd Docker Image
 495 -----------------------------------
 496
 497 Download the collectd docker image
 498 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 499 If you wish to use a pre-built barometer image, you can pull the barometer
 500 image from https://hub.docker.com/r/opnfv/barometer-collectd/
 501
 502 .. code:: bash
 503
 504     $ docker pull opnfv/barometer-collectd
 505
 506 Build the collectd docker image
 507 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 508
 509 .. code:: bash
 510
 511     $ git clone https://gerrit.opnfv.org/gerrit/barometer
 512     $ cd barometer/docker/barometer-collectd
 513     $ sudo docker build -t opnfv/barometer-collectd --build-arg http_proxy=`echo $http_proxy` \
 514       --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
 515
 516 .. note::
 517    Main directory of barometer source code (directory that contains 'docker',
 518    'docs', 'src' and systems sub-directories) will be referred as
 519    ``<BAROMETER_REPO_DIR>``
 520
 521
 522 .. note::
 523    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs to be
 524    passed only if system is behind an HTTP or HTTPS proxy server.
 525
 526 Check the docker images:
 527
 528 .. code:: bash
 529
 530    $ sudo docker images
 531
 532 Output should contain a barometer-collectd image:
 533
 534 .. code::
 535
 536    REPOSITORY                   TAG                 IMAGE ID            CREATED             SIZE
 537    opnfv/barometer-collectd     latest              05f2a3edd96b        3 hours ago         1.2GB
 538    centos                       7                   196e0ce0c9fb        4 weeks ago         197MB
 539    centos                       latest              196e0ce0c9fb        4 weeks ago         197MB
 540    hello-world                  latest              05a3bd381fc2        4 weeks ago         1.84kB
 541
 542 Run the collectd docker image
 543 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 544 .. code:: bash
 545
 546    $ cd <BAROMETER_REPO_DIR>
 547    $ sudo docker run -ti --net=host -v \
 548    `pwd`/src/collectd/collectd_sample_configs:/opt/collectd/etc/collectd.conf.d \
 549    -v /var/run:/var/run -v /tmp:/tmp --privileged opnfv/barometer-collectd
 550
 551 .. note::
 552    The docker collectd image contains configuration for all the collectd
 553    plugins. In the command above we are overriding
 554    /opt/collectd/etc/collectd.conf.d by mounting a host directory
 555    src/collectd/collectd_sample_configs that contains only the sample
 556    configurations we are interested in running. *It's important to do
 557    this if you don't have DPDK, or RDT installed on the host*.
 558    Sample configurations can be found at:
 559    https://github.com/opnfv/barometer/tree/master/src/collectd/collectd_sample_configs
 560
 561 Check your docker image is running
 562
 563 .. code:: bash
 564
 565    sudo docker ps
 566
 567 To make some changes when the container is running run:
 568
 569 .. code:: bash
 570
 571    sudo docker exec -ti <CONTAINER ID> /bin/bash
 572
 573 Build and Run InfluxDB and Grafana docker images
 574 ------------------------------------------------
 575
 576 Overview
 577 ^^^^^^^^
 578 The barometer-influxdb image is based on the influxdb:1.3.7 image from the influxdb dockerhub. To
 579 view detils on the base image please visit
 580 `https://hub.docker.com/_/influxdb/  <https://hub.docker.com/_/influxdb/>`_ Page includes details of
 581 exposed ports and configurable enviromental variables of the base image.
 582
 583 The barometer-grafana image is based on grafana:4.6.3 image from the grafana dockerhub. To view
 584 details on the base image please visit
 585 `https://hub.docker.com/r/grafana/grafana/ <https://hub.docker.com/r/grafana/grafana/>`_ Page
 586 includes details on exposed ports and configurable enviromental variables of the base image.
 587
 588 The barometer-grafana image includes pre-configured source and dashboards to display statistics exposed
 589 by the barometer-collectd image. The default datasource is an influxdb database running on localhost
 590 but the address of the influxdb server can be modified when launching the image by setting the
 591 environmental variables influxdb_host to IP or hostname of host on which influxdb server is running.
 592
 593 Additional dashboards can be added to barometer-grafana by mapping a volume to /opt/grafana/dashboards.
 594 Incase where a folder is mounted to this volume only files included in this folder will be visible
 595 inside barometer-grafana. To ensure all default files are also loaded please ensure they are included in
 596 volume folder been mounted. Appropriate example are given in section `Run the Grafana docker image`_
 597
 598 Download the InfluxDB and Grafana docker images
 599 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 600 If you wish to use pre-built barometer project's influxdb and grafana images, you can pull the
 601 images from https://hub.docker.com/r/opnfv/barometer-influxdb/ and https://hub.docker.com/r/opnfv/barometer-grafana/
 602
 603 .. note::
 604    If your preference is to build images locally please see sections `Build InfluxDB Docker Image`_ and
 605    `Build Grafana Docker Image`_
 606
 607 .. code:: bash
 608
 609     $ docker pull opnfv/barometer-influxdb
 610     $ docker pull opnfv/barometer-grafana
 611
 612 .. note::
 613    If you have pulled the pre-built barometer-influxdb and barometer-grafana images there is no
 614    requirement to complete steps outlined in  sections `Build InfluxDB Docker Image`_ and
 615    `Build Grafana Docker Image`_ and you can proceed directly to section
 616    `Run the Influxdb and Grafana Images`_ If you wish to run the barometer-influxdb and
 617    barometer-grafana images via Docker Compose proceed directly to section
 618    `Docker Compose`_.
 619
 620 Build InfluxDB docker image
 621 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 622
 623 Build influxdb image from Dockerfile
 624
 625 .. code:: bash
 626
 627   $ cd barometer/docker/barometer-influxdb
 628   $ sudo docker build -t opnfv/barometer-influxdb --build-arg http_proxy=`echo $http_proxy` \
 629     --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
 630
 631 .. note::
 632    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs to
 633    be passed only if system is behind an HTTP or HTTPS proxy server.
 634
 635 Check the docker images:
 636
 637 .. code:: bash
 638
 639    $ sudo docker images
 640
 641 Output should contain an influxdb image:
 642
 643 .. code::
 644
 645    REPOSITORY                   TAG                 IMAGE ID            CREATED            SIZE
 646    opnfv/barometer-influxdb     latest              1e4623a59fe5        3 days ago         191MB
 647
 648 Build Grafana docker image
 649 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 650
 651 Build Grafana image from Dockerfile
 652
 653 .. code:: bash
 654
 655   $ cd barometer/docker/barometer-grafana
 656   $ sudo docker build -t opnfv/barometer-grafana --build-arg http_proxy=`echo $http_proxy` \
 657     --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
 658
 659 .. note::
 660    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs to
 661    be passed only if system is behind an HTTP or HTTPS proxy server.
 662
 663 Check the docker images:
 664
 665 .. code:: bash
 666
 667    $ sudo docker images
 668
 669 Output should contain an influxdb image:
 670
 671 .. code::
 672
 673    REPOSITORY                   TAG                 IMAGE ID            CREATED             SIZE
 674    opnfv/barometer-grafana      latest              05f2a3edd96b        3 hours ago         1.2GB
 675
 676 Run the Influxdb and Grafana Images
 677 -----------------------------------
 678
 679 Run the InfluxDB docker image
 680 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 681 .. code:: bash
 682
 683    $ sudo docker run -tid -v /var/lib/influxdb:/var/lib/influxdb -p 8086:8086 -p 25826:25826  opnfv/barometer-influxdb
 684
 685 Check your docker image is running
 686
 687 .. code:: bash
 688
 689    sudo docker ps
 690
 691 To make some changes when the container is running run:
 692
 693 .. code:: bash
 694
 695    sudo docker exec -ti <CONTAINER ID> /bin/bash
 696
 697 Run the Grafana docker image
 698 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 699
 700 Connecting to an influxdb instance running on local system and adding own custom dashboards
 701
 702 .. code:: bash
 703
 704    $ cd <BAROMETER_REPO_DIR>
 705    $ sudo docker run -tid -v /var/lib/grafana:/var/lib/grafana -v ${PWD}/docker/barometer-grafana/dashboards:/opt/grafana/dashboards \
 706      -p 3000:3000 opnfv/barometer-grafana
 707
 708 Connecting to an influxdb instance running on remote system with hostname of someserver and IP address
 709 of 192.168.121.111
 710
 711 .. code:: bash
 712
 713    $ sudo docker run -tid -v /var/lib/grafana:/var/lib/grafana -p 3000:3000 -e \
 714      influxdb_host=someserver --add-host someserver:192.168.121.111 opnfv/barometer-grafana
 715
 716 Check your docker image is running
 717
 718 .. code:: bash
 719
 720    sudo docker ps
 721
 722 To make some changes when the container is running run:
 723
 724 .. code:: bash
 725
 726    sudo docker exec -ti <CONTAINER ID> /bin/bash
 727
 728 Connect to <host_ip>:3000 with a browser and log into grafana: admin/admin
 729
 730
 731 Build and Run VES and Kafka Docker Images
 732 ------------------------------------------
 733
 734 Download VES and Kafka docker images
 735 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 736
 737 If you wish to use pre-built barometer project's VES and kafka images, you can pull the
 738 images from https://hub.docker.com/r/opnfv/barometer-ves/ and  https://hub.docker.com/r/opnfv/barometer-kafka/
 739
 740 .. note::
 741    If your preference is to build images locally please see sections `Build the Kafka Image`_ and
 742    `Build VES Image`_
 743
 744 .. code:: bash
 745
 746     $ docker pull opnfv/barometer-kafka
 747     $ docker pull opnfv/barometer-ves
 748
 749 .. note::
 750    If you have pulled the pre-built images there is no requirement to complete steps outlined
 751    in sections `Build Kafka Docker Image`_ and `Build VES Docker Image`_ and you can proceed directly to section
 752    `Run Kafka Docker Image`_ If you wish to run the docker images via Docker Compose proceed directly to section `Docker Compose`_.
 753
 754 Build Kafka docker image
 755 ^^^^^^^^^^^^^^^^^^^^^^^^
 756
 757 Build Kafka docker image:
 758
 759 .. code:: bash
 760
 761     $ cd barometer/docker/barometer-kafka
 762     $ sudo docker build -t opnfv/barometer-kafka --build-arg http_proxy=`echo $http_proxy` \
 763       --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
 764
 765 .. note::
 766    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs
 767    to be passed only if system is behind an HTTP or HTTPS proxy server.
 768
 769 Check the docker images:
 770
 771 .. code:: bash
 772
 773    $ sudo docker images
 774
 775 Output should contain a barometer image:
 776
 777 .. code::
 778
 779    REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
 780    opnfv/barometer-kafka     latest              05f2a3edd96b        3 hours ago         1.2GB
 781
 782 Build VES docker image
 783 ^^^^^^^^^^^^^^^^^^^^^^
 784
 785 Build VES application docker image:
 786
 787 .. code:: bash
 788
 789     $ cd barometer/docker/barometer-ves
 790     $ sudo docker build -t opnfv/barometer-ves --build-arg http_proxy=`echo $http_proxy` \
 791       --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
 792
 793 .. note::
 794    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs
 795    to be passed only if system is behind an HTTP or HTTPS proxy server.
 796
 797 Check the docker images:
 798
 799 .. code:: bash
 800
 801    $ sudo docker images
 802
 803 Output should contain a barometer image:
 804
 805 .. code::
 806
 807    REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
 808    opnfv/barometer-ves       latest              05f2a3edd96b        3 hours ago         1.2GB
 809
 810 Run Kafka docker image
 811 ^^^^^^^^^^^^^^^^^^^^^^
 812
 813 .. note::
 814    Before running Kafka an instance of Zookeeper must be running for the Kafka broker to register
 815    with. Zookeeper can be running locally or on a remote platform. Kafka's broker_id and address of
 816    its zookeeper instance can be configured by setting values for environmental variables 'broker_id'
 817    and 'zookeeper_node'. In instance where 'broker_id' and/or 'zookeeper_node' is not set the default
 818    setting of broker_id=0 and zookeeper_node=localhost is used. In intance where Zookeeper is running
 819    on same node as Kafka and there is a one to one relationship between Zookeeper and Kafka, default
 820    setting can be used. The docker argument `add-host` adds hostname and IP address to
 821    /etc/hosts file in container
 822
 823 Run zookeeper docker image:
 824
 825 .. code:: bash
 826
 827    $ sudo docker run -tid --net=host -p 2181:2181 zookeeper:3.4.11
 828
 829 Run kafka docker image which connects with a zookeeper instance running on same node with a 1:1 relationship
 830
 831 .. code:: bash
 832
 833    $ sudo docker run -tid --net=host -p 9092:9092 opnfv/barometer-kafka
 834
 835
 836 Run kafka docker image which connects with a zookeeper instance running on a node with IP address of
 837 192.168.121.111 using broker ID of 1
 838
 839 .. code:: bash
 840
 841    $ sudo docker run -tid --net=host -p 9092:9092 --env broker_id=1 --env zookeeper_node=zookeeper --add-host \
 842      zookeeper:192.168.121.111 opnfv/barometer-kafka
 843
 844 Run VES Application docker image
 845 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 846 .. note::
 847    VES application uses configuration file ves_app_config.conf from directory
 848    barometer/3rd_party/collectd-ves-app/ves_app/config/ and host.yaml file from
 849    barometer/3rd_party/collectd-ves-app/ves_app/yaml/ by default. If you wish to use a custom config
 850    file it should be mounted to mount point /opt/ves/config/ves_app_config.conf. To use an alternative yaml
 851    file from folder barometer/3rd_party/collectd-ves-app/ves_app/yaml the name of the yaml file to use
 852    should be passed as an additional command. If you wish to use a custom file the file should be
 853    mounted to mount point /opt/ves/yaml/ Please see examples below
 854
 855 Run VES docker image with default configuration
 856
 857 .. code:: bash
 858
 859    $ sudo docker run -tid --net=host opnfv/barometer-ves
 860
 861 Run VES docker image with guest.yaml files from barometer/3rd_party/collectd-ves-app/ves_app/yaml/
 862
 863 .. code:: bash
 864
 865    $ sudo docker run -tid --net=host opnfv/barometer-ves guest.yaml
 866
 867
 868 Run VES docker image with using custom config and yaml files. In example below yaml/ folder cotains
 869 file named custom.yaml
 870
 871 .. code:: bash
 872
 873    $ sudo docker run -tid --net=host -v ${PWD}/custom.config:/opt/ves/config/ves_app_config.conf \
 874      -v ${PWD}/yaml/:/opt/ves/yaml/ opnfv/barometer-ves custom.yaml
 875
 876 Build and Run LocalAgent and Redis Docker Images
 877 -----------------------------------------------------
 878
 879 Download LocalAgent docker images
 880 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 881
 882 If you wish to use pre-built barometer project's LocalAgent images, you can pull the
 883 images from https://hub.docker.com/r/opnfv/barometer-localagent/
 884
 885 .. note::
 886    If your preference is to build images locally please see sections `Build LocalAgent Docker Image`_
 887
 888 .. code:: bash
 889
 890     $ docker pull opnfv/barometer-localagent
 891
 892 .. note::
 893    If you have pulled the pre-built images there is no requirement to complete steps outlined
 894    in sections `Build LocalAgent Docker Image`_ and you can proceed directly to section
 895    `Run LocalAgent Docker Image`_ If you wish to run the docker images via Docker Compose proceed directly to section `Docker Compose`_.
 896
 897 Build LocalAgent docker image
 898 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 899
 900 Build LocalAgent docker image:
 901
 902 .. code:: bash
 903
 904     $ cd barometer/docker/barometer-dma
 905     $ sudo docker build -t opnfv/barometer-dma --build-arg http_proxy=`echo $http_proxy` \
 906       --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
 907
 908 .. note::
 909    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs
 910    to be passed only if system is behind an HTTP or HTTPS proxy server.
 911
 912 Check the docker images:
 913
 914 .. code:: bash
 915
 916    $ sudo docker images
 917
 918 Output should contain a barometer image:
 919
 920 .. code::
 921
 922    REPOSITORY                   TAG                 IMAGE ID            CREATED             SIZE
 923    opnfv/barometer-dma          latest              2f14fbdbd498        3 hours ago         941 MB
 924
 925 Run Redis docker image
 926 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 927
 928 .. note::
 929    Before running LocalAgent, Redis must be running.
 930
 931 Run Redis docker image:
 932
 933 .. code:: bash
 934
 935    $ sudo docker run -tid -p 6379:6379 --name barometer-redis redis
 936
 937 Check your docker image is running
 938
 939 .. code:: bash
 940
 941    sudo docker ps
 942
 943 Run LocalAgent docker image
 944 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 945 .. note::
 946
 947 Run LocalAgent docker image with default configuration
 948
 949 .. code:: bash
 950
 951    $ cd barometer/docker/barometer-dma
 952    $ sudo mkdir /etc/barometer-dma
 953    $ sudo cp ../../src/dma/examples/config.toml /etc/barometer-dma/
 954    $ sudo vi /etc/barometer-dma/config.toml
 955    (edit amqp_password and os_password:OpenStack admin password)
 956
 957    $ sudo su -
 958    (When there is no key for SSH access authentication)
 959    # ssh-keygen
 960    (Press Enter until done)
 961    (Backup if necessary)
 962    # cp ~/.ssh/authorized_keys ~/.ssh/authorized_keys_org
 963    # cat ~/.ssh/authorized_keys_org ~/.ssh/id_rsa.pub \
 964      > ~/.ssh/authorized_keys
 965    # exit
 966
 967    $ sudo docker run -tid --net=host --name server \
 968      -v /etc/barometer-dma:/etc/barometer-dma \
 969      -v /root/.ssh/id_rsa:/root/.ssh/id_rsa \
 970      -v /etc/collectd/collectd.conf.d:/etc/collectd/collectd.conf.d \
 971      opnfv/barometer-dma /server
 972
 973    $ sudo docker run -tid --net=host --name infofetch \
 974      -v /etc/barometer-dma:/etc/barometer-dma \
 975      -v /var/run/libvirt:/var/run/libvirt \
 976      opnfv/barometer-dma /infofetch
 977
 978    (Execute when installing the threshold evaluation binary)
 979    $ sudo docker cp infofetch:/threshold ./
 980    $ sudo ln -s ${PWD}/threshold /usr/local/bin/
 981
 982 Docker Compose
 983 --------------
 984
 985 Install docker-compose
 986 ^^^^^^^^^^^^^^^^^^^^^^
 987
 988 On the node where you want to run influxdb + grafana or the node where you want to run the VES app
 989 zookeeper and Kafka containers together:
 990
 991 .. note::
 992    The default configuration for all these containers is to run on the localhost. If this is not
 993    the model you want to use then please make the appropriate configuration changes before launching
 994    the docker containers.
 995
 996 1. Start by installing docker compose
 997
 998 .. code:: bash
 999
1000    $ sudo curl -L https://github.com/docker/compose/releases/download/1.17.0/docker-compose-`uname -s`-`uname -m` -o /usr/bin/docker-compose
1001
1002 .. note::
1003    Use the latest Compose release number in the download command. The above command is an example,
1004    and it may become out-of-date. To ensure you have the latest version, check the Compose repository
1005    release page on GitHub.
1006
1007 2. Apply executable permissions to the binary:
1008
1009 .. code:: bash
1010
1011    $ sudo chmod +x /usr/bin/docker-compose
1012
1013 3. Test the installation.
1014
1015 .. code:: bash
1016
1017   $ sudo docker-compose --version
1018
1019 Run the InfluxDB and Grafana containers using docker compose
1020 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1021
1022 Launch containers:
1023
1024 .. code:: bash
1025
1026    $ cd barometer/docker/compose/influxdb-grafana/
1027    $ sudo docker-compose up -d
1028
1029 Check your docker images are running
1030
1031 .. code:: bash
1032
1033    $ sudo docker ps
1034
1035 Connect to <host_ip>:3000 with a browser and log into grafana: admin/admin
1036
1037 Run the Kafka, zookeeper and VES containers using docker compose
1038 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1039
1040 Launch containers:
1041
1042 .. code:: bash
1043
1044    $ cd barometer/docker/compose/ves/
1045    $ sudo docker-compose up -d
1046
1047 Check your docker images are running
1048
1049 .. code:: bash
1050
1051    $ sudo docker ps
1052
1053 Testing the docker image
1054 ^^^^^^^^^^^^^^^^^^^^^^^^
1055 TODO
1056
1057 References
1058 ^^^^^^^^^^^
1059 .. [1] https://docs.docker.com/engine/admin/systemd/#httphttps-proxy
1060 .. [2] https://docs.docker.com/engine/installation/linux/docker-ce/centos/#install-using-the-repository
1061 .. [3] https://docs.docker.com/engine/userguide/
1062
1063