docs/userguide/architecture.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) 2016 Huawei Technologies Co.,Ltd and others
   5
   6 ============
   7 Architecture
   8 ============
   9
  10 Abstract
  11 ========
  12 This chapter describes the yardstick framework software architecture. we will introduce it from Use-Case View,
  13 Logical View, Process View and Deployment View. More technical details will be introduced in this chapter.
  14
  15 Overview
  16 ========
  17
  18 Architecture overview
  19 ---------------------
  20 Yardstick is mainly written in Python, and test configurations are made
  21 in YAML. Documentation is written in reStructuredText format, i.e. .rst
  22 files. Yardstick is inspired by Rally. Yardstick is intended to run on a
  23 computer with access and credentials to a cloud. The test case is described
  24 in a configuration file given as an argument.
  25
  26 How it works: the benchmark task configuration file is parsed and converted into
  27 an internal model. The context part of the model is converted into a Heat
  28 template and deployed into a stack. Each scenario is run using a runner, either
  29 serially or in parallel. Each runner runs in its own subprocess executing
  30 commands in a VM using SSH. The output of each scenario is written as json
  31 records to a file or influxdb or http server, we use influxdb as the backend,
  32 the test result will be shown with grafana.
  33
  34
  35 Concept
  36 -------
  37 **Benchmark** - assess the relative performance of something
  38
  39 **Benchmark** configuration file - describes a single test case in yaml format
  40
  41 **Context** - The set of Cloud resources used by a scenario, such as user
  42 names, image names, affinity rules and network configurations. A context is
  43 converted into a simplified Heat template, which is used to deploy onto the
  44 Openstack environment.
  45
  46 **Data** - Output produced by running a benchmark, written to a file in json format
  47
  48 **Runner** - Logic that determines how a test scenario is run and reported, for
  49 example the number of test iterations, input value stepping and test duration.
  50 Predefined runner types exist for re-usage, see `Runner types`_.
  51
  52 **Scenario** - Type/class of measurement for example Ping, Pktgen, (Iperf, LmBench, ...)
  53
  54 **SLA** - Relates to what result boundary a test case must meet to pass. For
  55 example a latency limit, amount or ratio of lost packets and so on. Action
  56 based on :term:`SLA` can be configured, either just to log (monitor) or to stop
  57 further testing (assert). The :term:`SLA` criteria is set in the benchmark
  58 configuration file and evaluated by the runner.
  59
  60
  61 Runner types
  62 ------------
  63
  64 There exists several predefined runner types to choose between when designing
  65 a test scenario:
  66
  67 **Arithmetic:**
  68 Every test run arithmetically steps the specified input value(s) in the
  69 test scenario, adding a value to the previous input value. It is also possible
  70 to combine several input values for the same test case in different
  71 combinations.
  72
  73 Snippet of an Arithmetic runner configuration:
  74 ::
  75
  76
  77   runner:
  78       type: Arithmetic
  79       iterators:
  80       -
  81         name: stride
  82         start: 64
  83         stop: 128
  84         step: 64
  85
  86 **Duration:**
  87 The test runs for a specific period of time before completed.
  88
  89 Snippet of a Duration runner configuration:
  90 ::
  91
  92
  93   runner:
  94     type: Duration
  95     duration: 30
  96
  97 **Sequence:**
  98 The test changes a specified input value to the scenario. The input values
  99 to the sequence are specified in a list in the benchmark configuration file.
 100
 101 Snippet of a Sequence runner configuration:
 102 ::
 103
 104
 105   runner:
 106     type: Sequence
 107     scenario_option_name: packetsize
 108     sequence:
 109     - 100
 110     - 200
 111     - 250
 112
 113
 114 **Iteration:**
 115 Tests are run a specified number of times before completed.
 116
 117 Snippet of an Iteration runner configuration:
 118 ::
 119
 120
 121   runner:
 122     type: Iteration
 123     iterations: 2
 124
 125
 126
 127
 128 Use-Case View
 129 =============
 130 TBD(kubi)
 131
 132 Logical View
 133 ============
 134 TBD(Qiliang)
 135
 136 Process View (Test execution flow)
 137 ==================================
 138 TBD(Limingjiang)
 139
 140 Deployment View
 141 ===============
 142 TBD(Patrick)
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155 Yardstick Directory structure
 156 =============================
 157
 158 **yardstick/** - Yardstick main directory.
 159
 160 *ci/* - Used for continuous integration of Yardstick at different PODs and
 161         with support for different installers.
 162
 163 *docs/* - All documentation is stored here, such as configuration guides,
 164           user guides and Yardstick descriptions.
 165
 166 *etc/* - Used for test cases requiring specific POD configurations.
 167
 168 *samples/* - test case samples are stored here, most of all scenario and
 169              feature's samples are shown in this directory.
 170
 171 *tests/* - Here both Yardstick internal tests (*functional/* and *unit/*) as
 172            well as the test cases run to verify the NFVI (*opnfv/*) are stored.
 173            Also configurations of what to run daily and weekly at the different
 174            PODs is located here.
 175
 176 *tools/* - Currently contains tools to build image for VMs which are deployed
 177            by Heat. Currently contains how to build the yardstick-trusty-server
 178            image with the different tools that are needed from within the image.
 179
 180 *vTC/* - Contains the files for running the virtual Traffic Classifier tests.
 181
 182 *yardstick/* - Contains the internals of Yardstick: Runners, Scenario, Contexts,
 183                CLI parsing, keys, plotting tools, dispatcher and so on.
 184