docs/testing/user/userguide/05-operation.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International
   2 .. License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4 .. (c) OPNFV, Intel, Ericsson AB, Huawei Technologies Co. Ltd and others.
   5
   6 ..
   7       Convention for heading levels in Yardstick:
   8       =======  Heading 0 (reserved for the title in a document)
   9       -------  Heading 1
  10       ^^^^^^^  Heading 2
  11       +++++++  Heading 3
  12       '''''''  Heading 4
  13       Avoid deeper levels because they do not render well.
  14
  15 ===============
  16 Yardstick Usage
  17 ===============
  18
  19 Once you have yardstick installed, you can start using it to run testcases
  20 immediately, through the CLI. You can also define and run new testcases and
  21 test suites. This chapter details basic usage (running testcases), as well as
  22 more advanced usage (creating your own testcases).
  23
  24 Yardstick common CLI
  25 --------------------
  26
  27 List test cases
  28 ^^^^^^^^^^^^^^^
  29
  30 ``yardstick testcase list``: This command line would list all test cases in
  31 Yardstick. It would show like below::
  32
  33    +---------------------------------------------------------------------------------------
  34    | Testcase Name         | Description
  35    +---------------------------------------------------------------------------------------
  36    | opnfv_yardstick_tc001 | Measure network throughput using pktgen
  37    | opnfv_yardstick_tc002 | measure network latency using ping
  38    | opnfv_yardstick_tc005 | Measure Storage IOPS, throughput and latency using fio.
  39    ...
  40    +---------------------------------------------------------------------------------------
  41
  42
  43 Show a test case config file
  44 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  45
  46 Take opnfv_yardstick_tc002 for an example. This test case measure network
  47 latency. You just need to type in ``yardstick testcase show
  48 opnfv_yardstick_tc002``, and the console would show the config yaml of this
  49 test case::
  50
  51    ---
  52
  53    schema: "yardstick:task:0.1"
  54    description: >
  55       Yardstick TC002 config file;
  56       measure network latency using ping;
  57
  58    {% set image = image or "cirros-0.3.5" %}
  59
  60    {% set provider = provider or none %}
  61    {% set physical_network = physical_network or 'physnet1' %}
  62    {% set segmentation_id = segmentation_id or none %}
  63    {% set packetsize = packetsize or 100 %}
  64
  65    scenarios:
  66    {% for i in range(2) %}
  67    -
  68     type: Ping
  69     options:
  70       packetsize: {{packetsize}}
  71     host: athena.demo
  72     target: ares.demo
  73
  74     runner:
  75       type: Duration
  76       duration: 60
  77       interval: 10
  78
  79     sla:
  80       max_rtt: 10
  81       action: monitor
  82    {% endfor %}
  83
  84    context:
  85     name: demo
  86     image: {{image}}
  87     flavor: yardstick-flavor
  88     user: cirros
  89
  90     placement_groups:
  91       pgrp1:
  92         policy: "availability"
  93
  94     servers:
  95       athena:
  96         floating_ip: true
  97         placement: "pgrp1"
  98       ares:
  99         placement: "pgrp1"
 100
 101     networks:
 102       test:
 103         cidr: '10.0.1.0/24'
 104         {% if provider == "vlan" %}
 105         provider: {{provider}}
 106         physical_network: {{physical_network}}
 107           {% if segmentation_id %}
 108         segmentation_id: {{segmentation_id}}
 109           {% endif %}
 110         {% endif %}
 111
 112
 113 Run a Yardstick test case
 114 ^^^^^^^^^^^^^^^^^^^^^^^^^
 115
 116 If you want run a test case, then you need to use ``yardstick task start
 117 <test_case_path>`` this command support some parameters as below:
 118
 119    +---------------------+--------------------------------------------------+
 120    | Parameters          | Detail                                           |
 121    +=====================+==================================================+
 122    | -d                  | show debug log of yardstick running              |
 123    |                     |                                                  |
 124    +---------------------+--------------------------------------------------+
 125    | --task-args         | If you want to customize test case parameters,   |
 126    |                     | use "--task-args" to pass the value. The format  |
 127    |                     | is a json string with parameter key-value pair.  |
 128    |                     |                                                  |
 129    +---------------------+--------------------------------------------------+
 130    | --task-args-file    | If you want to use yardstick                     |
 131    |                     | env prepare command(or                           |
 132    |                     | related API) to load the                         |
 133    +---------------------+--------------------------------------------------+
 134    | --parse-only        |                                                  |
 135    |                     |                                                  |
 136    |                     |                                                  |
 137    +---------------------+--------------------------------------------------+
 138    | --output-file \     | Specify where to output the log. if not pass,    |
 139    | OUTPUT_FILE_PATH    | the default value is                             |
 140    |                     | "/tmp/yardstick/yardstick.log"                   |
 141    |                     |                                                  |
 142    +---------------------+--------------------------------------------------+
 143    | --suite \           | run a test suite, TEST_SUITE_PATH specify where  |
 144    | TEST_SUITE_PATH     | the test suite locates                           |
 145    |                     |                                                  |
 146    +---------------------+--------------------------------------------------+
 147
 148
 149 Run Yardstick in a local environment
 150 ------------------------------------
 151
 152 We also have a guide about `How to run Yardstick in a local environment`_.
 153 This work is contributed by Tapio Tallgren.
 154
 155 Create a new testcase for Yardstick
 156 -----------------------------------
 157
 158 As a user, you may want to define a new testcase in addition to the ones
 159 already available in Yardstick. This section will show you how to do this.
 160
 161 Each testcase consists of two sections:
 162
 163 * ``scenarios`` describes what will be done by the test
 164 * ``context`` describes the environment in which the test will be run.
 165
 166 Defining the testcase scenarios
 167 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 168
 169 TODO
 170
 171 Defining the testcase context(s)
 172 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 173
 174 Each testcase consists of one or more contexts, which describe the environment
 175 in which the testcase will be run.
 176 Current available contexts are:
 177
 178 * ``Dummy``: this is a no-op context, and is used when there is no environment
 179   to set up e.g. when testing whether OpenStack services are available
 180 * ``Node``: this context is used to perform operations on baremetal servers
 181 * ``Heat``: uses OpenStack to provision the required hosts, networks, etc.
 182 * ``Kubernetes``: uses Kubernetes to provision the resources required for the
 183   test.
 184
 185 Regardless of the context type, the ``context`` section of the testcase will
 186 consist of the following::
 187
 188    context:
 189      name: demo
 190      type: Dummy|Node|Heat|Kubernetes
 191
 192 The content of the ``context`` section will vary based on the context type.
 193
 194 Dummy Context
 195 +++++++++++++
 196
 197 No additional information is required for the Dummy context::
 198
 199   context:
 200     name: my_context
 201     type: Dummy
 202
 203 Node Context
 204 ++++++++++++
 205
 206 TODO
 207
 208 Heat Context
 209 ++++++++++++
 210
 211 In addition to ``name`` and ``type``, a Heat context requires the following
 212 arguments:
 213
 214 * ``image``: the image to be used to boot VMs
 215 * ``flavor``: the flavor to be used for VMs in the context
 216 * ``user``: the username for connecting into the VMs
 217 * ``networks``: The networks to be created, networks are identified by name
 218
 219   * ``name``: network name (required)
 220   * (TODO) Any optional attributes
 221
 222 * ``servers``: The servers to be created
 223
 224   * ``name``: server name
 225   * (TODO) Any optional attributes
 226
 227 In addition to the required arguments, the following optional arguments can be
 228 passed to the Heat context:
 229
 230 * ``placement_groups``:
 231
 232   * ``name``: the name of the placement group to be created
 233   * ``policy``: either ``affinity`` or ``availability``
 234 * ``server_groups``:
 235
 236   * ``name``: the name of the server group
 237   * ``policy``: either ``affinity`` or ``anti-affinity``
 238
 239 Combining these elements together, a sample Heat context config looks like:
 240
 241 .. literalinclude::
 242    ../../../../yardstick/tests/integration/dummy-scenario-heat-context.yaml
 243    :start-after: ---
 244
 245 Using exisiting HOT Templates
 246 '''''''''''''''''''''''''''''
 247
 248 TODO
 249
 250 Kubernetes Context
 251 ++++++++++++++++++
 252
 253 TODO
 254
 255 Using multiple contexts in a testcase
 256 +++++++++++++++++++++++++++++++++++++
 257
 258 When using multiple contexts in a testcase, the ``context`` section is replaced
 259 by a ``contexts`` section, and each context is separated with a ``-`` line::
 260
 261   contexts:
 262   -
 263     name: context1
 264     type: Heat
 265     ...
 266   -
 267     name: context2
 268     type: Node
 269     ...
 270
 271
 272 Reusing a context
 273 +++++++++++++++++
 274
 275 Typically, a context is torn down after a testcase is run, however, the user
 276 may wish to keep an context intact after a testcase is complete.
 277
 278 .. note::
 279   This feature has been implemented for the Heat context only
 280
 281 To keep or reuse a context, the ``flags`` option must be specified:
 282
 283 * ``no_setup``: skip the deploy stage, and fetch the details of a deployed
 284    context/Heat stack.
 285 * ``no_teardown``: skip the undeploy stage, thus keeping the stack intact for
 286    the next test
 287
 288 If either of these ``flags`` are ``True``, the context information must still
 289 be given. By default, these flags are disabled::
 290
 291   context:
 292     name: mycontext
 293     type: Heat
 294     flags:
 295       no_setup: True
 296       no_teardown: True
 297     ...
 298
 299 Create a test suite for Yardstick
 300 ---------------------------------
 301
 302 A test suite in Yardstick is a .yaml file which includes one or more test
 303 cases. Yardstick is able to support running test suite task, so you can
 304 customize your own test suite and run it in one task.
 305
 306 ``tests/opnfv/test_suites`` is the folder where Yardstick puts CI test suite.
 307 A typical test suite is like below (the ``fuel_test_suite.yaml`` example)::
 308
 309    ---
 310    # Fuel integration test task suite
 311
 312    schema: "yardstick:suite:0.1"
 313
 314    name: "fuel_test_suite"
 315    test_cases_dir: "samples/"
 316    test_cases:
 317    -
 318     file_name: ping.yaml
 319    -
 320     file_name: iperf3.yaml
 321
 322 As you can see, there are two test cases in the ``fuel_test_suite.yaml``. The
 323 ``schema`` and the ``name`` must be specified. The test cases should be listed
 324 via the tag ``test_cases`` and their relative path is also marked via the tag
 325 ``test_cases_dir``.
 326
 327 Yardstick test suite also supports constraints and task args for each test
 328 case. Here is another sample (the ``os-nosdn-nofeature-ha.yaml`` example) to
 329 show this, which is digested from one big test suite::
 330
 331    ---
 332
 333    schema: "yardstick:suite:0.1"
 334
 335    name: "os-nosdn-nofeature-ha"
 336    test_cases_dir: "tests/opnfv/test_cases/"
 337    test_cases:
 338    -
 339      file_name: opnfv_yardstick_tc002.yaml
 340    -
 341      file_name: opnfv_yardstick_tc005.yaml
 342    -
 343      file_name: opnfv_yardstick_tc043.yaml
 344         constraint:
 345            installer: compass
 346            pod: huawei-pod1
 347         task_args:
 348            huawei-pod1: '{"pod_info": "etc/yardstick/.../pod.yaml",
 349            "host": "node4.LF","target": "node5.LF"}'
 350
 351 As you can see in test case ``opnfv_yardstick_tc043.yaml``, there are two
 352 tags, ``constraint`` and ``task_args``. ``constraint`` is to specify which
 353 installer or pod it can be run in the CI environment. ``task_args`` is to
 354 specify the task arguments for each pod.
 355
 356 All in all, to create a test suite in Yardstick, you just need to create a
 357 yaml file and add test cases, constraint or task arguments if necessary.
 358
 359 References
 360 ----------
 361
 362 .. _`How to run Yardstick in a local environment`: https://wiki.opnfv.org/display/yardstick/How+to+run+Yardstick+in+a+local+environment