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 .. code:: bash
 132
 133     [collectd_hosts]
 134     localhost
 135
 136     [collectd_hosts:vars]
 137     install_mcelog=true
 138     insert_ipmi_modules=true
 139     #to use master or experimental container set the collectd flavor below
 140     #possible values: stable|master|experimental
 141     flavor=stable
 142
 143     [influxdb_hosts]
 144     #hostname or ip must be used.
 145     #using localhost will cause issues with collectd network plugin.
 146     #hostname
 147
 148     [grafana_hosts]
 149     #NOTE: As per current support, Grafana and Influxdb should be same host.
 150     #hostname
 151
 152     [prometheus_hosts]
 153     #localhost
 154
 155     [zookeeper_hosts]
 156     #NOTE: currently one zookeeper host is supported
 157     #hostname
 158
 159     [kafka_hosts]
 160     #hostname
 161
 162     [ves_hosts]
 163     #hostname
 164
 165 Change localhost to different hosts where neccessary.
 166 Hosts for influxdb and grafana are required only for ``collectd_service.yml``.
 167 Hosts for zookeeper, kafka and ves are required only for ``collectd_ves.yml``.
 168
 169 .. note::
 170    Zookeeper, Kafka and VES need to be on the same host, there is no
 171    support for multi node setup.
 172
 173 To change host for kafka edit ``kafka_ip_addr`` in
 174 ``./roles/config_files/vars/main.yml``.
 175
 176 Additional plugin dependencies
 177 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 178
 179 By default ansible will try to fulfill dependencies for ``mcelog`` and
 180 ``ipmi`` plugin. For ``mcelog`` plugin it installs mcelog daemon. For ipmi it
 181 tries to insert ``ipmi_devintf`` and ``ipmi_si`` kernel modules.
 182 This can be changed in inventory file with use of variables ``install_mcelog``
 183 and ``insert_ipmi_modules``, both variables are independent:
 184
 185 .. code:: bash
 186
 187     [collectd_hosts:vars]
 188     install_mcelog=false
 189     insert_ipmi_modules=false
 190
 191 .. note::
 192    On Ubuntu 18.04 the deb package for mcelog daemon is not available in official
 193    Ubuntu repository. In that case ansible scripts will try to download, make and
 194    install the daemon from mcelog git repository.
 195
 196 Configure ssh keys
 197 ^^^^^^^^^^^^^^^^^^
 198
 199 Generate ssh keys if not present, otherwise move onto next step.
 200 ssh keys are required for Ansible to connect the host you use for Barometer Installation.
 201
 202 .. code:: bash
 203
 204     $ sudo ssh-keygen
 205
 206 Copy ssh key to all target hosts. It requires to provide root password.
 207 The example is for ``localhost``.
 208
 209 .. code:: bash
 210
 211     $ sudo -i
 212     $ ssh-copy-id root@localhost
 213
 214 Verify that key is added and password is not required to connect.
 215
 216 .. code:: bash
 217
 218     $ sudo ssh root@localhost
 219
 220 .. note::
 221    Keys should be added to every target host and [localhost] is only used as an
 222    example. For multinode installation keys need to be copied for each node:
 223    [collectd_hostname], [influxdb_hostname] etc.
 224
 225 Download and run Collectd+Influxdb+Grafana containers
 226 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 227
 228 The One Click installation features easy and scalable deployment of Collectd,
 229 Influxdb and Grafana containers using Ansible playbook. The following steps goes
 230 through more details.
 231
 232 .. code:: bash
 233
 234     $ sudo -H ansible-playbook -i default.inv collectd_service.yml
 235
 236 Check the three containers are running, the output of ``docker ps`` should be similar to:
 237
 238 .. code:: bash
 239
 240     $ sudo docker ps
 241     CONTAINER ID        IMAGE                      COMMAND                  CREATED             STATUS              PORTS               NAMES
 242     a033aeea180d        opnfv/barometer-grafana    "/run.sh"                9 days ago          Up 7 minutes                            bar-grafana
 243     1bca2e4562ab        opnfv/barometer-influxdb   "/entrypoint.sh in..."   9 days ago          Up 7 minutes                            bar-influxdb
 244     daeeb68ad1d5        opnfv/barometer-collectd   "/run_collectd.sh ..."   9 days ago          Up 7 minutes                            bar-collectd
 245
 246 To make some changes when a container is running run:
 247
 248 .. code:: bash
 249
 250     $ sudo docker exec -ti <CONTAINER ID> /bin/bash
 251
 252 Connect to ``<host_ip>:3000`` with a browser and log into Grafana: admin/admin.
 253 For short introduction please see the:
 254 `Grafana guide <http://docs.grafana.org/guides/getting_started/>`_.
 255
 256 The collectd configuration files can be accessed directly on target system in
 257 ``/opt/collectd/etc/collectd.conf.d``. It can be used for manual changes or
 258 enable/disable plugins. If configuration has been modified it is required to
 259 restart collectd:
 260
 261 .. code:: bash
 262
 263     $ sudo docker restart bar-collectd
 264
 265 Download and run collectd+kafka+ves containers
 266 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 267
 268 .. code:: bash
 269
 270     $ sudo ansible-playbook -i default.inv collectd_ves.yml
 271
 272 Check the containers are running, the output of ``docker ps`` should be similar to:
 273
 274 .. code:: bash
 275
 276     $ sudo docker ps
 277     CONTAINER ID        IMAGE                      COMMAND                  CREATED             STATUS                     PORTS               NAMES
 278     29035be2dab5        zookeeper:3.4.11           "/docker-entrypoint._"   7 minutes ago       Up 7 minutes                                   bar-zookeeper
 279     eb8bba3c0b76        opnfv/barometer-ves        "./start_ves_app.s..."   6 minutes ago       Up 6 minutes                                   bar-ves
 280     86702a96a68c        opnfv/barometer-kafka      "/src/start_kafka.sh"    6 minutes ago       Up 6 minutes                                   bar-kafka
 281     daeeb68ad1d5        opnfv/barometer-collectd   "/run_collectd.sh ..."   6 minutes ago       Up 6 minutes                                   bar-collectd
 282
 283
 284 To make some changes when a container is running run:
 285
 286 .. code:: bash
 287
 288     $ sudo docker exec -ti <CONTAINER ID> /bin/bash
 289
 290 List of default plugins for collectd container
 291 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 292 .. note::
 293    From Jerma release, the supported dpdk version is 19.11
 294
 295    If you would like to use v18.11, Do the following changes:
 296     1.Update the dpdk version to v18.11 in <barometer>/src/package-list.mk
 297     2.Replace all 'common_linux' string with 'common_linuxapp' in <barometer>/src/dpdk/Makefile
 298
 299    If you would like to downgrade to a version lower than v18.11, Do the following changes:
 300     1.Update the dpdk version to a version lower than v18.11(Eg:- v16.11) in <barometer>/src/package-list.mk
 301     2.Replace all 'common_linux' string with 'common_linuxapp' in <barometer>/src/dpdk/Makefile
 302     3.Change the Makefile path from '(WORKDIR)/kernel/linux/kni/Makefile' to (WORKDIR)/lib/librte_eal/linuxapp/kni/Makefile in '(WORK_DIR)/src/dpdk/Makefile'.
 303
 304 By default the collectd is started with default configuration which includes
 305 the following plugins:
 306     * ``csv``, ``contextswitch``, ``cpu``, ``cpufreq``, ``df``, ``disk``,
 307       ``ethstat``, ``ipc``, ``irq``, ``load``, ``memory``, ``numa``,
 308       ``processes``, ``swap``, ``turbostat``, ``uuid``, ``uptime``, ``exec``,
 309       ``hugepages``, ``intel_pmu``, ``ipmi``, ``write_kafka``, ``logfile``,
 310       ``mcelog``, ``network``, ``intel_rdt``, ``rrdtool``, ``snmp_agent``,
 311       ``syslog``, ``virt``, ``ovs_stats``, ``ovs_events``, ``dpdk_telemetry``
 312
 313 .. note::
 314    Some of the plugins are loaded depending on specific system requirements and can be omitted if
 315    dependency is not met, this is the case for:
 316    * ``hugepages``, ``ipmi``, ``mcelog``, ``intel_rdt``, ``virt``, ``ovs_stats``, ``ovs_events``
 317
 318 .. note::
 319    The ``dpdkstat`` and ``dpdkevents`` plugins are disabled by default (in
 320    favour of the ``dpdk_telemetry`` plugin) and need to be explicitly enabled
 321    in order to use them:
 322
 323    .. code:: bash
 324
 325    $ sudo ansible-playbook -i default.inv collectd_service.yml --tags "all,dpdkstats,dpdkevents"
 326
 327 List and description of tags used in ansible scripts
 328 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 329
 330 Tags can be used to run a specific part of the configuration without running
 331 the whole playbook. To run a specific parts only:
 332
 333 .. code:: bash
 334
 335     $ sudo ansible-playbook -i default.inv collectd_service.yml --tags "syslog,cpu,uuid"
 336
 337 To disable some parts or plugins:
 338
 339 .. code:: bash
 340
 341     $ sudo ansible-playbook -i default.inv collectd_service.yml --skip-tags "en_default_all,syslog,cpu,uuid"
 342
 343 List of available tags:
 344
 345 ``install_docker``
 346   Install docker and required dependencies with package manager.
 347
 348 ``add_docker_proxy``
 349   Configure proxy file for docker service if proxy is set on host environment.
 350
 351 ``rm_config_dir``
 352   Remove collectd config files.
 353
 354 ``copy_additional_configs``
 355   Copy additional configuration files to target system. Path to additional
 356   configuration is stored in
 357   ``$barometer_dir/docker/ansible/roles/config_files/vars/main.yml`` as
 358   ``additional_configs_path``.
 359
 360 ``en_default_all``
 361   Set of default read plugins: ``contextswitch``, ``cpu``, ``cpufreq``, ``df``,
 362   ``disk``, ``ethstat``, ``ipc``, ``irq``, ``load``, ``memory``, ``numa``,
 363   ``processes``, ``swap``, ``turbostat``, ``uptime``.
 364
 365 ``plugins tags``
 366   The following tags can be used to enable/disable plugins: ``csv``,
 367   ``contextswitch``, ``cpu``, ``cpufreq``, ``df``, ``disk,`` ``ethstat``,
 368   ``ipc``, ``irq``, ``load``, ``memory``, ``numa``, ``processes``, ``swap``,
 369   ``turbostat``, ``uptime``, ``exec``, ``hugepages``, ``ipmi``, ``kafka``,
 370   ``logfile``, ``mcelogs``, ``n``etwork``,`` ``pmu``, ``rdt``, ``rrdtool``,
 371   ``snmp``, ``syslog``, ``virt``, ``ovs_stats``, ``ovs_events``, ``uuid``,
 372   ``dpdkevents``, ``dpdkstat``, ``dpdk_telemetry``.
 373