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