Update git submodules

[opnfvdocs.git] / docs / images / overview.rst

.. _overview:

.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. SPDX-License-Identifier: CC-BY-4.0
.. (c) Open Platform for NFV Project, Inc. and its contributors

=======================
Infrastructure Overview
=======================

OPNFV develops, operates, and maintains infrastructure which is used by the OPNFV
Community for development, integration, and testing purposes. `OPNFV
Infrastructure Working Group (Infra WG) <https://wiki.opnfv.org/display/INF>`_
oversees the OPNFV Infrastructure, ensures it is kept in a state which serves
the community in best possible way and always up to date.

Infra WG is working towards a model whereby we have a seamless pipeline
for handing resource requests from the OPNFV community for both development and
Continuous Integration perspectives. Automation of requests and integration to
existing automation tools is a primary driver in reaching this model. In the
Infra WG, we imagine a model where the Infrastructure Requirements that are
specified by a Feature, Installer or otherrelevant projects within OPNFV are
requested, provisioned, used, reported on and subsequently torn down with no (or
minimal) user intervention at the physical/infrastructure level.

Objectives of the Infra WG are

* Deliver efficiently dimensions resources to OPNFV community needs on request in a timely manner that ensure maximum usage (capacity) and maximum density (distribution of workloads)
* Satisfy the needs of the twice-yearly release projects, this includes being able to handle load (amount of projects and requests) as well as need (topology and different layouts)
* Support OPNFV community users.  As the INFRA group, we are integral to all aspects of the OPNFV Community (since it starts with the Hardware) - this can mean troubleshooting any element within the stack
* Provide a method to expand and adapt as OPNFV community needs grow and provide this to Hosting Providers (lab providers) for input in growth forecast so they can better judge how best to contribute with their resources.
* Work with reporting and other groups to ensure we have adequate feedback to the end-users of the labs on how their systems, code, feature performs.

The details of what is provided as part of the infrastructure can be seen in following chapters.

Hardware Infrastructure
-----------------------

TBD

Software Infrastructure
-----------------------

TBD

.. toctree::
   :maxdepth: 1

   ../submodules/releng/docs/sofware-infrastructure-index

Power Consumption Monitoring Framework
======================================

Introduction
------------
Power consumption is a key driver for NFV.
As an end user is interested to know which application is good/bad regarding
power consumption and explains why he/she has to plug his/her smartphone every
day, we would be interested to know which VNF is power consuming.

Power consumption is hard to evaluate empirically. It is however possible to
collect information and leverage Pharos federation to try to detect some
profiles/footprints.
In fact thanks to CI, we know that we are running a known/deterministic list of
cases. The idea is to correlate this knowledge with the power consumption to try
at the end to find statistical biais.


High Level Architecture
-----------------------

The energy recorder high level architecture may be described as follows:

.. figure:: ../../images/energyrecorder.png
   :align: center
   :alt: Energy recorder high level architecture

The energy monitoring system in based on 3 software components:

   * Power info collector: poll server to collect instantaneous power consumption information
   * Energy recording API + influxdb: On one leg receive servers consumption and
   on the other, scenarios notfication. It then able to establish te correlation
   between consumption and scenario and stores it into a time-series database (influxdb)
   * Python SDK: A Python SDK using decorator to send notification to Energy
   recording API from testcases scenarios

Power Info Collector
--------------------
It collects instantaneous power consumption information and send it to Event
API in charge of data storing.
The collector use different connector to read the power consumption on remote
servers:

  * IPMI: this is the basic method and is manufacturer dependent.
  Depending on manufacturer, refreshing delay may vary (generally for 10 to 30 sec.)
  * RedFish: redfish is an industry RESTFUL API for hardware managment.
  Unfortunatly it is not yet supported by many suppliers.
  * ILO: HP RESTFULL API:
  This connector support as well 2.1 as 2.4 version of HP-ILO

IPMI is supported by at least:

  * HP
  * IBM
  * Dell
  * Nokia
  * Advantech
  * Lenovo
  * Huawei

Redfish API has been successfully tested on:

  * HP
  * Dell
  * Huawei (E9000 class servers used in OPNFV Community Labs are  IPMI 2.0
  compliant and use Redfish login Interface through Browsers supporting JRE1.7/1.8)

Several test campaigns done with physical Wattmeter showed that IPMI results
were notvery accurate but RedFish were. So if Redfish is available, it is
highly recommended to use it.

Installation
^^^^^^^^^^^^

To run the server power consumption collector agent, you need to deploy a
docker container locally on your infrastructure.

This container requires:

  * Connectivy on the LAN where server administration services (ILO, eDrac,
  IPMI,...) are configured and IP access to the POD's servers
  * Outgoing HTTP access to the Event API (internet)

Build the image by typing::

  curl -s https://raw.githubusercontent.com/bherard/energyrecorder/master/docker/server-collector.dockerfile|docker build -t energyrecorder/collector -

Create local folder on your host for logs and config files::

  mkdir -p /etc/energyrecorder
  mkdir -p /var/log/energyrecorder

In /etc/energyrecorder create a configuration for logging in a file named
collector-logging.conf::

  curl -s https://raw.githubusercontent.com/bherard/energyrecorder/master/server-collector/conf/collector-logging.conf.sample > /etc/energyrecorder/collector-logging.conf

Check configuration for this file (folders, log levels.....)
In /etc/energyrecorder create a configuration for the collector in a file named
collector-settings.yaml::

  curl -s https://raw.githubusercontent.com/bherard/energyrecorder/master/server-collector/conf/collector-settings.yaml.sample > /etc/energyrecorder/collector-settings.yaml

Define the "PODS" section and their "servers" section according to the
environment to monitor.
Note: The "environment" key should correspond to the pod name, as defined in
the "NODE_NAME" environment variable by CI when running.

**IMPORTANT NOTE**: To apply a new configuration, you need to kill the running
container an start a new one (see below)

Run
^^^

To run the container, you have to map folder located on the host to folders in
the container (config, logs)::

  docker run -d --name energy-collector --restart=always -v /etc/energyrecorder:/usr/local/energyrecorder/server-collector/conf -v /var/log/energyrecorder:/var/log/energyrecorder energyrecorder/collector


Energy Recording API
--------------------
An event API to insert contextual information when monitoring energy (e.g.
start Functest, start Tempest, destroy VM, ..)
It is associated with an influxDB to store the power consumption measures
It is hosted on a shared environment with the folling access points:

+------------------------------------+----------------------------------------+
|   Component                        |    Connectivity                        |
+====================================+========================================+
| Energy recording API documentation | http://energy.opnfv.fr/resources/doc/  |
+------------------------------------+----------------------------------------+
| influxDB (data)                    | http://energy.opnfv.fr:8086            |
+------------------------------------+----------------------------------------+

In you need, you can also host your own version of the Energy recording API
(in such case, the Python SDK may requires a settings update)
If you plan to use the default shared API, following steps are not required.

Image creation
^^^^^^^^^^^^^^
First, you need to buid an image::

  curl -s https://raw.githubusercontent.com/bherard/energyrecorder/master/docker/recording-api.dockerfile|docker build -t energyrecorder/api -

Setup
^^^^^
Create local folder on your host for logs and config files::

  mkdir -p /etc/energyrecorder
  mkdir -p /var/log/energyrecorder
  mkdir -p /var/lib/influxdb

In /etc/energyrecorder create a configuration for logging in a file named
webapp-logging.conf::

  curl -s https://raw.githubusercontent.com/bherard/energyrecorder/master/recording-api/conf/webapp-logging.conf.sample > /etc/energyrecorder/webapp-logging.conf

Check configuration for this file (folders, log levels.....)

In /etc/energyrecorder create a configuration for the collector in a file
named webapp-settings.yaml::

  curl -s https://raw.githubusercontent.com/bherard/energyrecorder/master/recording-api/conf/webapp-settings.yaml.sample > /etc/energyrecorder/webapp-settings.yaml

Normaly included configuration is ready to use except username/passwer for
influx (see run-container.sh bellow). Use here the admin user.

**IMPORTANT NOTE**: To apply a new configuration, you need to kill the running
container an start a new one (see bellow)

Run
^^^
To run the container, you have to map folder located on the host to folders in
the container (config, logs)::

  docker run -d --name energyrecorder-api -p 8086:8086 -p 8888:8888  -v /etc/energyrecorder:/usr/local/energyrecorder/web.py/conf -v /var/log/energyrecorder/:/var/log/energyrecorder -v /var/lib/influxdb:/var/lib/influxdb energyrecorder/webapp admin-influx-user-name admin-password readonly-influx-user-name user-password

with

+---------------------------+--------------------------------------------+
| Parameter name            | Description                                |
+===========================+============================================+
| admin-influx-user-name    | Influx user with admin grants to create    |
|---------------------------+--------------------------------------------+
| admin-password            | Influx password to set to admin user       |
|---------------------------+--------------------------------------------+
| readonly-influx-user-name | Influx user with readonly grants to create |
|---------------------------+--------------------------------------------+
| user-password             | Influx password to set to readonly user    |
+---------------------------+--------------------------------------------+

**NOTE**: Local folder /var/lib/influxdb is the location web influx data are
stored. You may used anything else at your convience. Just remember to define
this mapping properly when running the container.

Power consumption Python SDK
----------------------------
a Python SDK - almost not intrusive, based on python decorator to trigger call
to the event API.

It is currently hosted in Functest repo but if other projects adopt it, a
dedicated project could be created and/or it could be hosted in Releng.

How to use the SDK
^^^^^^^^^^^^^^^^^^

import the energy library::

  import functest.energy.energy as energy

Notify that you want power recording in your testcase::

  @energy.enable_recording
  def run(self):
      self.do_some_stuff1()
      self.do_some_stuff2()

If you want to register additional steps during the scenarios you can to it in
2 diffferent way:

  * notify step on method defintion::
    @energy.set_step("step1")
    def do_some_stuff1(self):
    ...
    @energy.set_step("step2")
    def do_some_stuff2(self):
  * directly from code::
    @energy.enable_recording
    def run(self):
      Energy.set_step("step1")
      self.do_some_stuff1()
      ...
      Energy.set_step("step2")
      self.do_some_stuff2()

SDK Setting
^^^^^^^^^^^
Settings delivered in the project git are ready to use and assume that you will
use the sahre energy recording API.
If you want to use an other instance, you have to update the key
"energy_recorder.api_url" in <FUNCTEST>/functest/ci/config_functest.yaml" by
setting the proper hostname/IP

Results
-------
Here is an example of result comming from LF POD2. This sequence represents
several CI runs in a raw. (0 power corresponds to hard reboot of the servers)

You may connect http://energy.opnfv.fr:3000 for more results (ask for
credentials to infra team).

.. figure:: ../../images/energy_LF2.png
   :align: center
   :alt: Energy monitoring of LF POD2