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