docs/release/userguide/installguide.oneclick.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-oneclick-userguide:
   5
   6 =======================================
   7 OPNFV Barometer One Click Install Guide
   8 =======================================
   9
  10 .. contents::
  11    :depth: 3
  12    :local:
  13
  14 The intention of this user guide is to outline how to use the ansible playbooks for a one click installation of Barometer. A more in-depth installation guide is available with the :ref:`Docker user guide <barometer-docker-userguide>`.
  15
  16
  17 One Click Install with Ansible
  18 ------------------------------
  19
  20
  21 Proxy for package manager on host
  22 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  23 .. note::
  24    This step has to be performed only if host is behind HTTP/HTTPS proxy
  25
  26 Proxy URL have to be set in dedicated config file
  27
  28 1. CentOS - /etc/yum.conf
  29
  30 .. code:: bash
  31
  32     proxy=http://your.proxy.domain:1234
  33
  34 2. Ubuntu - /etc/apt/apt.conf
  35
  36 .. code:: bash
  37
  38     Acquire::http::Proxy "http://your.proxy.domain:1234"
  39
  40 After update of config file, apt mirrors have to be updated via 'apt-get update'
  41
  42 .. code:: bash
  43
  44     $ sudo apt-get update
  45
  46 Proxy environment variables (for docker and pip)
  47 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  48 .. note::
  49    This step has to be performed only if host is behind HTTP/HTTPS proxy
  50
  51 Configuring proxy for packaging system is not enough, also some proxy
  52 environment variables have to be set in the system before ansible scripts
  53 can be started.
  54 Barometer configures docker proxy automatically via ansible task as a part
  55 of 'one click install' process - user only has to provide proxy URL using common
  56 shell environment variables and ansible will automatically configure proxies
  57 for docker(to be able to fetch barometer images). Another component used by
  58 ansible (e.g. pip is used for downloading python dependencies) will also benefit
  59 from setting proxy variables properly in the system.
  60
  61 Proxy variables used by ansible One Click Install:
  62    * http_proxy
  63    * https_proxy
  64    * ftp_proxy
  65    * no_proxy
  66
  67 Variables mentioned above have to be visible for superuser (because most
  68 actions involving ansible-barometer installation require root privileges).
  69 Proxy variables are commonly defined in '/etc/environment' file (but any other
  70 place is good as long as variables can be seen by commands using 'su').
  71
  72 Sample proxy configuration in /etc/environment:
  73
  74 .. code:: bash
  75
  76     http_proxy=http://your.proxy.domain:1234
  77     https_proxy=http://your.proxy.domain:1234
  78     ftp_proxy=http://your.proxy.domain:1234
  79     no_proxy=localhost
  80
  81 Install Ansible
  82 ^^^^^^^^^^^^^^^
  83 .. note::
  84    * sudo permissions or root access are required to install ansible.
  85    * ansible version needs to be 2.4+, because usage of import/include statements
  86
  87 The following steps have been verified with Ansible 2.6.3 on Ubuntu 16.04 and 18.04.
  88 To install Ansible 2.6.3 on Ubuntu:
  89
  90 .. code:: bash
  91
  92     $ sudo apt-get install python
  93     $ sudo apt-get install python-pip
  94     $ sudo -H pip install 'ansible==2.6.3'
  95
  96 The following steps have been verified with Ansible 2.6.3 on Centos 7.5.
  97 To install Ansible 2.6.3 on Centos:
  98
  99 .. code:: bash
 100
 101     $ sudo yum install python
 102     $ sudo yum install epel-release
 103     $ sudo yum install python-pip
 104     $ sudo -H pip install 'ansible==2.6.3'
 105     $ sudo yum install git
 106
 107 .. note::
 108    When using multi-node-setup, please make sure that 'python' package is
 109    installed on all of the target nodes (ansible during 'Gathering facts'
 110    phase is using python2 and it may not be installed by default on some
 111    distributions - e.g. on Ubuntu 16.04 it has to be installed manually)
 112
 113 Clone barometer repo
 114 ^^^^^^^^^^^^^^^^^^^^
 115
 116 .. code:: bash
 117
 118     $ git clone https://gerrit.opnfv.org/gerrit/barometer
 119     $ cd barometer/docker/ansible
 120
 121 Edit inventory file
 122 ^^^^^^^^^^^^^^^^^^^
 123 Edit inventory file and add hosts: $barometer_dir/docker/ansible/default.inv
 124
 125 .. code:: bash
 126
 127     [collectd_hosts]
 128     localhost
 129
 130     [collectd_hosts:vars]
 131     install_mcelog=true
 132     insert_ipmi_modules=true
 133
 134     [influxdb_hosts]
 135     localhost
 136
 137     [grafana_hosts]
 138     localhost
 139
 140     [prometheus_hosts]
 141     #localhost
 142
 143     [zookeeper_hosts]
 144     #NOTE: currently one zookeeper host is supported
 145     #hostname
 146
 147     [kafka_hosts]
 148     #hostname
 149
 150     [ves_hosts]
 151     #hostname
 152
 153 Change localhost to different hosts where neccessary.
 154 Hosts for influxdb and grafana are required only for collectd_service.yml.
 155 Hosts for zookeeper, kafka and ves are required only for collectd_ves.yml.
 156
 157 .. note::
 158    Zookeeper, Kafka and VES need to be on the same host, there is no
 159    support for multi node setup.
 160
 161 To change host for kafka edit kafka_ip_addr in ./roles/config_files/vars/main.yml.
 162
 163 Additional plugin dependencies
 164 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 165
 166 By default ansible will try to fulfill dependencies for mcelog and ipmi plugin.
 167 For mcelog plugin it installs mcelog daemon. For ipmi it tries to insert ipmi_devintf
 168 and ipmi_si kernel modules.
 169 This can be changed in inventory file with use of variables install_mcelog
 170 and insert_ipmi_modules, both variables are independent:
 171
 172 .. code:: bash
 173
 174     [collectd_hosts:vars]
 175     install_mcelog=false
 176     insert_ipmi_modules=false
 177
 178 .. note::
 179    On Ubuntu 18.04 the deb package for mcelog daemon is not available in official
 180    Ubuntu repository. In that case ansible scripts will try to download, make and
 181    install the daemon from mcelog git repository.
 182
 183 Configure ssh keys
 184 ^^^^^^^^^^^^^^^^^^
 185
 186 Generate ssh keys if not present, otherwise move onto next step.
 187
 188 .. code:: bash
 189
 190     $ sudo ssh-keygen
 191
 192 Copy ssh key to all target hosts. It requires to provide root password.
 193 The example is for localhost.
 194
 195 .. code:: bash
 196
 197     $ sudo -i
 198     $ ssh-copy-id root@localhost
 199
 200 Verify that key is added and password is not required to connect.
 201
 202 .. code:: bash
 203
 204     $ sudo ssh root@localhost
 205
 206 .. note::
 207    Keys should be added to every target host and [localhost] is only used as an
 208    example. For multinode installation keys need to be copied for each node:
 209    [collectd_hostname], [influxdb_hostname] etc.
 210
 211 Download and run Collectd+Influxdb+Grafana containers
 212 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 213
 214 The One Click installation features easy and scalable deployment of Collectd,
 215 Influxdb and Grafana containers using Ansible playbook. The following steps goes
 216 through more details.
 217
 218 .. code:: bash
 219
 220     $ sudo -H ansible-playbook -i default.inv collectd_service.yml
 221
 222 Check the three containers are running, the output of docker ps should be similar to:
 223
 224 .. code:: bash
 225
 226     $ sudo docker ps
 227     CONTAINER ID        IMAGE                      COMMAND                  CREATED             STATUS              PORTS               NAMES
 228     a033aeea180d        opnfv/barometer-grafana    "/run.sh"                9 days ago          Up 7 minutes                            bar-grafana
 229     1bca2e4562ab        opnfv/barometer-influxdb   "/entrypoint.sh in..."   9 days ago          Up 7 minutes                            bar-influxdb
 230     daeeb68ad1d5        opnfv/barometer-collectd   "/run_collectd.sh ..."   9 days ago          Up 7 minutes                            bar-collectd
 231
 232 To make some changes when a container is running run:
 233
 234 .. code:: bash
 235
 236     $ sudo docker exec -ti <CONTAINER ID> /bin/bash
 237
 238 Connect to <host_ip>:3000 with a browser and log into Grafana: admin/admin.
 239 For short introduction please see the:
 240 `Grafana guide <http://docs.grafana.org/guides/getting_started/>`_.
 241
 242 The collectd configuration files can be accessed directly on target system in '/opt/collectd/etc/collectd.conf.d'.
 243 It can be used for manual changes or enable/disable plugins. If configuration has been modified it is required to
 244 restart collectd:
 245
 246 .. code:: bash
 247
 248     $ sudo docker restart bar-collectd
 249
 250 Download and run collectd+kafka+ves containers
 251 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 252
 253 .. code:: bash
 254
 255     $ sudo ansible-playbook -i default.inv collectd_ves.yml
 256
 257 Check the containers are running, the output of docker ps should be similar to:
 258
 259 .. code:: bash
 260
 261     $ sudo docker ps
 262     CONTAINER ID        IMAGE                      COMMAND                  CREATED             STATUS                     PORTS               NAMES
 263     29035be2dab5        zookeeper:3.4.11           "/docker-entrypoint._"   7 minutes ago       Up 7 minutes                                   bar-zookeeper
 264     eb8bba3c0b76        opnfv/barometer-ves        "./start_ves_app.s..."   6 minutes ago       Up 6 minutes                                   bar-ves
 265     86702a96a68c        opnfv/barometer-kafka      "/src/start_kafka.sh"    6 minutes ago       Up 6 minutes                                   bar-kafka
 266     daeeb68ad1d5        opnfv/barometer-collectd   "/run_collectd.sh ..."   6 minutes ago       Up 6 minutes                                   bar-collectd
 267
 268
 269 To make some changes when a container is running run:
 270
 271 .. code:: bash
 272
 273     $ sudo docker exec -ti <CONTAINER ID> /bin/bash
 274
 275 List of default plugins for collectd container
 276 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 277 .. note::
 278    The dpdk plugins dpdkevents and dpdkstat were tested with DPDK v16.11.
 279
 280 By default the collectd is started with default configuration which includes the followin plugins:
 281    * csv, contextswitch, cpu, cpufreq, df, disk, ethstat, ipc, irq, load, memory, numa, processes,
 282      swap, turbostat, uuid, uptime, exec, hugepages, intel_pmu, ipmi, write_kafka, logfile, mcelog,
 283      network, intel_rdt, rrdtool, snmp_agent, syslog, virt, ovs_stats, ovs_events, dpdkevents,
 284      dpdkstat
 285
 286 Some of the plugins are loaded depending on specific system requirements and can be omitted if
 287 dependency is not met, this is the case for:
 288    * hugepages, ipmi, mcelog, intel_rdt, virt, ovs_stats, ovs_events
 289
 290 List and description of tags used in ansible scripts
 291 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 292
 293 Tags can be used to run a specific part of the configuration without running the whole playbook.
 294 To run a specific parts only:
 295
 296 .. code:: bash
 297
 298     $ sudo ansible-playbook -i default.inv collectd_service.yml --tags "syslog,cpu,uuid"
 299
 300 To disable some parts or plugins:
 301
 302 .. code:: bash
 303
 304     $ sudo ansible-playbook -i default.inv collectd_service.yml --skip-tags "en_default_all,syslog,cpu,uuid"
 305
 306 List of available tags:
 307
 308 install_docker
 309   Install docker and required dependencies with package manager.
 310
 311 add_docker_proxy
 312   Configure proxy file for docker service if proxy is set on host environment.
 313
 314 rm_config_dir
 315   Remove collectd config files.
 316
 317 copy_additional_configs
 318   Copy additional configuration files to target system. Path to additional configuration
 319   is stored in $barometer_dir/docker/ansible/roles/config_files/vars/main.yml as additional_configs_path.
 320
 321 en_default_all
 322   Set of default read plugins: contextswitch, cpu, cpufreq, df, disk, ethstat, ipc, irq,
 323   load, memory, numa, processes, swap, turbostat, uptime.
 324
 325 plugins tags
 326   The following tags can be used to enable/disable plugins: csv, contextswitch, cpu,
 327   cpufreq, df, disk, ethstat, ipc, irq, load, memory, numa, processes, swap, turbostat,
 328   uptime, exec, hugepages, ipmi, kafka, logfile, mcelogs, network, pmu, rdt, rrdtool,
 329   snmp, syslog, virt, ovs_stats, ovs_events, uuid, dpdkevents, dpdkstat.
 330
 331