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