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 7 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    Unable to find image 'hello-world:latest' locally
 238    latest: Pulling from library/hello-world
 239    5b0f327be733: Pull complete
 240    Digest: sha256:07d5f7800dfe37b8c2196c7b1c524c33808ce2e0f74e7aa00e603295ca9a0972
 241    Status: Downloaded newer image for hello-world:latest
 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
 256 .. code:: bash
 257
 258     $ docker run -it ubuntu bash
 259
 260 Build and Run Collectd Docker Image
 261 -----------------------------------
 262
 263 Collectd-barometer flavors
 264 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 265
 266 Before starting to build and run the Collectd container, understand the available
 267 flavors of Collectd containers:
 268   * barometer-collectd - stable release, based on collectd 5.8
 269   * barometer-collectd-master - release based on collectd 'master' branch
 270   * barometer-collectd-experimental - release based on collectd 'master'
 271     branch that also includes set of experimental(not yet merged into upstream)
 272     pull requests
 273
 274 .. note::
 275    Experimental container is not tested across various OS'es and the stability
 276    of the container can change. Usage of experimental flavor is at users risk.
 277
 278 Stable barometer-collectd container is intended for work in production
 279 environment as it is based on latest collectd official release.
 280 `Barometer-collectd-master` and `barometer-collectd-experimental` containers
 281 can be used in order to try new collectd features.
 282 All flavors are located in `barometer` git repository - respective dockerfiles
 283 are stored in subdirectories of 'docker/' directory
 284
 285
 286 .. code:: bash
 287
 288     $ git clone https://gerrit.opnfv.org/gerrit/barometer
 289     $ ls barometer/docker|grep collectd
 290     barometer-collectd
 291     barometer-collectd-master
 292     barometer-collectd-experimental
 293
 294 .. note::
 295    Main directory of barometer source code (directory that contains 'docker',
 296    'docs', 'src' and systems sub-directories) will be referred as
 297    ``<BAROMETER_REPO_DIR>``
 298
 299 Download the collectd docker image
 300 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 301 If you wish to use a pre-built barometer image, you can pull the barometer
 302 image from https://hub.docker.com/r/opnfv/barometer-collectd/
 303
 304 .. code:: bash
 305
 306     $ docker pull opnfv/barometer-collectd
 307
 308 Build stable collectd container
 309 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 310
 311 .. code:: bash
 312
 313     $ cd <BAROMETER_REPO_DIR>/docker/barometer-collectd
 314     $ sudo docker build -t opnfv/barometer-collectd --build-arg http_proxy=`echo $http_proxy` \
 315       --build-arg https_proxy=`echo $https_proxy` --network=host -f Dockerfile .
 316
 317 .. note::
 318    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs to be
 319    passed only if system is behind an HTTP or HTTPS proxy server.
 320
 321 Check the docker images:
 322
 323 .. code:: bash
 324
 325    $ sudo docker images
 326
 327 Output should contain a barometer-collectd image:
 328
 329 .. code::
 330
 331    REPOSITORY                   TAG                 IMAGE ID            CREATED             SIZE
 332    opnfv/barometer-collectd     latest              05f2a3edd96b        3 hours ago         1.2GB
 333    centos                       7                   196e0ce0c9fb        4 weeks ago         197MB
 334    centos                       latest              196e0ce0c9fb        4 weeks ago         197MB
 335    hello-world                  latest              05a3bd381fc2        4 weeks ago         1.84kB
 336
 337 .. note::
 338    If you do not plan to use collectd-master and collectd-experimental barometer
 339    containers, then you can proceed directly to section `Run the collectd stable docker image`_
 340
 341
 342 Build collectd-master container
 343 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 344
 345 .. code:: bash
 346
 347     $ cd <BAROMETER_REPO_DIR>
 348     $ sudo docker build -t opnfv/barometer-collectd-master \
 349      --build-arg http_proxy=`echo $http_proxy` \
 350      --build-arg https_proxy=`echo $https_proxy` --network=host -f \
 351      docker/barometer-collectd-master/Dockerfile .
 352
 353 .. note::
 354    For `barometer-collectd-master` and `barometer-collectd-experimental` containers
 355    proxy parameters should be passed only if system is behind an HTTP or HTTPS
 356    proxy server (same as for stable collectd container)
 357
 358 Build collectd-experimental container
 359 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 360
 361 .. code:: bash
 362
 363     $ cd <BAROMETER_REPO_DIR>
 364     $ sudo docker build -t opnfv/barometer-collectd-experimental \
 365      --build-arg http_proxy=`echo $http_proxy` \
 366      --build-arg https_proxy=`echo $https_proxy` \
 367      --network=host -f docker/barometer-collectd-experimental/Dockerfile .
 368
 369 .. note::
 370    For `barometer-collectd-master` and `barometer-collectd-experimental` containers
 371    proxy parameters should be passed only if system is behind an HTTP or HTTPS
 372    proxy server (same as for stable collectd container)
 373
 374 Run the collectd stable docker image
 375 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 376 .. code:: bash
 377
 378    $ cd <BAROMETER_REPO_DIR>
 379    $ sudo docker run -ti --net=host -v \
 380    `pwd`/src/collectd/collectd_sample_configs:/opt/collectd/etc/collectd.conf.d \
 381    -v /var/run:/var/run -v /tmp:/tmp -v /sys/fs/resctrl:/sys/fs/resctrl \
 382    --privileged opnfv/barometer-collectd
 383
 384 .. note::
 385    The docker collectd image contains configuration for all the collectd
 386    plugins. In the command above we are overriding
 387    /opt/collectd/etc/collectd.conf.d by mounting a host directory
 388    src/collectd/collectd_sample_configs that contains only the sample
 389    configurations we are interested in running.
 390
 391    *If some dependencies for plugins listed in configuration directory
 392    aren't met, then collectd startup may fail(collectd tries to
 393    initialize plugins configurations for all given config files that can
 394    be found in shared configs directory and may fail if some dependency
 395    is missing).*
 396
 397    If `DPDK` or `RDT` can't be installed on host, then corresponding config
 398    files should be removed from shared configuration directory
 399    (`<BAROMETER_REPO_DIR>/src/collectd/collectd_sample_configs/`) prior
 400    to starting barometer-collectd container. By example: in case of missing
 401    `DPDK` functionality on the host, `dpdkstat.conf` and `dpdkevents.conf`
 402    should be removed.
 403
 404    Sample configurations can be found at:
 405    https://github.com/opnfv/barometer/tree/master/src/collectd/collectd_sample_configs
 406
 407    List of barometer-collectd dependencies on host for various plugins
 408    can be found at:
 409    https://wiki.opnfv.org/display/fastpath/Barometer-collectd+host+dependencies
 410
 411    The Resource Control file system (/sys/fs/resctrl) can be bound from host to
 412    container only if this directory exists on the host system. Otherwise omit
 413    the '-v /sys/fs/resctrl:/sys/fs/resctrl' part in docker run command.
 414    More information about resctrl can be found at:
 415    https://github.com/intel/intel-cmt-cat/wiki/resctrl
 416
 417 Check your docker image is running
 418
 419 .. code:: bash
 420
 421    sudo docker ps
 422
 423 To make some changes when the container is running run:
 424
 425 .. code:: bash
 426
 427    sudo docker exec -ti <CONTAINER ID> /bin/bash
 428
 429 Run the barometer-collectd-master docker image
 430 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 431 Run command for `barometer-collectd-master` container is very similar to command
 432 used for stable container - the only differences are name of the image
 433 and location of the sample configuration files(as different version of collectd
 434 plugins requiring different configuration files)
 435
 436
 437 .. code:: bash
 438
 439    $ cd <BAROMETER_REPO_DIR>
 440    $ sudo docker run -ti --net=host -v \
 441    `pwd`/src/collectd/collectd_sample_configs-master:/opt/collectd/etc/collectd.conf.d \
 442    -v /var/run:/var/run -v /tmp:/tmp -v /sys/fs/resctrl:/sys/fs/resctrl \
 443    --privileged opnfv/barometer-collectd-master
 444
 445 .. note::
 446    Barometer collectd docker images are sharing some directories with host
 447    (e.g. /tmp) therefore only one of collectd barometer flavors can be run
 448    at a time. In other words, if you want to try `barometer-collectd-master` or
 449    `barometer-collectd-experimental` image, please stop instance of
 450    `barometer-collectd(stable)` image first.
 451
 452    The Resource Control file system (/sys/fs/resctrl) can be bound from host to
 453    container only if this directory exists on the host system. Otherwise omit
 454    the '-v /sys/fs/resctrl:/sys/fs/resctrl' part in docker run command.
 455    More information about resctrl can be found at:
 456    https://github.com/intel/intel-cmt-cat/wiki/resctrl
 457
 458 Run the barometer-collectd-experimental docker image
 459 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 460 Barometer-collectd-experimental container shares default configuration files
 461 with 'barometer-collectd-master' equivalent but some of experimental pull
 462 requests may require modified configuration. Additional configuration files that
 463 are required specifically by experimental container can be found in
 464 `docker/barometer-collectd-experimental/experimental-configs/`
 465 directory. Content of this directory (all \*.conf files) should be copied to
 466 `src/collectd/collectd_sample_configs-master` directory before first run of
 467 experimental container.
 468
 469 .. code:: bash
 470
 471    $ cd <BAROMETER_REPO_DIR>
 472    $ cp docker/barometer-collectd-experimental/experimental-configs/*.conf \
 473      src/collectd/collectd_sample_configs-master
 474
 475 When configuration files are up to date for experimental container, it can be
 476 launched using following command (almost identical to run-command for 'master'
 477 collectd container)
 478
 479 .. code:: bash
 480
 481    $ cd <BAROMETER_REPO_DIR>
 482    $ sudo docker run -ti --net=host -v \
 483    `pwd`/src/collectd/collectd_sample_configs-master:/opt/collectd/etc/collectd.conf.d \
 484    -v /var/run:/var/run -v /tmp:/tmp -v /sys/fs/resctrl:/sys/fs/resctrl --privileged \
 485    opnfv/barometer-collectd-experimental
 486
 487 .. note::
 488    The Resource Control file system (/sys/fs/resctrl) can be bound from host to
 489    container only if this directory exists on the host system. Otherwise omit
 490    the '-v /sys/fs/resctrl:/sys/fs/resctrl' part in docker run command.
 491    More information about resctrl can be found at:
 492    https://github.com/intel/intel-cmt-cat/wiki/resctrl
 493
 494
 495 Build and Run InfluxDB and Grafana docker images
 496 ------------------------------------------------
 497
 498 Overview
 499 ^^^^^^^^
 500 The barometer-influxdb image is based on the influxdb:1.3.7 image from the influxdb dockerhub. To
 501 view detils on the base image please visit
 502 `https://hub.docker.com/_/influxdb/  <https://hub.docker.com/_/influxdb/>`_ Page includes details of
 503 exposed ports and configurable enviromental variables of the base image.
 504
 505 The barometer-grafana image is based on grafana:4.6.3 image from the grafana dockerhub. To view
 506 details on the base image please visit
 507 `https://hub.docker.com/r/grafana/grafana/ <https://hub.docker.com/r/grafana/grafana/>`_ Page
 508 includes details on exposed ports and configurable enviromental variables of the base image.
 509
 510 The barometer-grafana image includes pre-configured source and dashboards to display statistics exposed
 511 by the barometer-collectd image. The default datasource is an influxdb database running on localhost
 512 but the address of the influxdb server can be modified when launching the image by setting the
 513 environmental variables influxdb_host to IP or hostname of host on which influxdb server is running.
 514
 515 Additional dashboards can be added to barometer-grafana by mapping a volume to /opt/grafana/dashboards.
 516 Incase where a folder is mounted to this volume only files included in this folder will be visible
 517 inside barometer-grafana. To ensure all default files are also loaded please ensure they are included in
 518 volume folder been mounted. Appropriate example are given in section `Run the Grafana docker image`_
 519
 520 Download the InfluxDB and Grafana docker images
 521 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 522 If you wish to use pre-built barometer project's influxdb and grafana images, you can pull the
 523 images from https://hub.docker.com/r/opnfv/barometer-influxdb/ and https://hub.docker.com/r/opnfv/barometer-grafana/
 524
 525 .. note::
 526    If your preference is to build images locally please see sections `Build InfluxDB Docker Image`_ and
 527    `Build Grafana Docker Image`_
 528
 529 .. code:: bash
 530
 531     $ docker pull opnfv/barometer-influxdb
 532     $ docker pull opnfv/barometer-grafana
 533
 534 .. note::
 535    If you have pulled the pre-built barometer-influxdb and barometer-grafana images there is no
 536    requirement to complete steps outlined in  sections `Build InfluxDB Docker Image`_ and
 537    `Build Grafana Docker Image`_ and you can proceed directly to section
 538    `Run the Influxdb and Grafana Images`_
 539
 540 Build InfluxDB docker image
 541 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 542
 543 Build influxdb image from Dockerfile
 544
 545 .. code:: bash
 546
 547   $ cd barometer/docker/barometer-influxdb
 548   $ sudo docker build -t opnfv/barometer-influxdb --build-arg http_proxy=`echo $http_proxy` \
 549     --build-arg https_proxy=`echo $https_proxy` --network=host -f Dockerfile .
 550
 551 .. note::
 552    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs to
 553    be passed only if system is behind an HTTP or HTTPS proxy server.
 554
 555 Check the docker images:
 556
 557 .. code:: bash
 558
 559    $ sudo docker images
 560
 561 Output should contain an influxdb image:
 562
 563 .. code::
 564
 565    REPOSITORY                   TAG                 IMAGE ID            CREATED            SIZE
 566    opnfv/barometer-influxdb     latest              1e4623a59fe5        3 days ago         191MB
 567
 568 Build Grafana docker image
 569 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 570
 571 Build Grafana image from Dockerfile
 572
 573 .. code:: bash
 574
 575   $ cd barometer/docker/barometer-grafana
 576   $ sudo docker build -t opnfv/barometer-grafana --build-arg http_proxy=`echo $http_proxy` \
 577     --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
 578
 579 .. note::
 580    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs to
 581    be passed only if system is behind an HTTP or HTTPS proxy server.
 582
 583 Check the docker images:
 584
 585 .. code:: bash
 586
 587    $ sudo docker images
 588
 589 Output should contain an influxdb image:
 590
 591 .. code::
 592
 593    REPOSITORY                   TAG                 IMAGE ID            CREATED             SIZE
 594    opnfv/barometer-grafana      latest              05f2a3edd96b        3 hours ago         1.2GB
 595
 596 Run the Influxdb and Grafana Images
 597 -----------------------------------
 598
 599 Run the InfluxDB docker image
 600 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 601 .. code:: bash
 602
 603    $ sudo docker run -tid -v /var/lib/influxdb:/var/lib/influxdb --net=host\
 604     --name bar-influxdb opnfv/barometer-influxdb
 605
 606 Check your docker image is running
 607
 608 .. code:: bash
 609
 610    sudo docker ps
 611
 612 To make some changes when the container is running run:
 613
 614 .. code:: bash
 615
 616    sudo docker exec -ti <CONTAINER ID> /bin/bash
 617
 618 When both collectd and InfluxDB containers are located
 619 on the same host, then no additional configuration have to be added and you
 620 can proceed directly to `Run the Grafana docker image`_ section.
 621
 622 Modify collectd to support InfluxDB on another host
 623 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 624 If InfluxDB and collectd containers are located on separate hosts, then
 625 additional configuration have to be done in ``collectd`` container - it
 626 normally sends data using network plugin to 'localhost/127.0.0.1' therefore
 627 changing output location is required:
 628
 629 1. Stop and remove running bar-collectd container (if it is running)
 630
 631    .. code:: bash
 632
 633       $ sudo docker ps #to get collectd container name
 634       $ sudo docker rm -f <COLLECTD_CONTAINER_NAME>
 635
 636 2. Go to location where shared collectd config files are stored
 637
 638    .. code:: bash
 639
 640       $ cd <BAROMETER_REPO_DIR>
 641       $ cd src/collectd/collectd_sample_configs
 642
 643 3. Edit content of ``network.conf`` file.
 644    By default this file looks like that:
 645
 646    .. code::
 647
 648       LoadPlugin  network
 649       <Plugin network>
 650       Server "127.0.0.1" "25826"
 651       </Plugin>
 652
 653    ``127.0.0.1`` string has to be replaced with the IP address of host where
 654    InfluxDB container is running (e.g. ``192.168.121.111``). Edit this using your
 655    favorite text editor.
 656
 657 4. Start again collectd container like it is described in
 658    `Run the collectd stable docker image`_ chapter
 659
 660    .. code:: bash
 661
 662       $ cd <BAROMETER_REPO_DIR>
 663       $ sudo docker run -ti --name bar-collectd --net=host -v \
 664       `pwd`/src/collectd/collectd_sample_configs:/opt/collectd/etc/collectd.conf.d \
 665       -v /var/run:/var/run -v /tmp:/tmp --privileged opnfv/barometer-collectd
 666
 667 Now collectd container will be sending data to InfluxDB container located on
 668 remote Host pointed by IP configured in step 3.
 669
 670 Run the Grafana docker image
 671 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 672
 673 Connecting to an influxdb instance running on local system and adding own custom dashboards
 674
 675 .. code:: bash
 676
 677    $ cd <BAROMETER_REPO_DIR>
 678    $ sudo docker run -tid -v /var/lib/grafana:/var/lib/grafana \
 679      -v ${PWD}/docker/barometer-grafana/dashboards:/opt/grafana/dashboards \
 680      --name bar-grafana --net=host opnfv/barometer-grafana
 681
 682 Connecting to an influxdb instance running on remote system with hostname of someserver and IP address
 683 of 192.168.121.111
 684
 685 .. code:: bash
 686
 687    $ sudo docker run -tid -v /var/lib/grafana:/var/lib/grafana --net=host -e \
 688      influxdb_host=someserver --add-host someserver:192.168.121.111 --name \
 689      bar-grafana opnfv/barometer-grafana
 690
 691 Check your docker image is running
 692
 693 .. code:: bash
 694
 695    sudo docker ps
 696
 697 To make some changes when the container is running run:
 698
 699 .. code:: bash
 700
 701    sudo docker exec -ti <CONTAINER ID> /bin/bash
 702
 703 Connect to <host_ip>:3000 with a browser and log into grafana: admin/admin
 704
 705 Cleanup of influxdb/grafana configuration
 706 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 707
 708 When user wants to remove current grafana and influxdb configuration,
 709 folowing actions have to be performed
 710
 711 1. Stop and remove running influxdb and grafana containers
 712
 713 .. code:: bash
 714
 715    sudo docker rm -f bar-grafana bar-influxdb
 716
 717 2. Remove shared influxdb and grafana folders from the Host
 718
 719 .. code:: bash
 720
 721    sudo rm -rf /var/lib/grafana
 722    sudo rm -rf /var/lib/influxdb
 723
 724 .. note::
 725    Shared folders are storing configuration of grafana and influxdb
 726    containers. In case of changing influxdb or grafana configuration
 727    (e.g. moving influxdb to another host) it is good to perform cleanup
 728    on shared folders to not affect new setup with an old configuration.
 729
 730 Build and Run VES and Kafka Docker Images
 731 -----------------------------------------
 732
 733 Download VES and Kafka docker images
 734 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 735
 736 If you wish to use pre-built barometer project's VES and kafka images, you can pull the
 737 images from https://hub.docker.com/r/opnfv/barometer-ves/ and  https://hub.docker.com/r/opnfv/barometer-kafka/
 738
 739 .. note::
 740    If your preference is to build images locally please see sections `Build the Kafka Image`_ and
 741    `Build VES Image`_
 742
 743 .. code:: bash
 744
 745     $ docker pull opnfv/barometer-kafka
 746     $ docker pull opnfv/barometer-ves
 747
 748 .. note::
 749    If you have pulled the pre-built images there is no requirement to complete steps outlined
 750    in sections `Build Kafka Docker Image`_ and `Build VES Docker Image`_ and you can proceed directly to section
 751    `Run Kafka Docker Image`_
 752
 753 Build Kafka docker image
 754 ^^^^^^^^^^^^^^^^^^^^^^^^
 755
 756 Build Kafka docker image:
 757
 758 .. code:: bash
 759
 760     $ cd barometer/docker/barometer-kafka
 761     $ sudo docker build -t opnfv/barometer-kafka --build-arg http_proxy=`echo $http_proxy` \
 762       --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
 763
 764 .. note::
 765    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs
 766    to be passed only if system is behind an HTTP or HTTPS proxy server.
 767
 768 Check the docker images:
 769
 770 .. code:: bash
 771
 772    $ sudo docker images
 773
 774 Output should contain a barometer image:
 775
 776 .. code::
 777
 778    REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
 779    opnfv/barometer-kafka     latest              05f2a3edd96b        3 hours ago         1.2GB
 780
 781 Build VES docker image
 782 ^^^^^^^^^^^^^^^^^^^^^^
 783
 784 Build VES application docker image:
 785
 786 .. code:: bash
 787
 788     $ cd barometer/docker/barometer-ves
 789     $ sudo docker build -t opnfv/barometer-ves --build-arg http_proxy=`echo $http_proxy` \
 790       --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
 791
 792 .. note::
 793    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs
 794    to be passed only if system is behind an HTTP or HTTPS proxy server.
 795
 796 Check the docker images:
 797
 798 .. code:: bash
 799
 800    $ sudo docker images
 801
 802 Output should contain a barometer image:
 803
 804 .. code::
 805
 806    REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
 807    opnfv/barometer-ves       latest              05f2a3edd96b        3 hours ago         1.2GB
 808
 809 Run Kafka docker image
 810 ^^^^^^^^^^^^^^^^^^^^^^
 811
 812 .. note::
 813    Before running Kafka an instance of Zookeeper must be running for the Kafka broker to register
 814    with. Zookeeper can be running locally or on a remote platform. Kafka's broker_id and address of
 815    its zookeeper instance can be configured by setting values for environmental variables 'broker_id'
 816    and 'zookeeper_node'. In instance where 'broker_id' and/or 'zookeeper_node' is not set the default
 817    setting of broker_id=0 and zookeeper_node=localhost is used. In intance where Zookeeper is running
 818    on same node as Kafka and there is a one to one relationship between Zookeeper and Kafka, default
 819    setting can be used. The docker argument `add-host` adds hostname and IP address to
 820    /etc/hosts file in container
 821
 822 Run zookeeper docker image:
 823
 824 .. code:: bash
 825
 826    $ sudo docker run -tid --net=host -p 2181:2181 zookeeper:3.4.11
 827
 828 Run kafka docker image which connects with a zookeeper instance running on same node with a 1:1 relationship
 829
 830 .. code:: bash
 831
 832    $ sudo docker run -tid --net=host -p 9092:9092 opnfv/barometer-kafka
 833
 834
 835 Run kafka docker image which connects with a zookeeper instance running on a node with IP address of
 836 192.168.121.111 using broker ID of 1
 837
 838 .. code:: bash
 839
 840    $ sudo docker run -tid --net=host -p 9092:9092 --env broker_id=1 --env zookeeper_node=zookeeper --add-host \
 841      zookeeper:192.168.121.111 opnfv/barometer-kafka
 842
 843 Run VES Application docker image
 844 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 845 .. note::
 846    VES application uses configuration file ves_app_config.conf from directory
 847    barometer/3rd_party/collectd-ves-app/ves_app/config/ and host.yaml file from
 848    barometer/3rd_party/collectd-ves-app/ves_app/yaml/ by default. If you wish to use a custom config
 849    file it should be mounted to mount point /opt/ves/config/ves_app_config.conf. To use an alternative yaml
 850    file from folder barometer/3rd_party/collectd-ves-app/ves_app/yaml the name of the yaml file to use
 851    should be passed as an additional command. If you wish to use a custom file the file should be
 852    mounted to mount point /opt/ves/yaml/ Please see examples below
 853
 854 Run VES docker image with default configuration
 855
 856 .. code:: bash
 857
 858    $ sudo docker run -tid --net=host opnfv/barometer-ves
 859
 860 Run VES docker image with guest.yaml files from barometer/3rd_party/collectd-ves-app/ves_app/yaml/
 861
 862 .. code:: bash
 863
 864    $ sudo docker run -tid --net=host opnfv/barometer-ves guest.yaml
 865
 866
 867 Run VES docker image with using custom config and yaml files. In example below yaml/ folder cotains
 868 file named custom.yaml
 869
 870 .. code:: bash
 871
 872    $ sudo docker run -tid --net=host -v ${PWD}/custom.config:/opt/ves/config/ves_app_config.conf \
 873      -v ${PWD}/yaml/:/opt/ves/yaml/ opnfv/barometer-ves custom.yaml
 874
 875 Run VES Test Collector application
 876 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 877
 878 VES Test Collector application can be used for displaying platform
 879 wide metrics that are collected by barometer-ves container.
 880 Setup instructions are located in: :ref:`Setup VES Test Collector`
 881
 882 Build and Run DMA and Redis Docker Images
 883 -----------------------------------------
 884
 885 Download DMA docker images
 886 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 887
 888 If you wish to use pre-built barometer project's DMA images, you can pull the
 889 images from https://hub.docker.com/r/opnfv/barometer-dma/
 890
 891 .. note::
 892    If your preference is to build images locally please see sections `Build DMA Docker Image`_
 893
 894 .. code:: bash
 895
 896     $ docker pull opnfv/barometer-dma
 897
 898 .. note::
 899    If you have pulled the pre-built images there is no requirement to complete steps outlined
 900    in sections `Build DMA Docker Image`_ and you can proceed directly to section
 901    `Run DMA Docker Image`_
 902
 903 Build DMA docker image
 904 ^^^^^^^^^^^^^^^^^^^^^^
 905
 906 Build DMA docker image:
 907
 908 .. code:: bash
 909
 910     $ cd barometer/docker/barometer-dma
 911     $ sudo docker build -t opnfv/barometer-dma --build-arg http_proxy=`echo $http_proxy` \
 912       --build-arg https_proxy=`echo $https_proxy` -f Dockerfile .
 913
 914 .. note::
 915    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs
 916    to be passed only if system is behind an HTTP or HTTPS proxy server.
 917
 918 Check the docker images:
 919
 920 .. code:: bash
 921
 922    $ sudo docker images
 923
 924 Output should contain a barometer image:
 925
 926 .. code::
 927
 928    REPOSITORY                   TAG                 IMAGE ID            CREATED             SIZE
 929    opnfv/barometer-dma          latest              2f14fbdbd498        3 hours ago         941 MB
 930
 931 Run Redis docker image
 932 ^^^^^^^^^^^^^^^^^^^^^^
 933
 934 .. note::
 935    Before running DMA, Redis must be running.
 936
 937 Run Redis docker image:
 938
 939 .. code:: bash
 940
 941    $ sudo docker run -tid -p 6379:6379 --name barometer-redis redis
 942
 943 Check your docker image is running
 944
 945 .. code:: bash
 946
 947    sudo docker ps
 948
 949 Run DMA docker image
 950 ^^^^^^^^^^^^^^^^^^^^
 951 .. note::
 952
 953 Run DMA docker image with default configuration
 954
 955 .. code:: bash
 956
 957    $ cd barometer/docker/barometer-dma
 958    $ sudo mkdir /etc/barometer-dma
 959    $ sudo cp ../../src/dma/examples/config.toml /etc/barometer-dma/
 960    $ sudo vi /etc/barometer-dma/config.toml
 961    (edit amqp_password and os_password:OpenStack admin password)
 962
 963    $ sudo su -
 964    (When there is no key for SSH access authentication)
 965    # ssh-keygen
 966    (Press Enter until done)
 967    (Backup if necessary)
 968    # cp ~/.ssh/authorized_keys ~/.ssh/authorized_keys_org
 969    # cat ~/.ssh/authorized_keys_org ~/.ssh/id_rsa.pub \
 970      > ~/.ssh/authorized_keys
 971    # exit
 972
 973    $ sudo docker run -tid --net=host --name server \
 974      -v /etc/barometer-dma:/etc/barometer-dma \
 975      -v /root/.ssh/id_rsa:/root/.ssh/id_rsa \
 976      -v /etc/collectd/collectd.conf.d:/etc/collectd/collectd.conf.d \
 977      opnfv/barometer-dma /server
 978
 979    $ sudo docker run -tid --net=host --name infofetch \
 980      -v /etc/barometer-dma:/etc/barometer-dma \
 981      -v /var/run/libvirt:/var/run/libvirt \
 982      opnfv/barometer-dma /infofetch
 983
 984    (Execute when installing the threshold evaluation binary)
 985    $ sudo docker cp infofetch:/threshold ./
 986    $ sudo ln -s ${PWD}/threshold /usr/local/bin/
 987
 988 References
 989 ^^^^^^^^^^
 990 .. [1] https://docs.docker.com/config/daemon/systemd/#httphttps-proxy
 991 .. [2] https://docs.docker.com/engine/install/centos/#install-using-the-repository
 992 .. [3] https://docs.docker.com/engine/userguide/
 993
 994