docs/testing/user/userguide/yardstick.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) OPNFV, Intel Corporation, AT&T and others.
   4
   5 Execution of vswitchperf testcases by Yardstick
   6 -----------------------------------------------
   7
   8 General
   9 ^^^^^^^
  10
  11 Yardstick is a generic framework for a test execution, which is used for
  12 validation of installation of OPNFV platform. In the future, Yardstick will
  13 support two options of vswitchperf testcase execution:
  14
  15 - plugin mode, which will execute native vswitchperf testcases; Tests will
  16   be executed natively by vsperf, and test results will be processed and
  17   reported by yardstick.
  18 - traffic generator mode, which will run vswitchperf in **trafficgen**
  19   mode only; Yardstick framework will be used to launch VNFs and to configure
  20   flows to ensure, that traffic is properly routed. This mode will allow to
  21   test OVS performance in real world scenarios.
  22
  23 In Colorado release only the traffic generator mode is supported.
  24
  25 Yardstick Installation
  26 ^^^^^^^^^^^^^^^^^^^^^^
  27
  28 In order to run Yardstick testcases, you will need to prepare your test
  29 environment. Please follow the `installation instructions
  30 <http://artifacts.opnfv.org/yardstick/docs/user_guides_framework/index.html>`__
  31 to install the yardstick.
  32
  33 Please note, that yardstick uses OpenStack for execution of testcases.
  34 OpenStack must be installed with Heat and Neutron services. Otherwise
  35 vswitchperf testcases cannot be executed.
  36
  37 VM image with vswitchperf
  38 ^^^^^^^^^^^^^^^^^^^^^^^^^
  39
  40 A special VM image is required for execution of vswitchperf specific testcases
  41 by yardstick. It is possible to use a sample VM image available at OPNFV
  42 artifactory or to build customized image.
  43
  44 Sample VM image with vswitchperf
  45 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  46
  47 Sample VM image is available at vswitchperf section of OPNFV artifactory
  48 for free download:
  49
  50 .. code-block:: console
  51
  52     $ wget http://artifacts.opnfv.org/vswitchperf/vnf/vsperf-yardstick-image.qcow2
  53
  54 This image can be used for execution of sample testcases with dummy traffic
  55 generator.
  56
  57 **NOTE:** Traffic generators might require an installation of client software.
  58 This software is not included in the sample image and must be installed by user.
  59
  60 **NOTE:** This image will be updated only in case, that new features related
  61 to yardstick integration will be added to the vswitchperf.
  62
  63 Preparation of custom VM image
  64 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  65
  66 In general, any Linux distribution supported by vswitchperf can be used as
  67 a base image for vswitchperf. One of the possibilities is to modify vloop-vnf
  68 image, which can be downloaded from `<http://artifacts.opnfv.org/vswitchperf.html/>`__
  69 (see :ref:`vloop-vnf`).
  70
  71 Please follow the :ref:`vsperf-installation` to
  72 install vswitchperf inside vloop-vnf image. As vswitchperf will be run in
  73 trafficgen mode, it is possible to skip installation and compilation of OVS,
  74 QEMU and DPDK to keep image size smaller.
  75
  76 In case, that selected traffic generator requires installation of additional
  77 client software, please follow appropriate documentation. For example in case
  78 of IXIA, you would need to install IxOS and IxNetowrk TCL API.
  79
  80 VM image usage
  81 ~~~~~~~~~~~~~~
  82
  83 Image with vswitchperf must be uploaded into the glance service and
  84 vswitchperf specific flavor configured, e.g.:
  85
  86 .. code-block:: console
  87
  88     $ glance --os-username admin --os-image-api-version 1 image-create --name \
  89       vsperf --is-public true --disk-format qcow2 --container-format bare --file \
  90       vsperf-yardstick-image.qcow2
  91
  92     $ nova --os-username admin flavor-create vsperf-flavor 100 2048 25 1
  93
  94 Testcase execution
  95 ^^^^^^^^^^^^^^^^^^
  96
  97 After installation, yardstick is available as python package within yardstick
  98 specific virtual environment. It means, that yardstick environment must be
  99 enabled before the test execution, e.g.:
 100
 101 .. code-block:: console
 102
 103    source ~/yardstick_venv/bin/activate
 104
 105
 106 Next step is configuration of OpenStack environment, e.g. in case of devstack:
 107
 108 .. code-block:: console
 109
 110    source /opt/openstack/devstack/openrc
 111    export EXTERNAL_NETWORK=public
 112
 113 Vswitchperf testcases executable by yardstick are located at vswitchperf
 114 repository inside ``yardstick/tests`` directory. Example of their download
 115 and execution follows:
 116
 117 .. code-block:: console
 118
 119    git clone https://gerrit.opnfv.org/gerrit/vswitchperf
 120    cd vswitchperf
 121
 122    yardstick -d task start yardstick/tests/rfc2544_throughput_dummy.yaml
 123
 124 **NOTE:** Optional argument ``-d`` shows debug output.
 125
 126 Testcase customization
 127 ^^^^^^^^^^^^^^^^^^^^^^
 128
 129 Yardstick testcases are described by YAML files. vswitchperf specific testcases
 130 are part of the vswitchperf repository and their yaml files can be found at
 131 ``yardstick/tests`` directory. For detailed description of yaml file structure,
 132 please see yardstick documentation and testcase samples. Only vswitchperf specific
 133 parts will be discussed here.
 134
 135 Example of yaml file:
 136
 137 .. code-block:: yaml
 138
 139     ...
 140     scenarios:
 141     -
 142       type: Vsperf
 143       options:
 144         testname: 'p2p_rfc2544_throughput'
 145         trafficgen_port1: 'eth1'
 146         trafficgen_port2: 'eth3'
 147         external_bridge: 'br-ex'
 148         test_params: 'TRAFFICGEN_DURATION=30;TRAFFIC={'traffic_type':'rfc2544_throughput}'
 149         conf_file: '~/vsperf-yardstick.conf'
 150
 151       host: vsperf.demo
 152
 153       runner:
 154         type: Sequence
 155         scenario_option_name: frame_size
 156         sequence:
 157         - 64
 158         - 128
 159         - 512
 160         - 1024
 161         - 1518
 162       sla:
 163         metrics: 'throughput_rx_fps'
 164         throughput_rx_fps: 500000
 165         action: monitor
 166
 167     context:
 168     ...
 169
 170 Section option
 171 ~~~~~~~~~~~~~~
 172
 173 Section **option** defines details of vswitchperf test scenario. Lot of options
 174 are identical to the vswitchperf parameters passed through ``--test-params``
 175 argument. Following options are supported:
 176
 177 - **frame_size** - a packet size for which test should be executed;
 178   Multiple packet sizes can be tested by modification of Sequence runner
 179   section inside YAML definition. Default: '64'
 180 - **conf_file** - sets path to the vswitchperf configuration file, which will be
 181   uploaded to VM; Default: '~/vsperf-yardstick.conf'
 182 - **setup_script** - sets path to the setup script, which will be executed
 183   during setup and teardown phases
 184 - **trafficgen_port1** - specifies device name of 1st interface connected to
 185   the trafficgen
 186 - **trafficgen_port2** - specifies device name of 2nd interface connected to
 187   the trafficgen
 188 - **external_bridge** - specifies name of external bridge configured in OVS;
 189   Default: 'br-ex'
 190 - **test_params** - specifies a string with a list of vsperf configuration
 191   parameters, which will be passed to the ``--test-params`` CLI argument;
 192   Parameters should be stated in the form of ``param=value`` and separated
 193   by a semicolon. Configuration of traffic generator is driven by ``TRAFFIC``
 194   dictionary, which can be also updated by values defined by ``test_params``.
 195   Please check VSPERF documentation for details about available configuration
 196   parameters and their data types.
 197   In case that both **test_params** and **conf_file** are specified,
 198   then values from **test_params** will override values defined
 199   in the configuration file.
 200
 201 In case that **trafficgen_port1** and/or **trafficgen_port2** are defined, then
 202 these interfaces will be inserted into the **external_bridge** of OVS. It is
 203 expected, that OVS runs at the same node, where the testcase is executed. In case
 204 of more complex OpenStack installation or a need of additional OVS configuration,
 205 **setup_script** can be used.
 206
 207 **NOTE** It is essential to specify a configuration for selected traffic generator.
 208 In case, that standalone testcase is created, then traffic generator can be
 209 selected and configured directly in YAML file by **test_params**. On the other
 210 hand, if multiple testcases should be executed with the same traffic generator
 211 settings, then a customized configuration file should be prepared and its name
 212 passed by **conf_file** option.
 213
 214 Section runner
 215 ~~~~~~~~~~~~~~
 216
 217 Yardstick supports several `runner types
 218 <http://artifacts.opnfv.org/yardstick/docs/userguide/architecture.html#runner-types>`__.
 219 In case of vswitchperf specific TCs, **Sequence** runner type can be used to
 220 execute the testcase for given list of frame sizes.
 221
 222
 223 Section sla
 224 ~~~~~~~~~~~
 225
 226 In case that sla section is not defined, then testcase will be always
 227 considered as successful. On the other hand, it is possible to define a set of
 228 test metrics and their minimal values to evaluate test success. Any numeric
 229 value, reported by vswitchperf inside CSV result file, can be used.
 230 Multiple metrics can be defined as a coma separated list of items. Minimal
 231 value must be set separately for each metric.
 232
 233 e.g.:
 234
 235 .. code-block:: yaml
 236
 237       sla:
 238           metrics: 'throughput_rx_fps,throughput_rx_mbps'
 239           throughput_rx_fps: 500000
 240           throughput_rx_mbps: 1000
 241
 242 In case that any of defined metrics will be lower than defined value, then
 243 testcase will be marked as failed. Based on ``action`` policy, yardstick
 244 will either stop test execution (value ``assert``) or it will run next test
 245 (value ``monitor``).
 246
 247 **NOTE** The throughput SLA (or any other SLA) cannot be set to a meaningful
 248 value without knowledge of the server and networking environment, possibly
 249 including prior testing in that environment to establish a baseline SLA level
 250 under well-understood circumstances.