docs/release/userguide/installguide.docker.rst

   1 .. _barometer-docker-userguide:
   2 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4 .. (c) Anuket and others
   5
   6 =====================================
   7 Anuket Barometer Docker Install 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 For an alternative installation method using ansible, please see the :ref:`Barometer One Click Install Guide <barometer-oneclick-userguide>`.
  35
  36 For post-installation verification and troubleshooting, please see the :ref:`Barometer post installation guide <barometer-postinstall>`.
  37
  38 Barometer Docker Images Description
  39 -----------------------------------
  40
  41 .. Describe the specific features and how it is realised in the scenario in a brief manner
  42 .. to ensure the user understand the context for the user guide instructions to follow.
  43
  44 Barometer Collectd Image
  45 ^^^^^^^^^^^^^^^^^^^^^^^^
  46 The barometer collectd docker image gives you a collectd installation that includes all
  47 the barometer plugins.
  48
  49 .. note::
  50    The Dockerfile is available in the docker/barometer-collectd directory in the barometer repo.
  51    The Dockerfile builds a CentOS 8 docker image.
  52    The container MUST be run as a privileged container.
  53
  54 Collectd is a daemon which collects system performance statistics periodically
  55 and provides a variety of mechanisms to publish the collected metrics. It
  56 supports more than 90 different input and output plugins. Input plugins
  57 retrieve metrics and publish them to the collectd deamon, while output plugins
  58 publish the data they receive to an end point. Collectd also has infrastructure
  59 to support thresholding and notification.
  60
  61 Collectd docker image has enabled the following collectd plugins (in addition
  62 to the standard collectd plugins):
  63
  64 * hugepages plugin
  65 * Open vSwitch events Plugin
  66 * Open vSwitch stats Plugin
  67 * mcelog plugin
  68 * PMU plugin
  69 * RDT plugin
  70 * virt
  71 * SNMP Agent
  72 * Kafka_write plugin
  73
  74 Plugins and third party applications in Barometer repository that will be available in the
  75 docker image:
  76
  77 * Open vSwitch PMD stats
  78 * ONAP VES application
  79 * gnocchi plugin
  80 * aodh plugin
  81 * Legacy/IPMI
  82
  83 InfluxDB + Grafana Docker Images
  84 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  85
  86 The Barometer project's InfluxDB and Grafana docker images are 2 docker images that database and graph
  87 statistics reported by the Barometer collectd docker. InfluxDB is an open-source time series database
  88 tool which stores the data from collectd for future analysis via Grafana, which is a open-source
  89 metrics anlytics and visualisation suite which can be accessed through any browser.
  90
  91 VES + Kafka Docker Images
  92 ^^^^^^^^^^^^^^^^^^^^^^^^^
  93
  94 The Barometer project's VES application and Kafka docker images are based on a CentOS 7 image. Kafka
  95 docker image has a dependancy on `Zookeeper <https://zookeeper.apache.org/>`_. Kafka must be able to
  96 connect and register with an instance of Zookeeper that is either running on local or remote host.
  97 Kafka recieves and stores metrics recieved from Collectd. VES application pulls latest metrics from Kafka
  98 which it normalizes into VES format for sending to a VES collector. Please see details in
  99 :ref:`VES Application User Guide <barometer-ves-userguide>`
 100
 101 Installing Docker
 102 -----------------
 103 .. Describe the specific capabilities and usage for <XYZ> feature.
 104 .. Provide enough information that a user will be able to operate the feature on a deployed scenario.
 105
 106 .. note::
 107    The below sections provide steps for manual installation and configuration
 108    of docker images. They are not neccessary if docker images were installed with
 109    use of Ansible-Playbook.
 110
 111 On Ubuntu
 112 ^^^^^^^^^
 113 .. note::
 114    * sudo permissions are required to install docker.
 115    * These instructions are for Ubuntu 16.10
 116
 117 To install docker:
 118
 119 .. code:: bash
 120
 121     $ sudo apt-get install curl
 122     $ sudo curl -fsSL https://get.docker.com/ | sh
 123     $ sudo usermod -aG docker <username>
 124     $ sudo systemctl status docker
 125
 126 Replace <username> above with an appropriate user name.
 127
 128 On CentOS
 129 ^^^^^^^^^^
 130 .. note::
 131    * sudo permissions are required to install docker.
 132    * These instructions are for CentOS 7
 133
 134 To install docker:
 135
 136 .. code:: bash
 137
 138     $ sudo yum remove docker docker-common docker-selinux docker-engine
 139     $ sudo yum install -y yum-utils  device-mapper-persistent-data  lvm2
 140     $ sudo yum-config-manager   --add-repo    https://download.docker.com/linux/centos/docker-ce.repo
 141     $ sudo yum-config-manager --enable docker-ce-edge
 142     $ sudo yum-config-manager --enable docker-ce-test
 143     $ sudo yum install docker-ce
 144     $ sudo usermod -aG docker <username>
 145     $ sudo systemctl status docker
 146
 147 Replace <username> above with an appropriate user name.
 148
 149 .. note::
 150    If this is the first time you are installing a package from a recently added
 151    repository, you will be prompted to accept the GPG key, and the key’s
 152    fingerprint will be shown. Verify that the fingerprint is correct, and if so,
 153    accept the key. The fingerprint should match060A 61C5 1B55 8A7F 742B 77AA C52F
 154    EB6B 621E 9F35.
 155
 156         Retrieving key from https://download.docker.com/linux/centos/gpg
 157         Importing GPG key 0x621E9F35:
 158 .. ::
 159          Userid     : "Docker Release (CE rpm) <docker@docker.com>"
 160          Fingerprint: 060a 61c5 1b55 8a7f 742b 77aa c52f eb6b 621e 9f35
 161          From       : https://download.docker.com/linux/centos/gpg
 162         Is this ok [y/N]: y
 163
 164 Manual proxy configuration for docker
 165 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 166
 167 .. note::
 168    This applies for both CentOS and Ubuntu.
 169
 170 If you are behind an HTTP or HTTPS proxy server, you will need to add this
 171 configuration in the Docker systemd service file.
 172
 173 1. Create a systemd drop-in directory for the docker service:
 174
 175 .. code:: bash
 176
 177    $ sudo mkdir -p /etc/systemd/system/docker.service.d
 178
 179 2. Create a file
 180 called /etc/systemd/system/docker.service.d/http-proxy.conf that adds
 181 the HTTP_PROXY environment variable:
 182
 183 .. code:: bash
 184
 185    [Service]
 186    Environment="HTTP_PROXY=http://proxy.example.com:80/"
 187
 188 Or, if you are behind an HTTPS proxy server, create a file
 189 called /etc/systemd/system/docker.service.d/https-proxy.conf that adds
 190 the HTTPS_PROXY environment variable:
 191
 192 .. code:: bash
 193
 194     [Service]
 195     Environment="HTTPS_PROXY=https://proxy.example.com:443/"
 196
 197 Or create a single file with all the proxy configurations:
 198 /etc/systemd/system/docker.service.d/proxy.conf
 199
 200 .. code:: bash
 201
 202     [Service]
 203     Environment="HTTP_PROXY=http://proxy.example.com:80/"
 204     Environment="HTTPS_PROXY=https://proxy.example.com:443/"
 205     Environment="FTP_PROXY=ftp://proxy.example.com:443/"
 206     Environment="NO_PROXY=localhost"
 207
 208 3. Flush changes:
 209
 210 .. code:: bash
 211
 212     $ sudo systemctl daemon-reload
 213
 214 4. Restart Docker:
 215
 216 .. code:: bash
 217
 218     $ sudo systemctl restart docker
 219
 220 5. Check docker environment variables:
 221
 222 .. code:: bash
 223
 224     sudo systemctl show --property=Environment docker
 225
 226 Test docker installation
 227 ^^^^^^^^^^^^^^^^^^^^^^^^
 228 .. note::
 229    This applies for both CentOS and Ubuntu.
 230
 231 .. code:: bash
 232
 233    $ sudo docker run hello-world
 234
 235 The output should be something like:
 236
 237 .. code:: bash
 238
 239    Trying to pull docker.io/library/hello-world...Getting image source signatures
 240    Copying blob 0e03bdcc26d7 done
 241    Copying config bf756fb1ae done
 242    Writing manifest to image destination
 243    Storing signatures
 244
 245    Hello from Docker!
 246    This message shows that your installation appears to be working correctly.
 247
 248    To generate this message, Docker took the following steps:
 249     1. The Docker client contacted the Docker daemon.
 250     2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
 251     3. The Docker daemon created a new container from that image which runs the
 252        executable that produces the output you are currently reading.
 253     4. The Docker daemon streamed that output to the Docker client, which sent it
 254        to your terminal.
 255
 256    To try something more ambitious, you can run an Ubuntu container with:
 257     $ docker run -it ubuntu bash
 258
 259    Share images, automate workflows, and more with a free Docker ID:
 260     https://hub.docker.com/
 261
 262    For more examples and ideas, visit:
 263     https://docs.docker.com/get-started/
 264
 265 Build and Run Collectd Docker Image
 266 -----------------------------------
 267
 268 Collectd-barometer flavors
 269 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 270
 271 Before starting to build and run the Collectd container, understand the available
 272 flavors of Collectd containers:
 273
 274 * barometer-collectd - stable release, based on collectd 5.12
 275 * barometer-collectd-latest - release based on collectd 'main' branch
 276 * barometer-collectd-experimental - release based on collectd 'main'
 277   branch that can also include a set of experimental (not yet merged into
 278   upstream) pull requests
 279
 280 .. note::
 281    Experimental container is not tested across various OS'es and the stability
 282    of the container can change. Usage of experimental flavor is at users risk.
 283
 284 Stable `barometer-collectd` container is intended for work in production
 285 environment as it is based on latest collectd official release.
 286 `barometer-collectd-latest` and `barometer-collectd-experimental` containers
 287 can be used in order to try new collectd features.
 288 All flavors are located in `barometer` git repository - respective Dockerfiles
 289 are stored in subdirectories of `docker/` directory
 290
 291
 292 .. code:: bash
 293
 294     $ git clone https://gerrit.opnfv.org/gerrit/barometer
 295     $ ls barometer/docker|grep collectd
 296     barometer-collectd
 297     barometer-collectd-latest
 298     barometer-collectd-experimental
 299
 300 .. note::
 301    Main directory of barometer source code (directory that contains 'docker',
 302    'docs', 'src' and systems sub-directories) will be referred as
 303    ``<BAROMETER_REPO_DIR>``
 304
 305 Download the collectd docker image
 306 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 307 If you wish to use a pre-built barometer image, you can pull the barometer
 308 image from `dockerhub <https://hub.docker.com/r/opnfv/barometer-collectd/>`_
 309
 310 .. code:: bash
 311
 312     $ docker pull opnfv/barometer-collectd
 313
 314 Build stable collectd container
 315 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 316
 317 .. code:: bash
 318
 319     $ cd <BAROMETER_REPO_DIR>/docker/barometer-collectd
 320     $ sudo docker build -t opnfv/barometer-collectd --build-arg http_proxy=`echo $http_proxy` \
 321       --build-arg https_proxy=`echo $https_proxy` --network=host -f Dockerfile .
 322
 323 .. note::
 324    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs to be
 325    passed only if system is behind an HTTP or HTTPS proxy server.
 326
 327 Check the docker images:
 328
 329 .. code:: bash
 330
 331    $ sudo docker images
 332
 333 Output should contain a barometer-collectd image:
 334
 335 .. code::
 336
 337    REPOSITORY                   TAG                 IMAGE ID            CREATED             SIZE
 338    opnfv/barometer-collectd     latest              05f2a3edd96b        3 hours ago         1.2GB
 339    centos                       7                   196e0ce0c9fb        4 weeks ago         197MB
 340    centos                       latest              196e0ce0c9fb        4 weeks ago         197MB
 341    hello-world                  latest              05a3bd381fc2        4 weeks ago         1.84kB
 342
 343 .. note::
 344    If you do not plan to use `barometer-collectd-latest` and
 345    `barometer-collectd-experimental` containers, then you can proceed directly
 346    to section `Run the collectd stable docker image`_
 347
 348
 349 Build barometer-collectd-latest container
 350 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 351
 352 .. code:: bash
 353
 354     $ cd <BAROMETER_REPO_DIR>
 355     $ sudo docker build -t opnfv/barometer-collectd-latest \
 356      --build-arg http_proxy=`echo $http_proxy` \
 357      --build-arg https_proxy=`echo $https_proxy` --network=host -f \
 358      docker/barometer-collectd-latest/Dockerfile .
 359
 360 .. note::
 361    For `barometer-collectd-latest` and `barometer-collectd-experimental` containers
 362    proxy parameters should be passed only if system is behind an HTTP or HTTPS
 363    proxy server (same as for stable collectd container)
 364
 365 Build barometer-collectd-experimental container
 366 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 367
 368 The barometer-collectd-experimental container use the ``main`` branch of
 369 collectd, but allows the user to apply a number of pull requests, which are
 370 passed via the COLLECTD_PULL_REQUESTS build arg, which is passed to docker as
 371 shown in the example below.
 372 COLLECTD_PULL_REQUESTS should be a comma-delimited string of pull request IDs.
 373
 374 .. code:: bash
 375
 376     $ cd <BAROMETER_REPO_DIR>
 377     $ sudo docker build -t opnfv/barometer-collectd-experimental \
 378      --build-arg http_proxy=`echo $http_proxy` \
 379      --build-arg https_proxy=`echo $https_proxy` \
 380      --build-arg COLLECTD_PULL_REQUESTS=1234,5678 \
 381      --network=host -f docker/barometer-collectd-experimental/Dockerfile .
 382
 383 .. note::
 384    For `barometer-collectd-latest` and `barometer-collectd-experimental` containers
 385    proxy parameters should be passed only if system is behind an HTTP or HTTPS
 386    proxy server (same as for stable collectd container)
 387
 388 Build collectd-6
 389 ^^^^^^^^^^^^^^^^
 390
 391 The barometer-collectd-experimental Dockerfile can be used to build
 392 collectd-6.0, which is currently under development. In order to do this, the
 393 ``COLLECTD_FLAVOR`` build arg can be passed to the docker build command.
 394 The optional ``COLLECTD_PULL_REQUESTS`` arg can be passed as well, to test
 395 proposed patches to collectd.
 396
 397 .. code:: bash
 398
 399    $ cd <BAROMETER_REPO_DIR>
 400    $ sudo docker build -t opnfv/barometer-collectd-6 \
 401      --build-arg COLLECTD_FLAVOR=collectd-6 \
 402      --build-arg COLLECTD_PULL_REQUESTS=1234,5678 \
 403      --network=host -f docker/barometer-collectd-experimental/Dockerfile .
 404
 405 The instructions for running the collectd-6 container are the same as for the
 406 collectd-experimental container.
 407
 408 There are a few useful build args that can be used to further customise the
 409 collectd-6 build:
 410
 411 * **COLLECTD_CONFIG_CMD_ARGS**
 412   For testing with new plugins for collectd-6, as un-ported plugins are
 413   disabled by default.
 414   This new option lets the ./configure command be run with extra args,
 415   e.g. --enable-cpu --enable-<my-newly-ported-plugin>, which means that
 416   plugin can be enabled for the PR that is being tested.
 417
 418 * **COLLECTD_TAG**
 419   This overrides the default tag selected by the flavors, and allows checking
 420   out out an arbitrary branch (e.g. PR branch instead of using the
 421   ``COLLECTD_PULL_REQUESTS`` arg, which rebases each PR on top of the
 422   nominal branch.
 423   To check out a PR, use the following args with the docker build command:
 424   ``--build-arg COLLECTD_TAG=pull/<PR_ID>/head``
 425
 426 Run the collectd stable docker image
 427 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 428 .. code:: bash
 429
 430    $ cd <BAROMETER_REPO_DIR>
 431    $ sudo docker run -ti --net=host -v \
 432    `pwd`/src/collectd/collectd_sample_configs:/opt/collectd/etc/collectd.conf.d \
 433    -v /var/run:/var/run -v /tmp:/tmp -v /sys/fs/resctrl:/sys/fs/resctrl \
 434    --privileged opnfv/barometer-collectd
 435
 436 .. note::
 437    The docker collectd image contains configuration for all the collectd
 438    plugins. In the command above we are overriding
 439    /opt/collectd/etc/collectd.conf.d by mounting a host directory
 440    src/collectd/collectd_sample_configs that contains only the sample
 441    configurations we are interested in running.
 442
 443    *If some dependencies for plugins listed in configuration directory
 444    aren't met, then collectd startup may fail(collectd tries to
 445    initialize plugins configurations for all given config files that can
 446    be found in shared configs directory and may fail if some dependency
 447    is missing).*
 448
 449    If `DPDK` or `RDT` can't be installed on host, then corresponding config
 450    files should be removed from shared configuration directory
 451    (`<BAROMETER_REPO_DIR>/src/collectd/collectd_sample_configs/`) prior
 452    to starting barometer-collectd container. By example: in case of missing
 453    `DPDK` functionality on the host, `dpdkstat.conf` and `dpdkevents.conf`
 454    should be removed.
 455
 456    Sample configurations can be found at:
 457    https://github.com/opnfv/barometer/tree/master/src/collectd/collectd_sample_configs
 458
 459    List of barometer-collectd dependencies on host for various plugins
 460    can be found at:
 461    https://wiki.anuket.io/display/HOME/Barometer-collectd+host+dependencies
 462
 463    The Resource Control file system (/sys/fs/resctrl) can be bound from host to
 464    container only if this directory exists on the host system. Otherwise omit
 465    the '-v /sys/fs/resctrl:/sys/fs/resctrl' part in docker run command.
 466    More information about resctrl can be found at:
 467    https://github.com/intel/intel-cmt-cat/wiki/resctrl
 468
 469 Check your docker image is running
 470
 471 .. code:: bash
 472
 473    sudo docker ps
 474
 475 To make some changes when the container is running run:
 476
 477 .. code:: bash
 478
 479    sudo docker exec -ti <CONTAINER ID> /bin/bash
 480
 481 Run the barometer-collectd-latest docker image
 482 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 483 Run command for ``barometer-collectd-latest`` container is very similar to
 484 command used for stable container - the only differences are name of the image
 485 and location of the sample configuration files (as different version of
 486 collectd plugins requiring different configuration files)
 487
 488
 489 .. code:: bash
 490
 491    $ cd <BAROMETER_REPO_DIR>
 492    $ sudo docker run -ti --net=host -v \
 493    `pwd`/src/collectd/collectd_sample_configs-latest:/opt/collectd/etc/collectd.conf.d \
 494    -v /var/run:/var/run -v /tmp:/tmp -v /sys/fs/resctrl:/sys/fs/resctrl \
 495    --privileged opnfv/barometer-collectd-latest
 496
 497 .. note::
 498    Barometer collectd docker images are sharing some directories with host
 499    (e.g. /tmp) therefore only one of collectd barometer flavors can be run
 500    at a time. In other words, if you want to try `barometer-collectd-latest` or
 501    `barometer-collectd-experimental` image, please stop instance of
 502    `barometer-collectd(stable)` image first.
 503
 504    The Resource Control file system (/sys/fs/resctrl) can be bound from host to
 505    container only if this directory exists on the host system. Otherwise omit
 506    the '-v /sys/fs/resctrl:/sys/fs/resctrl' part in docker run command.
 507    More information about resctrl can be found at:
 508    https://github.com/intel/intel-cmt-cat/wiki/resctrl
 509
 510 Run the barometer-collectd-experimental docker image
 511 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 512 Barometer-collectd-experimental container shares default configuration files
 513 with 'barometer-collectd-latest' equivalent but some of experimental pull
 514 requests may require modified configuration. Additional configuration files that
 515 are required specifically by experimental container can be found in
 516 `docker/barometer-collectd-experimental/experimental-configs/`
 517 directory. Content of this directory (all \*.conf files) should be copied to
 518 ``src/collectd/collectd_sample_configs-latest`` directory before first run of
 519 experimental container.
 520
 521 .. code:: bash
 522
 523    $ cd <BAROMETER_REPO_DIR>
 524    $ cp docker/barometer-collectd-experimental/experimental-configs/*.conf \
 525      src/collectd/collectd_sample_configs-latest
 526
 527 When configuration files are up to date for experimental container, it can be
 528 launched using following command (almost identical to run-command for ``latest``
 529 collectd container)
 530
 531 .. code:: bash
 532
 533    $ cd <BAROMETER_REPO_DIR>
 534    $ sudo docker run -ti --net=host -v \
 535    `pwd`/src/collectd/collectd_sample_configs-latest:/opt/collectd/etc/collectd.conf.d \
 536    -v /var/run:/var/run -v /tmp:/tmp -v /sys/fs/resctrl:/sys/fs/resctrl --privileged \
 537    opnfv/barometer-collectd-experimental
 538
 539 .. note::
 540    The Resource Control file system (/sys/fs/resctrl) can be bound from host to
 541    container only if this directory exists on the host system. Otherwise omit
 542    the '-v /sys/fs/resctrl:/sys/fs/resctrl' part in docker run command.
 543    More information about resctrl can be found at:
 544    https://github.com/intel/intel-cmt-cat/wiki/resctrl
 545
 546
 547 Build and Run InfluxDB and Grafana docker images
 548 ------------------------------------------------
 549
 550 Overview
 551 ^^^^^^^^
 552 The barometer-influxdb image is based on the influxdb:1.3.7 image from the influxdb dockerhub. To
 553 view detils on the base image please visit
 554 `https://hub.docker.com/_/influxdb/  <https://hub.docker.com/_/influxdb/>`_ Page includes details of
 555 exposed ports and configurable enviromental variables of the base image.
 556
 557 The barometer-grafana image is based on grafana:4.6.3 image from the grafana dockerhub. To view
 558 details on the base image please visit
 559 `https://hub.docker.com/r/grafana/grafana/ <https://hub.docker.com/r/grafana/grafana/>`_ Page
 560 includes details on exposed ports and configurable enviromental variables of the base image.
 561
 562 The barometer-grafana image includes pre-configured source and dashboards to display statistics exposed
 563 by the barometer-collectd image. The default datasource is an influxdb database running on localhost
 564 but the address of the influxdb server can be modified when launching the image by setting the
 565 environmental variables influxdb_host to IP or hostname of host on which influxdb server is running.
 566
 567 Additional dashboards can be added to barometer-grafana by mapping a volume to /opt/grafana/dashboards.
 568 Incase where a folder is mounted to this volume only files included in this folder will be visible
 569 inside barometer-grafana. To ensure all default files are also loaded please ensure they are included in
 570 volume folder been mounted. Appropriate example are given in section `Run the Grafana docker image`_
 571
 572 Download the InfluxDB and Grafana docker images
 573 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 574 If you wish to use pre-built barometer project's influxdb and grafana images, you can pull the
 575 images from https://hub.docker.com/r/opnfv/barometer-influxdb/ and https://hub.docker.com/r/opnfv/barometer-grafana/
 576
 577 .. note::
 578    If your preference is to build images locally please see sections `Build InfluxDB Docker Image`_ and
 579    `Build Grafana Docker Image`_
 580
 581 .. code:: bash
 582
 583     $ docker pull opnfv/barometer-influxdb
 584     $ docker pull opnfv/barometer-grafana
 585
 586 .. note::
 587    If you have pulled the pre-built barometer-influxdb and barometer-grafana images there is no
 588    requirement to complete steps outlined in  sections `Build InfluxDB Docker Image`_ and
 589    `Build Grafana Docker Image`_ and you can proceed directly to section
 590    `Run the Influxdb and Grafana Images`_
 591
 592 Build InfluxDB docker image
 593 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 594
 595 Build influxdb image from Dockerfile
 596
 597 .. code:: bash
 598
 599   $ cd barometer/docker/barometer-influxdb
 600   $ sudo docker build -t opnfv/barometer-influxdb --build-arg http_proxy=`echo $http_proxy` \
 601     --build-arg https_proxy=`echo $https_proxy` --network=host -f Dockerfile .
 602
 603 .. note::
 604    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs to
 605    be passed only if system is behind an HTTP or HTTPS proxy server.
 606
 607 Check the docker images:
 608
 609 .. code:: bash
 610
 611    $ sudo docker images
 612
 613 Output should contain an influxdb image:
 614
 615 .. code::
 616
 617    REPOSITORY                   TAG                 IMAGE ID            CREATED            SIZE
 618    opnfv/barometer-influxdb     latest              1e4623a59fe5        3 days ago         191MB
 619
 620 Build Grafana docker image
 621 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 622
 623 Build Grafana image from Dockerfile
 624
 625 .. code:: bash
 626
 627   $ cd barometer/docker/barometer-grafana
 628   $ sudo docker build -t opnfv/barometer-grafana --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-grafana      latest              05f2a3edd96b        3 hours ago         1.2GB
 647
 648 Run the Influxdb and Grafana Images
 649 -----------------------------------
 650
 651 Run the InfluxDB docker image
 652 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 653 .. code:: bash
 654
 655    $ sudo docker run -tid -v /var/lib/influxdb:/var/lib/influxdb --net=host\
 656     --name bar-influxdb opnfv/barometer-influxdb
 657
 658 Check your docker image is running
 659
 660 .. code:: bash
 661
 662    sudo docker ps
 663
 664 To make some changes when the container is running run:
 665
 666 .. code:: bash
 667
 668    sudo docker exec -ti <CONTAINER ID> /bin/bash
 669
 670 When both collectd and InfluxDB containers are located
 671 on the same host, then no additional configuration have to be added and you
 672 can proceed directly to `Run the Grafana docker image`_ section.
 673
 674 Modify collectd to support InfluxDB on another host
 675 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 676 If InfluxDB and collectd containers are located on separate hosts, then
 677 additional configuration have to be done in ``collectd`` container - it
 678 normally sends data using network plugin to 'localhost/127.0.0.1' therefore
 679 changing output location is required:
 680
 681 1. Stop and remove running bar-collectd container (if it is running)
 682
 683    .. code:: bash
 684
 685       $ sudo docker ps #to get collectd container name
 686       $ sudo docker rm -f <COLLECTD_CONTAINER_NAME>
 687
 688 2. Go to location where shared collectd config files are stored
 689
 690    .. code:: bash
 691
 692       $ cd <BAROMETER_REPO_DIR>
 693       $ cd src/collectd/collectd_sample_configs
 694
 695 3. Edit content of ``network.conf`` file.
 696    By default this file looks like that:
 697
 698    .. code::
 699
 700       LoadPlugin  network
 701       <Plugin network>
 702       Server "127.0.0.1" "25826"
 703       </Plugin>
 704
 705    ``127.0.0.1`` string has to be replaced with the IP address of host where
 706    InfluxDB container is running (e.g. ``192.168.121.111``). Edit this using your
 707    favorite text editor.
 708
 709 4. Start again collectd container like it is described in
 710    `Run the collectd stable docker image`_ chapter
 711
 712    .. code:: bash
 713
 714       $ cd <BAROMETER_REPO_DIR>
 715       $ sudo docker run -ti --name bar-collectd --net=host -v \
 716       `pwd`/src/collectd/collectd_sample_configs:/opt/collectd/etc/collectd.conf.d \
 717       -v /var/run:/var/run -v /tmp:/tmp --privileged opnfv/barometer-collectd
 718
 719 Now collectd container will be sending data to InfluxDB container located on
 720 remote Host pointed by IP configured in step 3.
 721
 722 Run the Grafana docker image
 723 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 724
 725 Connecting to an influxdb instance running on local system and adding own custom dashboards
 726
 727 .. code:: bash
 728
 729    $ cd <BAROMETER_REPO_DIR>
 730    $ sudo docker run -tid -v /var/lib/grafana:/var/lib/grafana \
 731      -v ${PWD}/docker/barometer-grafana/dashboards:/opt/grafana/dashboards \
 732      --name bar-grafana --net=host opnfv/barometer-grafana
 733
 734 Connecting to an influxdb instance running on remote system with hostname of someserver and IP address
 735 of 192.168.121.111
 736
 737 .. code:: bash
 738
 739    $ sudo docker run -tid -v /var/lib/grafana:/var/lib/grafana --net=host -e \
 740      influxdb_host=someserver --add-host someserver:192.168.121.111 --name \
 741      bar-grafana opnfv/barometer-grafana
 742
 743 Check your docker image is running
 744
 745 .. code:: bash
 746
 747    sudo docker ps
 748
 749 To make some changes when the container is running run:
 750
 751 .. code:: bash
 752
 753    sudo docker exec -ti <CONTAINER ID> /bin/bash
 754
 755 Connect to <host_ip>:3000 with a browser and log into grafana: admin/admin
 756
 757 Cleanup of influxdb/grafana configuration
 758 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 759
 760 When user wants to remove current grafana and influxdb configuration,
 761 folowing actions have to be performed
 762
 763 1. Stop and remove running influxdb and grafana containers
 764
 765 .. code:: bash
 766
 767    sudo docker rm -f bar-grafana bar-influxdb
 768
 769 2. Remove shared influxdb and grafana folders from the Host
 770
 771 .. code:: bash
 772
 773    sudo rm -rf /var/lib/grafana
 774    sudo rm -rf /var/lib/influxdb
 775
 776 .. note::
 777    Shared folders are storing configuration of grafana and influxdb
 778    containers. In case of changing influxdb or grafana configuration
 779    (e.g. moving influxdb to another host) it is good to perform cleanup
 780    on shared folders to not affect new setup with an old configuration.
 781
 782 Build and Run VES and Kafka Docker Images
 783 -----------------------------------------
 784
 785 Download VES and Kafka docker images
 786 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 787
 788 If you wish to use pre-built barometer project's VES and kafka images, you can pull the
 789 images from https://hub.docker.com/r/opnfv/barometer-ves/ and  https://hub.docker.com/r/opnfv/barometer-kafka/
 790
 791 .. note::
 792    If your preference is to build images locally please see sections `Build Kafka Docker Image`_ and
 793    `Build VES Docker Image`_
 794
 795 .. code:: bash
 796
 797     $ docker pull opnfv/barometer-kafka
 798     $ docker pull opnfv/barometer-ves
 799
 800 .. note::
 801    If you have pulled the pre-built images there is no requirement to complete steps outlined
 802    in sections `Build Kafka Docker Image`_ and `Build VES Docker Image`_ and you can proceed directly to section
 803    `Run Kafka Docker Image`_
 804
 805 Build Kafka docker image
 806 ^^^^^^^^^^^^^^^^^^^^^^^^
 807
 808 Build Kafka docker image:
 809
 810 .. code:: bash
 811
 812     $ cd barometer/docker/barometer-kafka
 813     $ sudo docker build -t opnfv/barometer-kafka --build-arg http_proxy=`echo $http_proxy` \
 814       --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
 815
 816 .. note::
 817    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs
 818    to be passed only if system is behind an HTTP or HTTPS proxy server.
 819
 820 Check the docker images:
 821
 822 .. code:: bash
 823
 824    $ sudo docker images
 825
 826 Output should contain a barometer image:
 827
 828 .. code::
 829
 830    REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
 831    opnfv/barometer-kafka     latest              05f2a3edd96b        3 hours ago         1.2GB
 832
 833 Build VES docker image
 834 ^^^^^^^^^^^^^^^^^^^^^^
 835
 836 Build VES application docker image:
 837
 838 .. code:: bash
 839
 840     $ cd barometer/docker/barometer-ves
 841     $ sudo docker build -t opnfv/barometer-ves --build-arg http_proxy=`echo $http_proxy` \
 842       --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
 843
 844 .. note::
 845    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs
 846    to be passed only if system is behind an HTTP or HTTPS proxy server.
 847
 848 Check the docker images:
 849
 850 .. code:: bash
 851
 852    $ sudo docker images
 853
 854 Output should contain a barometer image:
 855
 856 .. code::
 857
 858    REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
 859    opnfv/barometer-ves       latest              05f2a3edd96b        3 hours ago         1.2GB
 860
 861 Run Kafka docker image
 862 ^^^^^^^^^^^^^^^^^^^^^^
 863
 864 .. note::
 865    Before running Kafka an instance of Zookeeper must be running for the Kafka broker to register
 866    with. Zookeeper can be running locally or on a remote platform. Kafka's broker_id and address of
 867    its zookeeper instance can be configured by setting values for environmental variables 'broker_id'
 868    and 'zookeeper_node'. In instance where 'broker_id' and/or 'zookeeper_node' is not set the default
 869    setting of broker_id=0 and zookeeper_node=localhost is used. In intance where Zookeeper is running
 870    on same node as Kafka and there is a one to one relationship between Zookeeper and Kafka, default
 871    setting can be used. The docker argument `add-host` adds hostname and IP address to
 872    /etc/hosts file in container
 873
 874 Run zookeeper docker image:
 875
 876 .. code:: bash
 877
 878    $ sudo docker run -tid --net=host -p 2181:2181 zookeeper:3.4.11
 879
 880 Run kafka docker image which connects with a zookeeper instance running on same node with a 1:1 relationship
 881
 882 .. code:: bash
 883
 884    $ sudo docker run -tid --net=host -p 9092:9092 opnfv/barometer-kafka
 885
 886
 887 Run kafka docker image which connects with a zookeeper instance running on a node with IP address of
 888 192.168.121.111 using broker ID of 1
 889
 890 .. code:: bash
 891
 892    $ sudo docker run -tid --net=host -p 9092:9092 --env broker_id=1 --env zookeeper_node=zookeeper --add-host \
 893      zookeeper:192.168.121.111 opnfv/barometer-kafka
 894
 895 Run VES Application docker image
 896 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 897 .. note::
 898    VES application uses configuration file ves_app_config.conf from directory
 899    barometer/3rd_party/collectd-ves-app/ves_app/config/ and host.yaml file from
 900    barometer/3rd_party/collectd-ves-app/ves_app/yaml/ by default. If you wish to use a custom config
 901    file it should be mounted to mount point /opt/ves/config/ves_app_config.conf. To use an alternative yaml
 902    file from folder barometer/3rd_party/collectd-ves-app/ves_app/yaml the name of the yaml file to use
 903    should be passed as an additional command. If you wish to use a custom file the file should be
 904    mounted to mount point /opt/ves/yaml/ Please see examples below
 905
 906 Run VES docker image with default configuration
 907
 908 .. code:: bash
 909
 910    $ sudo docker run -tid --net=host opnfv/barometer-ves
 911
 912 Run VES docker image with guest.yaml files from barometer/3rd_party/collectd-ves-app/ves_app/yaml/
 913
 914 .. code:: bash
 915
 916    $ sudo docker run -tid --net=host opnfv/barometer-ves guest.yaml
 917
 918
 919 Run VES docker image with using custom config and yaml files. In example below yaml/ folder cotains
 920 file named custom.yaml
 921
 922 .. code:: bash
 923
 924    $ sudo docker run -tid --net=host -v ${PWD}/custom.config:/opt/ves/config/ves_app_config.conf \
 925      -v ${PWD}/yaml/:/opt/ves/yaml/ opnfv/barometer-ves custom.yaml
 926
 927 Run VES Test Collector application
 928 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 929
 930 VES Test Collector application can be used for displaying platform
 931 wide metrics that are collected by barometer-ves container.
 932 Setup instructions are located in: :ref:`Setup VES Test Collector`
 933
 934 Build and Run DMA and Redis Docker Images
 935 -----------------------------------------
 936
 937 Download DMA docker images
 938 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 939
 940 If you wish to use pre-built barometer project's DMA images, you can pull the
 941 images from https://hub.docker.com/r/opnfv/barometer-dma/
 942
 943 .. note::
 944    If your preference is to build images locally please see sections `Build DMA Docker Image`_
 945
 946 .. code:: bash
 947
 948     $ docker pull opnfv/barometer-dma
 949
 950 .. note::
 951    If you have pulled the pre-built images there is no requirement to complete steps outlined
 952    in sections `Build DMA Docker Image`_ and you can proceed directly to section
 953    `Run DMA Docker Image`_
 954
 955 Build DMA docker image
 956 ^^^^^^^^^^^^^^^^^^^^^^
 957
 958 Build DMA docker image:
 959
 960 .. code:: bash
 961
 962     $ cd barometer/docker/barometer-dma
 963     $ sudo docker build -t opnfv/barometer-dma --build-arg http_proxy=`echo $http_proxy` \
 964       --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
 965
 966 .. note::
 967    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs
 968    to be passed only if system is behind an HTTP or HTTPS proxy server.
 969
 970 Check the docker images:
 971
 972 .. code:: bash
 973
 974    $ sudo docker images
 975
 976 Output should contain a barometer image:
 977
 978 .. code::
 979
 980    REPOSITORY                   TAG                 IMAGE ID            CREATED             SIZE
 981    opnfv/barometer-dma          latest              2f14fbdbd498        3 hours ago         941 MB
 982
 983 Run Redis docker image
 984 ^^^^^^^^^^^^^^^^^^^^^^
 985
 986 .. note::
 987    Before running DMA, Redis must be running.
 988
 989 Run Redis docker image:
 990
 991 .. code:: bash
 992
 993    $ sudo docker run -tid -p 6379:6379 --name barometer-redis redis
 994
 995 Check your docker image is running
 996
 997 .. code:: bash
 998
 999    sudo docker ps
1000
1001 Run DMA docker image
1002 ^^^^^^^^^^^^^^^^^^^^
1003 .. note::
1004
1005   Run DMA docker image with default configuration
1006
1007 .. code:: bash
1008
1009    $ cd barometer/docker/barometer-dma
1010    $ sudo mkdir /etc/barometer-dma
1011    $ sudo cp ../../src/dma/examples/config.toml /etc/barometer-dma/
1012    $ sudo vi /etc/barometer-dma/config.toml
1013    (edit amqp_password and os_password:OpenStack admin password)
1014
1015    $ sudo su -
1016    (When there is no key for SSH access authentication)
1017    # ssh-keygen
1018    (Press Enter until done)
1019    (Backup if necessary)
1020    # cp ~/.ssh/authorized_keys ~/.ssh/authorized_keys_org
1021    # cat ~/.ssh/authorized_keys_org ~/.ssh/id_rsa.pub \
1022      > ~/.ssh/authorized_keys
1023    # exit
1024
1025    $ sudo docker run -tid --net=host --name server \
1026      -v /etc/barometer-dma:/etc/barometer-dma \
1027      -v /root/.ssh/id_rsa:/root/.ssh/id_rsa \
1028      -v /etc/collectd/collectd.conf.d:/etc/collectd/collectd.conf.d \
1029      opnfv/barometer-dma /server
1030
1031    $ sudo docker run -tid --net=host --name infofetch \
1032      -v /etc/barometer-dma:/etc/barometer-dma \
1033      -v /var/run/libvirt:/var/run/libvirt \
1034      opnfv/barometer-dma /infofetch
1035
1036    (Execute when installing the threshold evaluation binary)
1037    $ sudo docker cp infofetch:/threshold ./
1038    $ sudo ln -s ${PWD}/threshold /usr/local/bin/
1039
1040 References
1041 ^^^^^^^^^^
1042 .. [1] https://docs.docker.com/config/daemon/systemd/#httphttps-proxy
1043 .. [2] https://docs.docker.com/engine/install/centos/#install-using-the-repository
1044 .. [3] https://docs.docker.com/engine/userguide/
1045
1046