summaryrefslogtreecommitdiffstats
path: root/docs/userguide/yardstick.rst
diff options
context:
space:
mode:
authorTrevor Cooper <trevor.cooper@intel.com>2017-03-22 14:04:38 -0700
committerTrevor Cooper <trevor.cooper@intel.com>2017-03-22 14:04:38 -0700
commit5bc3a7f072674902f9fbdc59ddc36f44b4c87cca (patch)
tree7676941d206af68bab9d20a4570ced6dc9c4629a /docs/userguide/yardstick.rst
parentac5b51c16eec6bd6c2b2dd68ca0a5240d9e858f2 (diff)
Moved userguide to user directory
Change-Id: I35f2cbbab8ce7daec26fed63fa92cf7c17cd37b3 Signed-off-by: Trevor Cooper <trevor.cooper@intel.com>
Diffstat (limited to 'docs/userguide/yardstick.rst')
-rw-r--r--docs/userguide/yardstick.rst250
1 files changed, 0 insertions, 250 deletions
diff --git a/docs/userguide/yardstick.rst b/docs/userguide/yardstick.rst
deleted file mode 100644
index b5e5c72d..00000000
--- a/docs/userguide/yardstick.rst
+++ /dev/null
@@ -1,250 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-.. (c) OPNFV, Intel Corporation, AT&T and others.
-
-Execution of vswitchperf testcases by Yardstick
------------------------------------------------
-
-General
-^^^^^^^
-
-Yardstick is a generic framework for a test execution, which is used for
-validation of installation of OPNFV platform. In the future, Yardstick will
-support two options of vswitchperf testcase execution:
-
-- plugin mode, which will execute native vswitchperf testcases; Tests will
- be executed natively by vsperf, and test results will be processed and
- reported by yardstick.
-- traffic generator mode, which will run vswitchperf in **trafficgen**
- mode only; Yardstick framework will be used to launch VNFs and to configure
- flows to ensure, that traffic is properly routed. This mode will allow to
- test OVS performance in real world scenarios.
-
-In Colorado release only the traffic generator mode is supported.
-
-Yardstick Installation
-^^^^^^^^^^^^^^^^^^^^^^
-
-In order to run Yardstick testcases, you will need to prepare your test
-environment. Please follow the `installation instructions
-<http://artifacts.opnfv.org/yardstick/docs/user_guides_framework/index.html>`__
-to install the yardstick.
-
-Please note, that yardstick uses OpenStack for execution of testcases.
-OpenStack must be installed with Heat and Neutron services. Otherwise
-vswitchperf testcases cannot be executed.
-
-VM image with vswitchperf
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-A special VM image is required for execution of vswitchperf specific testcases
-by yardstick. It is possible to use a sample VM image available at OPNFV
-artifactory or to build customized image.
-
-Sample VM image with vswitchperf
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Sample VM image is available at vswitchperf section of OPNFV artifactory
-for free download:
-
-.. code-block:: console
-
- $ wget http://artifacts.opnfv.org/vswitchperf/vnf/vsperf-yardstick-image.qcow2
-
-This image can be used for execution of sample testcases with dummy traffic
-generator.
-
-**NOTE:** Traffic generators might require an installation of client software.
-This software is not included in the sample image and must be installed by user.
-
-**NOTE:** This image will be updated only in case, that new features related
-to yardstick integration will be added to the vswitchperf.
-
-Preparation of custom VM image
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In general, any Linux distribution supported by vswitchperf can be used as
-a base image for vswitchperf. One of the possibilities is to modify vloop-vnf
-image, which can be downloaded from `<http://artifacts.opnfv.org/vswitchperf.html/>`__
-(see :ref:`vloop-vnf`).
-
-Please follow the :ref:`vsperf-installation` to
-install vswitchperf inside vloop-vnf image. As vswitchperf will be run in
-trafficgen mode, it is possible to skip installation and compilation of OVS,
-QEMU and DPDK to keep image size smaller.
-
-In case, that selected traffic generator requires installation of additional
-client software, please follow appropriate documentation. For example in case
-of IXIA, you would need to install IxOS and IxNetowrk TCL API.
-
-VM image usage
-~~~~~~~~~~~~~~
-
-Image with vswitchperf must be uploaded into the glance service and
-vswitchperf specific flavor configured, e.g.:
-
-.. code-block:: console
-
- $ glance --os-username admin --os-image-api-version 1 image-create --name \
- vsperf --is-public true --disk-format qcow2 --container-format bare --file \
- vsperf-yardstick-image.qcow2
-
- $ nova --os-username admin flavor-create vsperf-flavor 100 2048 25 1
-
-Testcase execution
-^^^^^^^^^^^^^^^^^^
-
-After installation, yardstick is available as python package within yardstick
-specific virtual environment. It means, that yardstick environment must be
-enabled before the test execution, e.g.:
-
-.. code-block:: console
-
- source ~/yardstick_venv/bin/activate
-
-
-Next step is configuration of OpenStack environment, e.g. in case of devstack:
-
-.. code-block:: console
-
- source /opt/openstack/devstack/openrc
- export EXTERNAL_NETWORK=public
-
-Vswitchperf testcases executable by yardstick are located at vswitchperf
-repository inside ``yardstick/tests`` directory. Example of their download
-and execution follows:
-
-.. code-block:: console
-
- git clone https://gerrit.opnfv.org/gerrit/vswitchperf
- cd vswitchperf
-
- yardstick -d task start yardstick/tests/rfc2544_throughput_dummy.yaml
-
-**NOTE:** Optional argument ``-d`` shows debug output.
-
-Testcase customization
-^^^^^^^^^^^^^^^^^^^^^^
-
-Yardstick testcases are described by YAML files. vswitchperf specific testcases
-are part of the vswitchperf repository and their yaml files can be found at
-``yardstick/tests`` directory. For detailed description of yaml file structure,
-please see yardstick documentation and testcase samples. Only vswitchperf specific
-parts will be discussed here.
-
-Example of yaml file:
-
-.. code-block:: yaml
-
- ...
- scenarios:
- -
- type: Vsperf
- options:
- testname: 'p2p_rfc2544_throughput'
- trafficgen_port1: 'eth1'
- trafficgen_port2: 'eth3'
- external_bridge: 'br-ex'
- test_params: 'TRAFFICGEN_DURATION=30;TRAFFIC={'traffic_type':'rfc2544_throughput}'
- conf_file: '~/vsperf-yardstick.conf'
-
- host: vsperf.demo
-
- runner:
- type: Sequence
- scenario_option_name: frame_size
- sequence:
- - 64
- - 128
- - 512
- - 1024
- - 1518
- sla:
- metrics: 'throughput_rx_fps'
- throughput_rx_fps: 500000
- action: monitor
-
- context:
- ...
-
-Section option
-~~~~~~~~~~~~~~
-
-Section **option** defines details of vswitchperf test scenario. Lot of options
-are identical to the vswitchperf parameters passed through ``--test-params``
-argument. Following options are supported:
-
-- **frame_size** - a packet size for which test should be executed;
- Multiple packet sizes can be tested by modification of Sequence runner
- section inside YAML definition. Default: '64'
-- **conf_file** - sets path to the vswitchperf configuration file, which will be
- uploaded to VM; Default: '~/vsperf-yardstick.conf'
-- **setup_script** - sets path to the setup script, which will be executed
- during setup and teardown phases
-- **trafficgen_port1** - specifies device name of 1st interface connected to
- the trafficgen
-- **trafficgen_port2** - specifies device name of 2nd interface connected to
- the trafficgen
-- **external_bridge** - specifies name of external bridge configured in OVS;
- Default: 'br-ex'
-- **test_params** - specifies a string with a list of vsperf configuration
- parameters, which will be passed to the ``--test-params`` CLI argument;
- Parameters should be stated in the form of ``param=value`` and separated
- by a semicolon. Configuration of traffic generator is driven by ``TRAFFIC``
- dictionary, which can be also updated by values defined by ``test_params``.
- Please check VSPERF documentation for details about available configuration
- parameters and their data types.
- In case that both **test_params** and **conf_file** are specified,
- then values from **test_params** will override values defined
- in the configuration file.
-
-In case that **trafficgen_port1** and/or **trafficgen_port2** are defined, then
-these interfaces will be inserted into the **external_bridge** of OVS. It is
-expected, that OVS runs at the same node, where the testcase is executed. In case
-of more complex OpenStack installation or a need of additional OVS configuration,
-**setup_script** can be used.
-
-**NOTE** It is essential to specify a configuration for selected traffic generator.
-In case, that standalone testcase is created, then traffic generator can be
-selected and configured directly in YAML file by **test_params**. On the other
-hand, if multiple testcases should be executed with the same traffic generator
-settings, then a customized configuration file should be prepared and its name
-passed by **conf_file** option.
-
-Section runner
-~~~~~~~~~~~~~~
-
-Yardstick supports several `runner types
-<http://artifacts.opnfv.org/yardstick/docs/userguide/architecture.html#runner-types>`__.
-In case of vswitchperf specific TCs, **Sequence** runner type can be used to
-execute the testcase for given list of frame sizes.
-
-
-Section sla
-~~~~~~~~~~~
-
-In case that sla section is not defined, then testcase will be always
-considered as successful. On the other hand, it is possible to define a set of
-test metrics and their minimal values to evaluate test success. Any numeric
-value, reported by vswitchperf inside CSV result file, can be used.
-Multiple metrics can be defined as a coma separated list of items. Minimal
-value must be set separately for each metric.
-
-e.g.:
-
-.. code-block:: yaml
-
- sla:
- metrics: 'throughput_rx_fps,throughput_rx_mbps'
- throughput_rx_fps: 500000
- throughput_rx_mbps: 1000
-
-In case that any of defined metrics will be lower than defined value, then
-testcase will be marked as failed. Based on ``action`` policy, yardstick
-will either stop test execution (value ``assert``) or it will run next test
-(value ``monitor``).
-
-**NOTE** The throughput SLA (or any other SLA) cannot be set to a meaningful
-value without knowledge of the server and networking environment, possibly
-including prior testing in that environment to establish a baseline SLA level
-under well-understood circumstances.