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 Check the docker images:
 225
 226 .. code:: bash
 227
 228    $ sudo docker images
 229
 230 Output should contain a barometer image:
 231
 232 .. code::
 233
 234    REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
 235    barometer_image     latest              05f2a3edd96b        3 hours ago         1.2GB
 236    centos              7                   196e0ce0c9fb        4 weeks ago         197MB
 237    centos              latest              196e0ce0c9fb        4 weeks ago         197MB
 238    hello-world         latest              05a3bd381fc2        4 weeks ago         1.84kB
 239
 240 Run the barometer docker image:
 241
 242 .. code:: bash
 243
 244    $ sudo docker run -tid --net=host -v `pwd`/../src/collectd_sample_configs:/opt/collectd/etc/collectd.conf.d \
 245     -v /var/run:/var/run -v /tmp:/tmp --privileged barometer_image /run_collectd.sh
 246
 247 .. note::
 248   The docker barometer image contains configuration for all the collectd plugins. In the command
 249   above we are overriding /opt/collectd/etc/collectd.conf.d by mounting a host directory
 250   `pwd`/../src/collectd_sample_configs thta contains only the sample configurations we are interested
 251   in running.
 252
 253 To make some changes run:
 254
 255 .. code:: bash
 256
 257    sudo docker exec -tid barometer_image /bin/bash
 258
 259 Check your docker image is running
 260
 261 .. code:: bash
 262
 263    sudo docker ps
 264
 265 Build the influxdb + Grafana docker images
 266 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 267
 268 Start by installing docker compose:
 269
 270 .. code:: bash
 271
 272    $ sudo curl -L https://github.com/docker/compose/releases/download/1.17.0/docker-compose-`uname -s`-`uname -m` -o /usr/bin/docker-compose
 273
 274 .. note::
 275   Use the latest Compose release number in the download command. The above command is an example,
 276   and it may become out-of-date. To ensure you have the latest version, check the Compose repository
 277   release page on GitHub.
 278
 279 2. Apply executable permissions to the binary:
 280
 281 .. code:: bash
 282
 283    $ sudo chmod +x /usr/bin/docker-compose
 284
 285 3. Test the installation.
 286
 287 .. code:: bash
 288
 289   $ sudo docker-compose --version
 290
 291 4. Run the get_types_db.sh script in barometer/docker
 292
 293 5. Run the docker containers:
 294
 295 .. code:: bash
 296
 297   $ sudo docker-compose up -d
 298
 299 6. Check your docker images are running
 300
 301 .. code:: bash
 302
 303    $ sudo docker ps
 304
 305 7. Run the script to create the CPU dashboard barometer/docker:
 306
 307 .. code:: bash
 308
 309    $ ./configure_grafana.sh
 310
 311 8. Connect to <host_ip>:3000 with a browser and log into grafana: admin/admin
 312
 313 Testing the docker image
 314 ^^^^^^^^^^^^^^^^^^^^^^^^
 315
 316 TODO
 317
 318 References
 319 ^^^^^^^^^^^
 320 .. [1] https://docs.docker.com/engine/admin/systemd/#httphttps-proxy
 321 .. [2] https://docs.docker.com/engine/installation/linux/docker-ce/centos/#install-using-the-repository
 322 .. [3] https://docs.docker.com/engine/userguide/
 323