diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/conf.py | 1 | ||||
| -rw-r--r-- | docs/conf.yaml | 3 | ||||
| -rw-r--r-- | docs/index.rst | 17 | ||||
| -rw-r--r-- | docs/release/release-notes/release-notes.rst | 4 | ||||
| -rw-r--r-- | docs/requirements.txt | 5 | ||||
| -rwxr-xr-x | docs/testing/developer/devguide/devguide.rst | 140 | ||||
| -rw-r--r-- | docs/testing/user/userguide/04-installation.rst | 109 | ||||
| -rw-r--r-- | docs/testing/user/userguide/13-nsb-installation.rst | 4 | ||||
| -rw-r--r-- | docs/testing/user/userguide/14-nsb-operation.rst | 8 | ||||
| -rw-r--r-- | docs/testing/user/userguide/glossary.rst | 75 |
10 files changed, 347 insertions, 19 deletions
diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 000000000..86fddf13e --- /dev/null +++ b/docs/conf.py @@ -0,0 +1 @@ +from docs_conf.conf import * # pylint: disable=wildcard-import diff --git a/docs/conf.yaml b/docs/conf.yaml new file mode 100644 index 000000000..01e08ec7f --- /dev/null +++ b/docs/conf.yaml @@ -0,0 +1,3 @@ +--- +project_cfg: opnfv +project: Yardstick diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 000000000..e1339b0dd --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,17 @@ +.. 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 + +.. _yardstick: + +========= +Yardstick +========= + +.. toctree:: + :numbered: + :maxdepth: 2 + + release/release-notes/index + testing/user/userguide/index + testing/developer/devguide/index diff --git a/docs/release/release-notes/release-notes.rst b/docs/release/release-notes/release-notes.rst index daa4b8187..745db4470 100644 --- a/docs/release/release-notes/release-notes.rst +++ b/docs/release/release-notes/release-notes.rst @@ -149,9 +149,9 @@ Deliverables Documents --------- - - User Guide: http://docs.opnfv.org/en/stable-fraser/submodules/yardstick/docs/testing/user/userguide/index.html + - User Guide: :ref:`<yardstick-userguide>` - - Developer Guide: http://docs.opnfv.org/en/stable-fraser/submodules/yardstick/docs/testing/developer/devguide/index.html + - Developer Guide: :ref:`<yardstick-devguide>` Software Deliverables diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 000000000..440843584 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,5 @@ +lfdocs-conf +sphinx_opnfv_theme +# Uncomment the following line if your project uses Sphinx to document +# HTTP APIs +# sphinxcontrib-httpdomain diff --git a/docs/testing/developer/devguide/devguide.rst b/docs/testing/developer/devguide/devguide.rst index 91f2c2148..4fe01c12b 100755 --- a/docs/testing/developer/devguide/devguide.rst +++ b/docs/testing/developer/devguide/devguide.rst @@ -449,6 +449,10 @@ Verify your patch:: It is used in CI but also by the CLI. +For more details on ``tox`` and tests, please refer to the `Running tests`_ +and `working with tox`_ sections below, which describe the different available +environments. + Submit the code with Git ++++++++++++++++++++++++ @@ -566,6 +570,142 @@ The process for backporting is as follows: A backported change needs a ``+1`` and a ``+2`` from a committer who didn’t propose the change (i.e. minimum 3 people involved). +Development guidelines +---------------------- +This section provides guidelines and best practices for feature development +and bug fixing in Yardstick. + +In general, bug fixes should be submitted as a single patch. + +When developing larger features, all commits on the local topic branch can be +submitted together, by running ``git review`` on the tip of the branch. This +creates a chain of related patches in gerrit. + +Each commit should contain one logical change and the author should aim for no +more than 300 lines of code per commit. This helps to make the changes easier +to review. + +Each feature should have the following: + +* Feature/bug fix code +* Unit tests (both positive and negative) +* Functional tests (optional) +* Sample testcases (if applicable) +* Documentation +* Update to release notes + +Coding style +~~~~~~~~~~~~ +.. _`OpenStack Style Guidelines`: https://docs.openstack.org/hacking/latest/user/hacking.html +.. _`OPNFV coding guidelines`: https://wiki.opnfv.org/display/DEV/Contribution+Guidelines + +Please follow the `OpenStack Style Guidelines`_ for code contributions (the +section on Internationalization (i18n) Strings is not applicable). + +When writing commit message, the `OPNFV coding guidelines`_ on git commit +message style should also be used. + +Running tests +~~~~~~~~~~~~~ +Once your patch has been submitted, a number of tests will be run by Jenkins +CI to verify the patch. Before submitting your patch, you should run these +tests locally. You can do this using ``tox``, which has a number of different +test environments defined in ``tox.ini``. +Calling ``tox`` without any additional arguments runs the default set of +tests (unit tests, functional tests, coverage and pylint). + +If some tests are failing, you can save time and select test environments +individually, by passing one or more of the following command-line options to +``tox``: + +* ``-e py27``: Unit tests using Python 2.7 +* ``-e py3``: Unit tests using Python 3 +* ``-e pep8``: Linter and style checks on updated files +* ``-e functional``: Functional tests using Python 2.7 +* ``-e functional-py3``: Functional tests using Python 3 +* ``-e coverage``: Code coverage checks + +.. note:: You need to stage your changes prior to running coverage for those + changes to be checked. + +In addition to the tests run by Jenkins (listed above), there are a number of +other test environments defined. + +* ``-e pep8-full``: Linter and style checks are run on the whole repo (not + just on updated files) +* ``-e os-requirements``: Check that the requirements are compatible with + OpenStack requirements. + +Working with tox +++++++++++++++++ +.. _virtualenv: https://virtualenv.pypa.io/en/stable/ + +``tox`` uses `virtualenv`_ to create isolated Python environments to run the +tests in. The test environments are located at +``.tox/<environment_name>`` e.g. ``.tox/py27``. + +If requirements are changed, you will need to recreate the tox test +environment to make sure the new requirements are installed. This is done by +passing the additional ``-r`` command-line option to ``tox``:: + + tox -r -e ... + +This can also be achieved by deleting the test environments manually before +running ``tox``:: + + rm -rf .tox/<environment_name> + rm -rf .tox/py27 + +Writing unit tests +~~~~~~~~~~~~~~~~~~ +For each change submitted, a set of unit tests should be submitted, which +should include both positive and negative testing. + +In order to help identify which tests are needed, follow the guidelines below. + +* In general, there should be a separate test for each branching point, return + value and input set. +* Negative tests should be written to make sure exceptions are raised and/or + handled appropriately. + +The following convention should be used for naming tests:: + + test_<method_name>_<some_comment> + +The comment gives more information on the nature of the test, the side effect +being checked, or the parameter being modified:: + + test_my_method_runtime_error + test_my_method_invalid_credentials + test_my_method_param1_none + +Mocking ++++++++ +The ``mock`` library is used for unit testing to stub out external libraries. + +The following conventions are used in Yardstick: + +* Use ``mock.patch.object`` instead of ``mock.patch``. + +* When naming mocked classes/functions, use ``mock_<class_and_function_name>`` + e.g. ``mock_subprocess_call`` + +* Avoid decorating classes with mocks. Apply the mocking in ``setUp()``:: + + @mock.patch.object(ssh, 'SSH') + class MyClassTestCase(unittest.TestCase): + + should be:: + + class MyClassTestCase(unittest.TestCase): + def setUp(self): + self._mock_ssh = mock.patch.object(ssh, 'SSH') + self.mock_ssh = self._mock_ssh.start() + + self.addCleanup(self._stop_mocks) + + def _stop_mocks(self): + self._mock_ssh.stop() Plugins ------- diff --git a/docs/testing/user/userguide/04-installation.rst b/docs/testing/user/userguide/04-installation.rst index a4846230e..d97078909 100644 --- a/docs/testing/user/userguide/04-installation.rst +++ b/docs/testing/user/userguide/04-installation.rst @@ -444,6 +444,115 @@ These configuration files can be found in the ``samples`` directory. Default location for the output is ``/tmp/yardstick.out``. +Automatic installation of Yardstick using ansible +------------------------------------------------- + +Automatic installation can be used as an alternative to the manual. +Yardstick can be installed on the bare metal and to the container. Yardstick +container can be either pulled or built. + +Bare metal installation +^^^^^^^^^^^^^^^^^^^^^^^ + +Use ansible script ``install.yaml`` to install Yardstick on Ubuntu server: + +.. code-block:: console + + ansible-playbook -i install-inventory.ini install.yaml \ + -e YARDSTICK_DIR=<path to Yardstick folder> + +.. note:: By default ``INSTALLATION_MODE`` is ``baremetal``. + +.. note:: By default Ubuntu 16.04 is chosen (xenial). It can be changed to + Ubuntu 18.04 (bionic) by passing ``-e OS_RELEASE=bionic`` parameter. + +.. note:: To install Yardstick in virtual environment pass parameter + ``-e VIRTUAL_ENVIRONMENT=True``. + +To build Yardstick NSB image pass ``IMG_PROPERTY=nsb`` as input parameter: + +.. code-block:: console + + ansible-playbook -i install-inventory.ini install.yaml \ + -e IMAGE_PROPERTY=nsb \ + -e YARDSTICK_DIR=<path to Yardstick folder> + +.. note:: In this ``INSTALLATION_MODE`` mode either Yardstick image or SampleVNF + images will be built. Image type is defined by parameter ``IMAGE_PROPERTY``. + By default Yardstick image will be built. + +Container installation +^^^^^^^^^^^^^^^^^^^^^^ + +Use ansible script ``install.yaml`` to pull or build Yardstick +container. To pull Yardstick image and start container run: + +.. code-block:: console + + ansible-playbook -i install-inventory.ini install.yaml \ + -e YARDSTICK_DIR=<path to Yardstick folder> \ + -e INSTALLATION_MODE=container_pull + +.. note:: In this ``INSTALLATION_MODE`` mode either Yardstick image or SampleVNF + images will be built. Image type is defined by variable ``IMG_PROPERTY`` in + file ``ansible/group_vars/all.yml``. By default Yardstick image will be + built. + +.. note:: Open question: How to know if Docker image is built on Ubuntu 16.04 and 18.04? + Do we need separate tag to be used? + +To build Yardstick image run: + +.. code-block:: console + + ansible-playbook -i install-inventory.ini install.yaml \ + -e YARDSTICK_DIR=<path to Yardstick folder> \ + -e INSTALLATION_MODE=container + +.. note:: In this ``INSTALLATION_MODE`` mode neither Yardstick image nor SampleVNF + image will be built. + +.. note:: By default Ubuntu 16.04 is chosen (xenial). It can be changed to + Ubuntu 18.04 (bionic) by passing ``-e OS_RELEASE=bionic`` parameter. + +Parameters for ``install.yaml`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Description of the parameters used with ``install.yaml`` script + + +-------------------------+-------------------------------------------------+ + | Parameters | Detail | + +=========================+=================================================+ + | -i install-inventory.ini| Installs package dependency to remote servers | + | | Mandatory parameter | + | | By default no remote servers are provided | + | | Needed packages will be installed on localhost | + +-------------------------+-------------------------------------------------+ + | -e YARDSTICK_DIR | Path to Yardstick folder | + | | Mandatory parameter | + +-------------------------+-------------------------------------------------+ + | -e INSTALLATION_MODE | baremetal: Yardstick is installed to the bare | + | | metal | + | | Default parameter | + | +-------------------------------------------------+ + | | container: Yardstick is installed in container | + | | Container is built from Dockerfile | + | +-------------------------------------------------+ + | | container_pull: Yardstick is installed in | + | | container | + | | Container is pulled from docker hub | + +-------------------------+-------------------------------------------------+ + | -e OS_RELEASE | xenial or bionic: Ubuntu version to be used | + | | Default is Ubuntu 16.04 (xenial) | + +-------------------------+-------------------------------------------------+ + | -e IMAGE_PROPERTY | normal or nsb: Type of the VM image to be built | + | | Default image is Yardstick | + +-------------------------+-------------------------------------------------+ + | -e VIRTUAL_ENVIRONMENT | False or True: Whether install in virtualenv | + | | Default is False | + +-------------------------+-------------------------------------------------+ + + Deploy InfluxDB and Grafana using Docker ---------------------------------------- diff --git a/docs/testing/user/userguide/13-nsb-installation.rst b/docs/testing/user/userguide/13-nsb-installation.rst index fb68fbf21..0b76cdd30 100644 --- a/docs/testing/user/userguide/13-nsb-installation.rst +++ b/docs/testing/user/userguide/13-nsb-installation.rst @@ -168,6 +168,10 @@ It will also automatically download all the packages needed for NSB Testing setup. Refer chapter :doc:`04-installation` for more on docker **Install Yardstick using Docker (recommended)** +Another way to execute an installation for a Bare-Metal or a Standalone context +is to use ansible script ``install.yaml``. Refer chapter :doc:`04-installation` +for more details. + System Topology: ================ diff --git a/docs/testing/user/userguide/14-nsb-operation.rst b/docs/testing/user/userguide/14-nsb-operation.rst index a5f3a0cf6..adefe2f18 100644 --- a/docs/testing/user/userguide/14-nsb-operation.rst +++ b/docs/testing/user/userguide/14-nsb-operation.rst @@ -256,7 +256,7 @@ to the VNF. An example scale-up Heat testcase is: -.. literalinclude:: /submodules/yardstick/samples/vnf_samples/nsut/vfw/tc_heat_rfc2544_ipv4_1rule_1flow_64B_trex_scale-up.yaml +.. literalinclude:: /samples/vnf_samples/nsut/vfw/tc_heat_rfc2544_ipv4_1rule_1flow_64B_trex_scale-up.yaml :language: yaml This testcase template requires specifying the number of VCPUs, Memory and Ports. @@ -271,7 +271,7 @@ In order to support ports scale-up, traffic and topology templates need to be us A example topology template is: -.. literalinclude:: /submodules/yardstick/samples/vnf_samples/nsut/vfw/vfw-tg-topology-scale-up.yaml +.. literalinclude:: /samples/vnf_samples/nsut/vfw/vfw-tg-topology-scale-up.yaml :language: yaml This template has ``vports`` as an argument. To pass this argument it needs to @@ -293,7 +293,7 @@ For example: A example traffic profile template is: -.. literalinclude:: /submodules/yardstick/samples/vnf_samples/traffic_profiles/ipv4_throughput-scale-up.yaml +.. literalinclude:: /samples/vnf_samples/traffic_profiles/ipv4_throughput-scale-up.yaml :language: yaml There is an option to provide predefined config for SampleVNFs. Path to config @@ -457,5 +457,5 @@ Sample test case file 4. Modify ``networks/phy_port`` accordingly to the baremetal setup. 5. Run test from: -.. literalinclude:: /submodules/yardstick/samples/vnf_samples/nsut/acl/tc_ovs_rfc2544_ipv4_1rule_1flow_64B_trex.yaml +.. literalinclude:: /samples/vnf_samples/nsut/acl/tc_ovs_rfc2544_ipv4_1rule_1flow_64B_trex.yaml :language: yaml diff --git a/docs/testing/user/userguide/glossary.rst b/docs/testing/user/userguide/glossary.rst index be98aa6c0..6a153943c 100644 --- a/docs/testing/user/userguide/glossary.rst +++ b/docs/testing/user/userguide/glossary.rst @@ -13,6 +13,11 @@ Glossary API Application Programming Interface + Docker + Docker provisions and manages containers. Yardstick and many other OPNFV + projects are deployed in containers. Docker is required to launch the + containerized versions of these projects. + DPI Deep Packet Inspection @@ -27,36 +32,80 @@ Glossary IOPS Input/Output Operations Per Second + A performance measurement used to benchmark storage devices. + + KPI + Key Performance Indicator + + Kubernetes + k8s + Kubernetes is an open-source container-orchestration system for automating + deployment, scaling and management of containerized applications. + It is one of the contexts supported in Yardstick. + + NFV + Network Function Virtualization + NFV is an initiative to take network services which were traditionally run + on proprietary, dedicated hardware, and virtualize them to run on general + purpose hardware. + + NFVI + Network Function Virtualization Infrastructure + The servers, routers, switches, etc on which the NFV system runs. NIC Network Interface Controller + OpenStack + OpenStack is a cloud operating system that controls pools of compute, + storage, and networking resources. OpenStack is an open source project + licensed under the Apache License 2.0. + PBFS Packet Based per Flow State + PROX + Packet pROcessing eXecution engine + QoS Quality of Service + The ability to guarantee certain network or storage requirements to + satisfy a Service Level Agreement (SLA) between an application provider + and end users. + Typically includes performance requirements like networking bandwidth, + latency, jitter correction, and reliability as well as storage + performance in Input/Output Operations Per Second (IOPS), throttling + agreements, and performance expectations at peak load + + SLA + Service Level Agreement + An SLA is an agreement between a service provider and a customer to + provide a certain level of service/performance. + + SR-IOV + Single Root IO Virtualization + A specification that, when implemented by a physical PCIe + device, enables it to appear as multiple separate PCIe devices. This + enables multiple virtualized guests to share direct access to the + physical device. + + SUT + System Under Test + + ToS + Type of Service VLAN - Virtual LAN + Virtual LAN (Local Area Network) VM Virtual Machine + An operating system instance that runs on top of a hypervisor. + Multiple VMs can run at the same time on the same physical + host. VNF Virtual Network Function VNFC Virtual Network Function Component - - NFVI - Network Function Virtualization Infrastructure - - SR-IOV - Single Root IO Virtualization - - SUT - System Under Test - - ToS - Type of Service |