docs/release/userguide/docker.userguide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. (c) <optionally add copywriters name>
   4
   5 ===================================
   6 OPNFV Barometer Docker User Guide
   7 ===================================
   8
   9 .. contents::
  10    :depth: 3
  11    :local:
  12
  13 Barometer docker image description
  14 -----------------------------------
  15 .. Describe the specific features and how it is realised in the scenario in a brief manner
  16 .. to ensure the user understand the context for the user guide instructions to follow.
  17
  18 The intention of this user guide is to outline how to install and test the
  19 barometer docker image that can be built from the Dockerfile available in the
  20 barometer repository.
  21
  22 .. note::
  23    The Dockerfile is available in the docker/ directory in the barometer repo.
  24    The Dockerfile builds a CentOS 7 docker image.
  25
  26 The barometer docker image gives you a collectd installation that includes all
  27 the barometer plugins.
  28
  29 .. note::
  30    The container MUST be run as a privileged container.
  31
  32 Collectd is a daemon which collects system performance statistics periodically
  33 and provides a variety of mechanisms to publish the collected metrics. It
  34 supports more than 90 different input and output plugins. Input plugins
  35 retrieve metrics and publish them to the collectd deamon, while output plugins
  36 publish the data they receive to an end point. collectd also has infrastructure
  37 to support thresholding and notification.
  38
  39 Barometer docker image has enabled the following collectd plugins (in addition
  40 to the standard collectd plugins):
  41
  42 * hugepages plugin
  43 * Open vSwitch events Plugin
  44 * Open vSwitch stats Plugin
  45 * mcelog plugin
  46 * PMU plugin
  47 * RDT plugin
  48 * virt
  49 * SNMP Agent
  50
  51 Plugins and third party applications in Barometer repository that will be available in the
  52 docker image:
  53
  54 * Open vSwitch PMD stats
  55 * ONAP VES application
  56 * gnocchi plugin
  57 * aodh plugin
  58 * Legacy/IPMI
  59
  60
  61 Installing Docker
  62 -----------------
  63 .. Describe the specific capabilities and usage for <XYZ> feature.
  64 .. Provide enough information that a user will be able to operate the feature on a deployed scenario.
  65
  66 On Ubuntu
  67 ^^^^^^^^^^
  68 .. note::
  69  * sudo permissions are required to install docker.
  70  * These instructions are for Ubuntu 16.10
  71
  72 To install docker:
  73
  74 .. code:: bash
  75
  76     $ sudo apt-get install curl
  77     $ sudo curl -fsSL https://get.docker.com/ | sh
  78     $ sudo usermod -aG docker <username>
  79     $ sudo systemctl status docker
  80
  81 Replace <username> above with an appropriate user name.
  82
  83 On CentOS
  84 ^^^^^^^^^^
  85 .. note::
  86  * sudo permissions are required to install docker.
  87  * These instructions are for CentOS 7
  88
  89 To install docker:
  90
  91 .. code:: bash
  92
  93     $ sudo yum remove docker docker-common docker-selinux docker-engine
  94     $ sudo yum install -y yum-utils  device-mapper-persistent-data  lvm2
  95     $ sudo yum-config-manager   --add-repo    https://download.docker.com/linux/centos/docker-ce.repo
  96     $ sudo yum-config-manager --enable docker-ce-edge
  97     $ sudo yum-config-manager --enable docker-ce-test
  98     $ sudo yum install docker-ce
  99     $ sudo usermod -aG docker <username>
 100     $ sudo systemctl status docker
 101
 102 Replace <username> above with an appropriate user name.
 103
 104 .. note::
 105    If this is the first time you are installing a package from a recently added
 106    repository, you will be prompted to accept the GPG key, and the key’s
 107    fingerprint will be shown. Verify that the fingerprint is correct, and if so,
 108    accept the key. The fingerprint should match060A 61C5 1B55 8A7F 742B 77AA C52F
 109    EB6B 621E 9F35.
 110
 111         Retrieving key from https://download.docker.com/linux/centos/gpg
 112         Importing GPG key 0x621E9F35:
 113          Userid     : "Docker Release (CE rpm) <docker@docker.com>"
 114          Fingerprint: 060a 61c5 1b55 8a7f 742b 77aa c52f eb6b 621e 9f35
 115          From       : https://download.docker.com/linux/centos/gpg
 116         Is this ok [y/N]: y
 117
 118 Proxy Configuration:
 119 ^^^^^^^^^^^^^^^^^^^^
 120 .. note::
 121    This applies for both CentOS and Ubuntu.
 122
 123 If you are behind an HTTP or HTTPS proxy server, you will need to add this
 124 configuration in the Docker systemd service file.
 125
 126 1. Create a systemd drop-in directory for the docker service:
 127
 128 .. code:: bash
 129
 130    $ sudo mkdir -p /etc/systemd/system/docker.service.d
 131
 132 2. Create a file
 133 called /etc/systemd/system/docker.service.d/http-proxy.conf that adds
 134 the HTTP_PROXY environment variable:
 135
 136 .. code:: bash
 137
 138    [Service]
 139    Environment="HTTP_PROXY=http://proxy.example.com:80/"
 140
 141 Or, if you are behind an HTTPS proxy server, create a file
 142 called /etc/systemd/system/docker.service.d/https-proxy.conf that adds
 143 the HTTPS_PROXY environment variable:
 144
 145 .. code:: bash
 146
 147     [Service]
 148     Environment="HTTPS_PROXY=https://proxy.example.com:443/"
 149
 150 Or create a single file with all the proxy configurations:
 151 /etc/systemd/system/docker.service.d/proxy.conf
 152
 153 .. code:: bash
 154
 155     [Service]
 156     Environment="HTTP_PROXY=http://proxy.example.com:80/"
 157     Environment="HTTPS_PROXY=https://proxy.example.com:443/"
 158     Environment="FTP_PROXY=ftp://proxy.example.com:443/"
 159     Environment="NO_PROXY=localhost"
 160
 161 3. Flush changes:
 162
 163 .. code:: bash
 164
 165     $ sudo systemctl daemon-reload
 166
 167 4. Restart Docker:
 168
 169 .. code:: bash
 170
 171     $ sudo systemctl restart docker
 172
 173 5. Check docker environment variables:
 174
 175 .. code:: bash
 176
 177     sudo systemctl show --property=Environment docker
 178
 179 Test docker installation
 180 ^^^^^^^^^^^^^^^^^^^^^^^^
 181 .. note::
 182       This applies for both CentOS and Ubuntu.
 183
 184 .. code:: bash
 185
 186    $ sudo docker run hello-world
 187
 188 The output should be something like:
 189
 190 .. code:: bash
 191
 192    Unable to find image 'hello-world:latest' locally
 193    latest: Pulling from library/hello-world
 194    5b0f327be733: Pull complete
 195    Digest: sha256:07d5f7800dfe37b8c2196c7b1c524c33808ce2e0f74e7aa00e603295ca9a0972
 196    Status: Downloaded newer image for hello-world:latest
 197
 198    Hello from Docker!
 199    This message shows that your installation appears to be working correctly.
 200
 201    To generate this message, Docker took the following steps:
 202     1. The Docker client contacted the Docker daemon.
 203     2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
 204     3. The Docker daemon created a new container from that image which runs the
 205        executable that produces the output you are currently reading.
 206     4. The Docker daemon streamed that output to the Docker client, which sent it
 207        to your terminal.
 208
 209 To try something more ambitious, you can run an Ubuntu container with:
 210
 211 .. code:: bash
 212
 213     $ docker run -it ubuntu bash
 214
 215 Build the barometer docker image
 216 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 217
 218 .. code:: bash
 219
 220     $ cd barometer
 221     $ sudo docker build -t barometer_image --build-arg http_proxy=`echo $http_proxy` \
 222       --build-arg https_proxy=`echo $https_proxy` -f docker/Dockerfile .
 223
 224 .. note::
 225    In the above mentioned ``docker build`` command, http_proxy & https_proxy arguments needs to be passed only if system is behind an HTTP or HTTPS proxy server.
 226
 227 Check the docker images:
 228
 229 .. code:: bash
 230
 231    $ sudo docker images
 232
 233 Output should contain a barometer image:
 234
 235 .. code::
 236
 237    REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
 238    barometer_image     latest              05f2a3edd96b        3 hours ago         1.2GB
 239    centos              7                   196e0ce0c9fb        4 weeks ago         197MB
 240    centos              latest              196e0ce0c9fb        4 weeks ago         197MB
 241    hello-world         latest              05a3bd381fc2        4 weeks ago         1.84kB
 242
 243 Run the barometer docker image:
 244
 245 .. code:: bash
 246
 247    $ sudo docker run -tid --net=host -v `pwd`/../src/collectd_sample_configs:/opt/collectd/etc/collectd.conf.d \
 248     -v /var/run:/var/run -v /tmp:/tmp --privileged barometer_image /run_collectd.sh
 249
 250 .. note::
 251   The docker barometer image contains configuration for all the collectd plugins. In the command
 252   above we are overriding /opt/collectd/etc/collectd.conf.d by mounting a host directory
 253   `pwd`/../src/collectd_sample_configs thta contains only the sample configurations we are interested
 254   in running.
 255
 256 To make some changes run:
 257
 258 .. code:: bash
 259
 260    sudo docker exec -tid barometer_image /bin/bash
 261
 262 Check your docker image is running
 263
 264 .. code:: bash
 265
 266    sudo docker ps
 267
 268 Build the influxdb + Grafana docker images
 269 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 270
 271 Start by installing docker compose:
 272
 273 .. code:: bash
 274
 275    $ sudo curl -L https://github.com/docker/compose/releases/download/1.17.0/docker-compose-`uname -s`-`uname -m` -o /usr/bin/docker-compose
 276
 277 .. note::
 278   Use the latest Compose release number in the download command. The above command is an example,
 279   and it may become out-of-date. To ensure you have the latest version, check the Compose repository
 280   release page on GitHub.
 281
 282 2. Apply executable permissions to the binary:
 283
 284 .. code:: bash
 285
 286    $ sudo chmod +x /usr/bin/docker-compose
 287
 288 3. Test the installation.
 289
 290 .. code:: bash
 291
 292   $ sudo docker-compose --version
 293
 294 4. Run the get_types_db.sh script in barometer/docker
 295
 296 5. Run the docker containers:
 297
 298 .. code:: bash
 299
 300   $ sudo docker-compose up -d
 301
 302 6. Check your docker images are running
 303
 304 .. code:: bash
 305
 306    $ sudo docker ps
 307
 308 7. Run the script to create the CPU dashboard barometer/docker:
 309
 310 .. code:: bash
 311
 312    $ ./configure_grafana.sh
 313
 314 8. Connect to <host_ip>:3000 with a browser and log into grafana: admin/admin
 315
 316 Testing the docker image
 317 ^^^^^^^^^^^^^^^^^^^^^^^^
 318
 319 TODO
 320
 321 References
 322 ^^^^^^^^^^^
 323 .. [1] https://docs.docker.com/engine/admin/systemd/#httphttps-proxy
 324 .. [2] https://docs.docker.com/engine/installation/linux/docker-ce/centos/#install-using-the-repository
 325 .. [3] https://docs.docker.com/engine/userguide/
 326