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