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 ssh keys are required for Ansible to connect the host you use for Barometer Installation.
 195
 196 .. code:: bash
 197
 198     $ sudo ssh-keygen
 199
 200 Copy ssh key to all target hosts. It requires to provide root password.
 201 The example is for localhost.
 202
 203 .. code:: bash
 204
 205     $ sudo -i
 206     $ ssh-copy-id root@localhost
 207
 208 Verify that key is added and password is not required to connect.
 209
 210 .. code:: bash
 211
 212     $ sudo ssh root@localhost
 213
 214 .. note::
 215    Keys should be added to every target host and [localhost] is only used as an
 216    example. For multinode installation keys need to be copied for each node:
 217    [collectd_hostname], [influxdb_hostname] etc.
 218
 219 Download and run Collectd+Influxdb+Grafana containers
 220 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 221
 222 The One Click installation features easy and scalable deployment of Collectd,
 223 Influxdb and Grafana containers using Ansible playbook. The following steps goes
 224 through more details.
 225
 226 .. code:: bash
 227
 228     $ sudo -H ansible-playbook -i default.inv collectd_service.yml
 229
 230 Check the three containers are running, the output of docker ps should be similar to:
 231
 232 .. code:: bash
 233
 234     $ sudo docker ps
 235     CONTAINER ID        IMAGE                      COMMAND                  CREATED             STATUS              PORTS               NAMES
 236     a033aeea180d        opnfv/barometer-grafana    "/run.sh"                9 days ago          Up 7 minutes                            bar-grafana
 237     1bca2e4562ab        opnfv/barometer-influxdb   "/entrypoint.sh in..."   9 days ago          Up 7 minutes                            bar-influxdb
 238     daeeb68ad1d5        opnfv/barometer-collectd   "/run_collectd.sh ..."   9 days ago          Up 7 minutes                            bar-collectd
 239
 240 To make some changes when a container is running run:
 241
 242 .. code:: bash
 243
 244     $ sudo docker exec -ti <CONTAINER ID> /bin/bash
 245
 246 Connect to <host_ip>:3000 with a browser and log into Grafana: admin/admin.
 247 For short introduction please see the:
 248 `Grafana guide <http://docs.grafana.org/guides/getting_started/>`_.
 249
 250 The collectd configuration files can be accessed directly on target system in '/opt/collectd/etc/collectd.conf.d'.
 251 It can be used for manual changes or enable/disable plugins. If configuration has been modified it is required to
 252 restart collectd:
 253
 254 .. code:: bash
 255
 256     $ sudo docker restart bar-collectd
 257
 258 Download and run collectd+kafka+ves containers
 259 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 260
 261 .. code:: bash
 262
 263     $ sudo ansible-playbook -i default.inv collectd_ves.yml
 264
 265 Check the containers are running, the output of docker ps should be similar to:
 266
 267 .. code:: bash
 268
 269     $ sudo docker ps
 270     CONTAINER ID        IMAGE                      COMMAND                  CREATED             STATUS                     PORTS               NAMES
 271     29035be2dab5        zookeeper:3.4.11           "/docker-entrypoint._"   7 minutes ago       Up 7 minutes                                   bar-zookeeper
 272     eb8bba3c0b76        opnfv/barometer-ves        "./start_ves_app.s..."   6 minutes ago       Up 6 minutes                                   bar-ves
 273     86702a96a68c        opnfv/barometer-kafka      "/src/start_kafka.sh"    6 minutes ago       Up 6 minutes                                   bar-kafka
 274     daeeb68ad1d5        opnfv/barometer-collectd   "/run_collectd.sh ..."   6 minutes ago       Up 6 minutes                                   bar-collectd
 275
 276
 277 To make some changes when a container is running run:
 278
 279 .. code:: bash
 280
 281     $ sudo docker exec -ti <CONTAINER ID> /bin/bash
 282
 283 List of default plugins for collectd container
 284 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 285 .. note::
 286    The dpdk plugins dpdkevents and dpdkstat were tested with DPDK v16.11.
 287
 288 By default the collectd is started with default configuration which includes the followin plugins:
 289    * csv, contextswitch, cpu, cpufreq, df, disk, ethstat, ipc, irq, load, memory, numa, processes,
 290      swap, turbostat, uuid, uptime, exec, hugepages, intel_pmu, ipmi, write_kafka, logfile, mcelog,
 291      network, intel_rdt, rrdtool, snmp_agent, syslog, virt, ovs_stats, ovs_events, dpdkevents,
 292      dpdkstat
 293
 294 Some of the plugins are loaded depending on specific system requirements and can be omitted if
 295 dependency is not met, this is the case for:
 296    * hugepages, ipmi, mcelog, intel_rdt, virt, ovs_stats, ovs_events
 297
 298 List and description of tags used in ansible scripts
 299 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 300
 301 Tags can be used to run a specific part of the configuration without running the whole playbook.
 302 To run a specific parts only:
 303
 304 .. code:: bash
 305
 306     $ sudo ansible-playbook -i default.inv collectd_service.yml --tags "syslog,cpu,uuid"
 307
 308 To disable some parts or plugins:
 309
 310 .. code:: bash
 311
 312     $ sudo ansible-playbook -i default.inv collectd_service.yml --skip-tags "en_default_all,syslog,cpu,uuid"
 313
 314 List of available tags:
 315
 316 install_docker
 317   Install docker and required dependencies with package manager.
 318
 319 add_docker_proxy
 320   Configure proxy file for docker service if proxy is set on host environment.
 321
 322 rm_config_dir
 323   Remove collectd config files.
 324
 325 copy_additional_configs
 326   Copy additional configuration files to target system. Path to additional configuration
 327   is stored in $barometer_dir/docker/ansible/roles/config_files/vars/main.yml as additional_configs_path.
 328
 329 en_default_all
 330   Set of default read plugins: contextswitch, cpu, cpufreq, df, disk, ethstat, ipc, irq,
 331   load, memory, numa, processes, swap, turbostat, uptime.
 332
 333 plugins tags
 334   The following tags can be used to enable/disable plugins: csv, contextswitch, cpu,
 335   cpufreq, df, disk, ethstat, ipc, irq, load, memory, numa, processes, swap, turbostat,
 336   uptime, exec, hugepages, ipmi, kafka, logfile, mcelogs, network, pmu, rdt, rrdtool,
 337   snmp, syslog, virt, ovs_stats, ovs_events, uuid, dpdkevents, dpdkstat.
 338
 339