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     $ sudo apt-get install git
  96
  97 The following steps have been verified with Ansible 2.6.3 on Centos 7.5.
  98 To install Ansible 2.6.3 on Centos:
  99
 100 .. code:: bash
 101
 102     $ sudo yum install python
 103     $ sudo yum install epel-release
 104     $ sudo yum install python-pip
 105     $ sudo -H pip install 'ansible==2.6.3'
 106     $ sudo yum install git
 107
 108 .. note::
 109    When using multi-node-setup, please make sure that 'python' package is
 110    installed on all of the target nodes (ansible during 'Gathering facts'
 111    phase is using python2 and it may not be installed by default on some
 112    distributions - e.g. on Ubuntu 16.04 it has to be installed manually)
 113
 114 Clone barometer repo
 115 ^^^^^^^^^^^^^^^^^^^^
 116
 117 .. code:: bash
 118
 119     $ git clone https://gerrit.opnfv.org/gerrit/barometer
 120     $ cd barometer/docker/ansible
 121
 122 Edit inventory file
 123 ^^^^^^^^^^^^^^^^^^^
 124 Edit inventory file and add hosts: $barometer_dir/docker/ansible/default.inv
 125
 126 .. code:: bash
 127
 128     [collectd_hosts]
 129     localhost
 130
 131     [collectd_hosts:vars]
 132     install_mcelog=true
 133     insert_ipmi_modules=true
 134     #to use master or experimental container set the collectd flavor below
 135     #possible values: stable|master|experimental
 136     flavor=stable
 137
 138     [influxdb_hosts]
 139     #hostname or ip must be used.
 140     #using localhost will cause issues with collectd network plugin.
 141     #hostname
 142
 143     [grafana_hosts]
 144     #NOTE: As per current support, Grafana and Influxdb should be same host.
 145     #hostname
 146
 147     [prometheus_hosts]
 148     #localhost
 149
 150     [zookeeper_hosts]
 151     #NOTE: currently one zookeeper host is supported
 152     #hostname
 153
 154     [kafka_hosts]
 155     #hostname
 156
 157     [ves_hosts]
 158     #hostname
 159
 160 Change localhost to different hosts where neccessary.
 161 Hosts for influxdb and grafana are required only for collectd_service.yml.
 162 Hosts for zookeeper, kafka and ves are required only for collectd_ves.yml.
 163
 164 .. note::
 165    Zookeeper, Kafka and VES need to be on the same host, there is no
 166    support for multi node setup.
 167
 168 To change host for kafka edit kafka_ip_addr in ./roles/config_files/vars/main.yml.
 169
 170 Additional plugin dependencies
 171 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 172
 173 By default ansible will try to fulfill dependencies for mcelog and ipmi plugin.
 174 For mcelog plugin it installs mcelog daemon. For ipmi it tries to insert ipmi_devintf
 175 and ipmi_si kernel modules.
 176 This can be changed in inventory file with use of variables install_mcelog
 177 and insert_ipmi_modules, both variables are independent:
 178
 179 .. code:: bash
 180
 181     [collectd_hosts:vars]
 182     install_mcelog=false
 183     insert_ipmi_modules=false
 184
 185 .. note::
 186    On Ubuntu 18.04 the deb package for mcelog daemon is not available in official
 187    Ubuntu repository. In that case ansible scripts will try to download, make and
 188    install the daemon from mcelog git repository.
 189
 190 Configure ssh keys
 191 ^^^^^^^^^^^^^^^^^^
 192
 193 Generate ssh keys if not present, otherwise move onto next step.
 194
 195 .. code:: bash
 196
 197     $ sudo ssh-keygen
 198
 199 Copy ssh key to all target hosts. It requires to provide root password.
 200 The example is for localhost.
 201
 202 .. code:: bash
 203
 204     $ sudo -i
 205     $ ssh-copy-id root@localhost
 206
 207 Verify that key is added and password is not required to connect.
 208
 209 .. code:: bash
 210
 211     $ sudo ssh root@localhost
 212
 213 .. note::
 214    Keys should be added to every target host and [localhost] is only used as an
 215    example. For multinode installation keys need to be copied for each node:
 216    [collectd_hostname], [influxdb_hostname] etc.
 217
 218 Download and run Collectd+Influxdb+Grafana containers
 219 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 220
 221 The One Click installation features easy and scalable deployment of Collectd,
 222 Influxdb and Grafana containers using Ansible playbook. The following steps goes
 223 through more details.
 224
 225 .. code:: bash
 226
 227     $ sudo -H ansible-playbook -i default.inv collectd_service.yml
 228
 229 Check the three containers are running, the output of docker ps should be similar to:
 230
 231 .. code:: bash
 232
 233     $ sudo docker ps
 234     CONTAINER ID        IMAGE                      COMMAND                  CREATED             STATUS              PORTS               NAMES
 235     a033aeea180d        opnfv/barometer-grafana    "/run.sh"                9 days ago          Up 7 minutes                            bar-grafana
 236     1bca2e4562ab        opnfv/barometer-influxdb   "/entrypoint.sh in..."   9 days ago          Up 7 minutes                            bar-influxdb
 237     daeeb68ad1d5        opnfv/barometer-collectd   "/run_collectd.sh ..."   9 days ago          Up 7 minutes                            bar-collectd
 238
 239 To make some changes when a container is running run:
 240
 241 .. code:: bash
 242
 243     $ sudo docker exec -ti <CONTAINER ID> /bin/bash
 244
 245 Connect to <host_ip>:3000 with a browser and log into Grafana: admin/admin.
 246 For short introduction please see the:
 247 `Grafana guide <http://docs.grafana.org/guides/getting_started/>`_.
 248
 249 The collectd configuration files can be accessed directly on target system in '/opt/collectd/etc/collectd.conf.d'.
 250 It can be used for manual changes or enable/disable plugins. If configuration has been modified it is required to
 251 restart collectd:
 252
 253 .. code:: bash
 254
 255     $ sudo docker restart bar-collectd
 256
 257 Download and run collectd+kafka+ves containers
 258 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 259
 260 .. code:: bash
 261
 262     $ sudo ansible-playbook -i default.inv collectd_ves.yml
 263
 264 Check the containers are running, the output of docker ps should be similar to:
 265
 266 .. code:: bash
 267
 268     $ sudo docker ps
 269     CONTAINER ID        IMAGE                      COMMAND                  CREATED             STATUS                     PORTS               NAMES
 270     29035be2dab5        zookeeper:3.4.11           "/docker-entrypoint._"   7 minutes ago       Up 7 minutes                                   bar-zookeeper
 271     eb8bba3c0b76        opnfv/barometer-ves        "./start_ves_app.s..."   6 minutes ago       Up 6 minutes                                   bar-ves
 272     86702a96a68c        opnfv/barometer-kafka      "/src/start_kafka.sh"    6 minutes ago       Up 6 minutes                                   bar-kafka
 273     daeeb68ad1d5        opnfv/barometer-collectd   "/run_collectd.sh ..."   6 minutes ago       Up 6 minutes                                   bar-collectd
 274
 275
 276 To make some changes when a container is running run:
 277
 278 .. code:: bash
 279
 280     $ sudo docker exec -ti <CONTAINER ID> /bin/bash
 281
 282 List of default plugins for collectd container
 283 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 284 .. note::
 285    The dpdk plugins dpdkevents and dpdkstat were tested with DPDK v18.11.
 286
 287 By default the collectd is started with default configuration which includes the followin plugins:
 288    * csv, contextswitch, cpu, cpufreq, df, disk, ethstat, ipc, irq, load, memory, numa, processes,
 289      swap, turbostat, uuid, uptime, exec, hugepages, intel_pmu, ipmi, write_kafka, logfile, mcelog,
 290      network, intel_rdt, rrdtool, snmp_agent, syslog, virt, ovs_stats, ovs_events, dpdkevents,
 291      dpdkstat
 292
 293 Some of the plugins are loaded depending on specific system requirements and can be omitted if
 294 dependency is not met, this is the case for:
 295    * hugepages, ipmi, mcelog, intel_rdt, virt, ovs_stats, ovs_events
 296
 297 List and description of tags used in ansible scripts
 298 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 299
 300 Tags can be used to run a specific part of the configuration without running the whole playbook.
 301 To run a specific parts only:
 302
 303 .. code:: bash
 304
 305     $ sudo ansible-playbook -i default.inv collectd_service.yml --tags "syslog,cpu,uuid"
 306
 307 To disable some parts or plugins:
 308
 309 .. code:: bash
 310
 311     $ sudo ansible-playbook -i default.inv collectd_service.yml --skip-tags "en_default_all,syslog,cpu,uuid"
 312
 313 List of available tags:
 314
 315 install_docker
 316   Install docker and required dependencies with package manager.
 317
 318 add_docker_proxy
 319   Configure proxy file for docker service if proxy is set on host environment.
 320
 321 rm_config_dir
 322   Remove collectd config files.
 323
 324 copy_additional_configs
 325   Copy additional configuration files to target system. Path to additional configuration
 326   is stored in $barometer_dir/docker/ansible/roles/config_files/vars/main.yml as additional_configs_path.
 327
 328 en_default_all
 329   Set of default read plugins: contextswitch, cpu, cpufreq, df, disk, ethstat, ipc, irq,
 330   load, memory, numa, processes, swap, turbostat, uptime.
 331
 332 plugins tags
 333   The following tags can be used to enable/disable plugins: csv, contextswitch, cpu,
 334   cpufreq, df, disk, ethstat, ipc, irq, load, memory, numa, processes, swap, turbostat,
 335   uptime, exec, hugepages, ipmi, kafka, logfile, mcelogs, network, pmu, rdt, rrdtool,
 336   snmp, syslog, virt, ovs_stats, ovs_events, uuid, dpdkevents, dpdkstat.
 337
 338