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