OPNFV Documentation¶

Overall Test Architecture¶

The management of test results can be summarized as follows:

+-------------+    +-------------+    +-------------+
|             |    |             |    |             |
|   Test      |    |   Test      |    |   Test      |
| Project #1  |    | Project #2  |    | Project #N  |
|             |    |             |    |             |
+-------------+    +-------------+    +-------------+
         |               |               |
         V               V               V
     +---------------------------------------------+
     |                                             |
     |           Test Rest API front end           |
     |    http://testresults.opnfv.org/test        |
     |                                             |
     +---------------------------------------------+
         ^                |                     ^
         |                V                     |
         |     +-------------------------+      |
         |     |                         |      |
         |     |    Test Results DB      |      |
         |     |         Mongo DB        |      |
         |     |                         |      |
         |     +-------------------------+      |
         |                                      |
         |                                      |
   +----------------------+        +----------------------+
   |                      |        |                      |
   | Testing Dashboards   |        |  Test Landing page   |
   |                      |        |                      |
   +----------------------+        +----------------------+

The Test Database¶

A Mongo DB Database was introduced for the Brahmaputra release. The following collections are declared in this database:

• pods: the list of pods used for production CI
• projects: the list of projects providing test cases
• test cases: the test cases related to a given project
• results: the results of the test cases
• scenarios: the OPNFV scenarios tested in CI

This database can be used by any project through the Test API. Please note that projects may also use additional databases. The Test Database is mainly use to collect CI test results and generate scenario trust indicators. The Test Database is also cloned for OPNFV Plugfests in order to provide a private datastore only accessible to Plugfest participants.

Test API description¶

The Test API is used to declare pods, projects, test cases and test results. Pods correspond to a cluster of machines (3 controller and 2 compute nodes in HA mode) used to run the tests and are defined in the Pharos project. The results pushed in the database are related to pods, projects and test cases. Trying to push results generated from a non-referenced pod will return an error message by the Test API.

The data model is very basic, 5 objects are available:

• Pods
• Projects
• Test cases
• Results
• Scenarios

For detailed information, please go to http://artifacts.opnfv.org/releng/docs/testapi.html

The code of the Test API is hosted in the releng-testresults repository [TST2]. The static documentation of the Test API can be found at [TST3]. The Test API has been dockerized and may be installed locally in your lab.

The deployment of the Test API has been automated. A jenkins job manages:

• the unit tests of the Test API
• the creation of a new docker file
• the deployment of the new Test API
• the archive of the old Test API
• the backup of the Mongo DB

Test API Authorization¶

PUT/DELETE/POST operations of the TestAPI now require token based authorization. The token needs to be added in the request using a header ‘X-Auth-Token’ for access to the database.

e.g:

headers['X-Auth-Token']

The value of the header i.e the token can be accessed in the jenkins environment variable TestApiToken. The token value is added as a masked password.

headers['X-Auth-Token'] = os.environ.get('TestApiToken')

The above example is in Python. Token based authentication has been added so that only CI pods running Jenkins jobs can access the database. Please note that currently token authorization is implemented but is not yet enabled.

Introduction¶

Power consumption is a key driver for NFV. As an end user is interested to know which application is good or 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:

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.

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

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

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

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

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:

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.

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

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

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

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

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

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.

import functest.energy.energy as energy

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

@energy.set_step("step1")
def do_some_stuff1(self):
...
@energy.set_step("step2")
def do_some_stuff2(self):

@energy.enable_recording
def run(self):
  Energy.set_step("step1")
  self.do_some_stuff1()
  ...
  Energy.set_step("step2")
  self.do_some_stuff2()

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).

Licencing your documentation¶

All contributions to the OPNFV project are done in accordance with the OPNFV licensing requirements. Documentation in OPNFV is contributed in accordance with the Creative Commons 4.0 and the `SPDX https://spdx.org/>`_ licence. All documentation files need to be licensed using the text below. The license may be applied in the first lines of all contributed RST files:

.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. SPDX-License-Identifier: CC-BY-4.0
.. (c) <optionally add copywriters name>

These lines will not be rendered in the html and pdf files.

How and where to store the document content files in your repository¶

All documentation for your project should be structured and stored in the <repo>/docs/ directory. The documentation toolchain will look in these directories and be triggered on events in these directories when generating documents.

Release documentation¶

Release documentation is the set of documents that are published for each OPNFV release. These documents are created and developed following the OPNFV release process and milestones and should reflect the content of the OPNFV release. These documents have a master index.rst file in the <opnfvdocs> repository and extract content from other repositories. To provide content into these documents place your <content>.rst files in a directory in your repository that matches the master document and add a reference to that file in the correct place in the corresponding index.rst file in opnfvdocs/docs/release/.

Platform Overview: opnfvdocs/docs/release/overview

• Note this document is not a contribution driven document
• Content for this is prepared by the Marketing team together with the opnfvdocs team

Installation Instruction: <repo>/docs/release/installation

• Folder for documents describing how to deploy each installer and scenario descriptions
• Release notes will be included here <To Confirm>
• Security related documents will be included here
• Note that this document will be compiled into ‘OPNFV Installation Instruction’

User Guide: <repo>/docs/release/userguide

• Folder for manuals to use specific features
• Folder for documents describing how to install/configure project specific components and features
• Can be the directory where API reference for project specific features are stored
• Note this document will be compiled into ‘OPNFV userguide’

Configuration Guide: <repo>/docs/release/configguide

• Brief introduction to configure OPNFV with its dependencies.

Release Notes: <repo>/docs/release/release-notes

• Changes brought about in the release cycle.
• Include version details.

Testing documentation¶

Documentation created by test projects can be stored under two different sub directories /user or /developemnt. Release notes will be stored under <repo>/docs/release/release-notes

User documentation: <repo>/testing/user/ Will collect the documentation of the test projects allowing the end user to perform testing towards a OPNFV SUT e.g. Functest/Yardstick/Vsperf/Storperf/Bottlenecks/Qtip installation/config & user guides.

Development documentation: <repo>/testing/developent/ Will collect documentation to explain how to create your own test case and leverage existing testing frameworks e.g. developer guides.

Development Documentation¶

Project specific documents such as design documentation, project overview or requirement documentation can be stored under /docs/development. Links to generated documents will be dislayed under Development Documentaiton section on docs.opnfv.org. You are encouraged to establish the following basic structure for your project as needed:

Requirement Documentation: <repo>/docs/development/requirements/

• Folder for your requirement documentation
• For details on requirements projects’ structures see the Requirements Projects page.

Design Documentation: <repo>/docs/development/design

• Folder for your upstream design documents (blueprints, development proposals, etc..)

Project overview: <repo>/docs/development/overview

• Folder for any project specific documentation.

Infrastructure Documentation¶

Infrastructure documentation can be stored under <repo>/docs/ folder of corresponding infrastructure project.

In toctree¶

To import project documents from project repositories, we use submodules.

Each project is stored in opnfvdocs/docs/submodule/ as follows:

To include your project specific documentation in the composite documentation, first identify where your project documentation should be included. Say your project userguide should figure in the ‘OPNFV Userguide’, then:

vim opnfvdocs/docs/release/userguide.introduction.rst

This opens the text editor. Identify where you want to add the userguide. If the userguide is to be added to the toctree, simply include the path to it, example:

.. toctree::
    :maxdepth: 1

 submodules/functest/docs/userguide/index
 submodules/bottlenecks/docs/userguide/index
 submodules/yardstick/docs/userguide/index
 <submodules/path-to-your-file>

As Hyperlink¶

It’s pretty common to want to reference another location in the OPNFV documentation and it’s pretty easy to do with reStructuredText. This is a quick primer, more information is in the Sphinx section on Cross-referencing arbitrary locations.

Within a single document, you can reference another section simply by:

This is a reference to `The title of a section`_

Assuming that somewhere else in the same file there a is a section title something like:

The title of a section
^^^^^^^^^^^^^^^^^^^^^^

It’s typically better to use :ref: syntax and labels to provide links as they work across files and are resilient to sections being renamed. First, you need to create a label something like:

.. _a-label:

The title of a section
^^^^^^^^^^^^^^^^^^^^^^

Then you can reference the section anywhere by simply doing:

This is a reference to :ref:`a-label`

or:

This is a reference to :ref:`a section I really liked <a-label>`

Because the labels have to be unique, it usually makes sense to prefix the labels with the project name to help share the label space, e.g., sfc-user-guide instead of just user-guide.

Once you have made these changes you need to push the patch back to the opnfvdocs team for review and integration.

git add .
git commit --signoff --all
git review

Be sure to add the project leader of the opnfvdocs project as a reviewer of the change you just pushed in gerrit.

Composite OPNFVDOCS documentation¶

To build whole documentation under opnfvdocs/, follow these steps:

Install virtual environment.

sudo pip install virtualenv
cd /local/repo/path/to/project

Download the OPNFVDOCS repository.

git clone https://gerrit.opnfv.org/gerrit/opnfvdocs

Change directory to opnfvdocs & install requirements.

cd opnfvdocs
sudo pip install -r etc/requirements.txt

Update submodules, build documentation using tox & then open using any browser.

cd opnfvdocs
git submodule update --init
tox -edocs
firefox docs/_build/html/index.html

Individual project documentation¶

To test how the documentation renders in HTML, follow these steps:

Install virtual environment.

sudo pip install virtualenv
cd /local/repo/path/to/project

Download the opnfvdocs repository.

git clone https://gerrit.opnfv.org/gerrit/opnfvdocs

Change directory to opnfvdocs & install requirements.

cd opnfvdocs
sudo pip install -r etc/requirements.txt

Move the conf.py file to your project folder where RST files have been kept:

mv opnfvdocs/docs/conf.py <path-to-your-folder>/

Move the static files to your project folder:

mv opnfvdocs/_static/ <path-to-your-folder>/

Build the documentation from within your project folder:

sphinx-build -b html <path-to-your-folder> <path-to-output-folder>

Your documentation shall be built as HTML inside the specified output folder directory.

Adding a Local Build¶

In your project repo:

1. Add the following files:

   docs/conf.py

   from docs_conf.conf import *  # noqa: F401,F403
   

   docs/conf.yaml

   ---
   project_cfg: opnfv
   project: Example
   

   docs/requirements.txt

   lfdocs-conf
   sphinx_opnfv_theme
   # Uncomment the following line if your project uses Sphinx to document
   # HTTP APIs
   # sphinxcontrib-httpdomain
   

   tox.ini

   [tox]
   minversion = 1.6
   envlist =
       docs,
       docs-linkcheck
   skipsdist = true
   
   [testenv:docs]
   deps = -rdocs/requirements.txt
   commands =
       sphinx-build -b html -n -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html
       echo "Generated docs available in {toxinidir}/docs/_build/html"
   whitelist_externals = echo
   
   [testenv:docs-linkcheck]
   deps = -rdocs/requirements.txt
   commands = sphinx-build -b linkcheck -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck
   

   .gitignore

   .tox/ docs/_build/*

   docs/index.rst

   If this file doesn’t exist, it will need to be created along any other missing index file for directories (release, development). Any example of the file’s content looks like this:

   .. 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
   
   .. _<project-name>:
   
   ==============
   <project-name>
   ==============
   
   .. toctree::
      :numbered:
      :maxdepth: 2
   
      release/release-notes/index
      release/installation/index
      release/userguide/index
      scenarios/index
   

You can verify the build works by running:

tox -e docs

Creating a CI Job¶

In the releng repository:

1. Update your project’s job file jjb/<project>/<projects-jobs.yaml with the following (taken from this guide):

   ---
   - project:
       name: PROJECT
       project: PROJECT
       project-name: 'PROJECT'
   
       project-pattern: 'PROJECT'
       rtd-build-url: RTD_BUILD_URL
       rtd-token: RTD_TOKEN
   
       jobs:
         - '{project-name}-rtd-jobs'
   

You can either send an email to helpdesk in order to get a copy of RTD_BUILD_URL and RTD_TOKEN, ping aricg or bramwelt in #opnfv-docs on Freenode, or add Aric Gardner or Trevor Bramwell to your patch as a reviewer and they will pass along the token and build URL.

Removing the Submodule¶

In the opnfvdocs repository:

1. Add an intersphinx link to the opnfvdocs repo configuration:

   docs/conf.py

   intersphinx_mapping['<project>'] = ('http://opnfv-<project>.readthedocs.io', None)
   

   If the project exists on ReadTheDocs, and the previous build was merged in and ran, you can verify the linking is working currectly by finding the following line in the output of tox -e docs:

   loading intersphinx inventory from https://opnfv-<project>.readthedocs.io/en/latest/objects.inv...
   

2. Ensure all references in opnfvdocs are using :ref: or :doc: and not directly specifying submodule files with ../submodules/<project>.

   For example:

   .. toctree::
   
      ../submodules/releng/docs/overview.rst
   

   Would become:

   .. toctree::
   
      :ref:`Releng Overview <releng:overview>`
   

   Some more examples can be seen here.

3. Remove the submodule from opnfvdocs, replacing <project> with your project and commit the change:

   git rm docs/submodules/<project>
   git commit -s
   git review
   

Verify Job¶

The verify job name is docs-verify-rtd-{branch}.

When you send document changes to gerrit, jenkins will create your documents in HTML formats (normal and single-page) to verify that new document can be built successfully. Please check the jenkins log and artifact carefully. You can improve your document even though if the build job succeeded.

Merge Job¶

The merge job name is docs-merge-rtd-{branch}.

Once the patch is merged, jenkins will automatically trigger building of the new documentation. This might take about 15 minutes while readthedocs builds the documentatation. The newly built documentation shall show up as appropriate placed in docs.opnfv.org/{branch}/path-to-file.