docs/testing/user/userguide/03-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
  13 introduce it from Use-Case View, Logical View, Process View and Deployment
  14 View. More technical details will be introduced in this chapter.
  15
  16 Overview
  17 ========
  18
  19 Architecture overview
  20 ---------------------
  21 Yardstick is mainly written in Python, and test configurations are made
  22 in YAML. Documentation is written in reStructuredText format, i.e. .rst
  23 files. Yardstick is inspired by Rally. Yardstick is intended to run on a
  24 computer with access and credentials to a cloud. The test case is described
  25 in a configuration file given as an argument.
  26
  27 How it works: the benchmark task configuration file is parsed and converted
  28 into an internal model. The context part of the model is converted into a Heat
  29 template and deployed into a stack. Each scenario is run using a runner, either
  30 serially or in parallel. Each runner runs in its own subprocess executing
  31 commands in a VM using SSH. The output of each scenario is written as json
  32 records to a file or influxdb or http server, we use influxdb as the backend,
  33 the test result will be shown with grafana.
  34
  35
  36 Concept
  37 -------
  38 **Benchmark** - assess the relative performance of something
  39
  40 **Benchmark** configuration file - describes a single test case in yaml format
  41
  42 **Context** - The set of Cloud resources used by a scenario, such as user
  43 names, image names, affinity rules and network configurations. A context is
  44 converted into a simplified Heat template, which is used to deploy onto the
  45 Openstack environment.
  46
  47 **Data** - Output produced by running a benchmark, written to a file in json
  48 format
  49
  50 **Runner** - Logic that determines how a test scenario is run and reported, for
  51 example the number of test iterations, input value stepping and test duration.
  52 Predefined runner types exist for re-usage, see `Runner types`_.
  53
  54 **Scenario** - Type/class of measurement for example Ping, Pktgen, (Iperf,
  55 LmBench, ...)
  56
  57 **SLA** - Relates to what result boundary a test case must meet to pass. For
  58 example a latency limit, amount or ratio of lost packets and so on. Action
  59 based on :term:`SLA` can be configured, either just to log (monitor) or to stop
  60 further testing (assert). The :term:`SLA` criteria is set in the benchmark
  61 configuration file and evaluated by the runner.
  62
  63
  64 Runner types
  65 ------------
  66
  67 There exists several predefined runner types to choose between when designing
  68 a test scenario:
  69
  70 **Arithmetic:**
  71 Every test run arithmetically steps the specified input value(s) in the
  72 test scenario, adding a value to the previous input value. It is also possible
  73 to combine several input values for the same test case in different
  74 combinations.
  75
  76 Snippet of an Arithmetic runner configuration:
  77 ::
  78
  79
  80   runner:
  81       type: Arithmetic
  82       iterators:
  83       -
  84         name: stride
  85         start: 64
  86         stop: 128
  87         step: 64
  88
  89 **Duration:**
  90 The test runs for a specific period of time before completed.
  91
  92 Snippet of a Duration runner configuration:
  93 ::
  94
  95
  96   runner:
  97     type: Duration
  98     duration: 30
  99
 100 **Sequence:**
 101 The test changes a specified input value to the scenario. The input values
 102 to the sequence are specified in a list in the benchmark configuration file.
 103
 104 Snippet of a Sequence runner configuration:
 105 ::
 106
 107
 108   runner:
 109     type: Sequence
 110     scenario_option_name: packetsize
 111     sequence:
 112     - 100
 113     - 200
 114     - 250
 115
 116
 117 **Iteration:**
 118 Tests are run a specified number of times before completed.
 119
 120 Snippet of an Iteration runner configuration:
 121 ::
 122
 123
 124   runner:
 125     type: Iteration
 126     iterations: 2
 127
 128
 129
 130
 131 Use-Case View
 132 =============
 133 Yardstick Use-Case View shows two kinds of users. One is the Tester who will
 134 do testing in cloud, the other is the User who is more concerned with test
 135 result and result analyses.
 136
 137 For testers, they will run a single test case or test case suite to verify
 138 infrastructure compliance or bencnmark their own infrastructure performance.
 139 Test result will be stored by dispatcher module, three kinds of store method
 140 (file, influxdb and http) can be configured. The detail information of
 141 scenarios and runners can be queried with CLI by testers.
 142
 143 For users, they would check test result with four ways.
 144
 145 If dispatcher module is configured as file(default), there are two ways to
 146 check test result. One is to get result from yardstick.out ( default path:
 147 /tmp/yardstick.out), the other is to get plot of test result, it will be shown
 148 if users execute command "yardstick-plot".
 149
 150 If dispatcher module is configured as influxdb, users will check test
 151 result on Grafana which is most commonly used for visualizing time series data.
 152
 153 If dispatcher module is configured as http, users will check test result
 154 on OPNFV testing dashboard which use MongoDB as backend.
 155
 156 .. image:: images/Use_case.png
 157    :width: 800px
 158    :alt: Yardstick Use-Case View
 159
 160 Logical View
 161 ============
 162 Yardstick Logical View describes the most important classes, their
 163 organization, and the most important use-case realizations.
 164
 165 Main classes:
 166
 167 **TaskCommands** - "yardstick task" subcommand handler.
 168
 169 **HeatContext** - Do test yaml file context section model convert to HOT,
 170 deploy and undeploy Openstack heat stack.
 171
 172 **Runner** - Logic that determines how a test scenario is run and reported.
 173
 174 **TestScenario** - Type/class of measurement for example Ping, Pktgen, (Iperf,
 175 LmBench, ...)
 176
 177 **Dispatcher** - Choose user defined way to store test results.
 178
 179 TaskCommands is the "yardstick task" subcommand's main entry. It takes yaml
 180 file (e.g. test.yaml) as input, and uses HeatContext to convert the yaml
 181 file's context section to HOT. After Openstack heat stack is deployed by
 182 HeatContext with the converted HOT, TaskCommands use Runner to run specified
 183 TestScenario. During first runner initialization, it will create output
 184 process. The output process use Dispatcher to push test results. The Runner
 185 will also create a process to execute TestScenario. And there is a
 186 multiprocessing queue between each runner process and output process, so the
 187 runner process can push the real-time test results to the storage media.
 188 TestScenario is commonly connected with VMs by using ssh. It sets up VMs and
 189 run test measurement scripts through the ssh tunnel. After all TestScenaio
 190 is finished, TaskCommands will undeploy the heat stack. Then the whole test is
 191 finished.
 192
 193 .. image:: images/Yardstick_framework_architecture_in_D.png
 194    :width: 800px
 195    :alt: Yardstick framework architecture in Danube
 196
 197 Process View (Test execution flow)
 198 ==================================
 199 Yardstick process view shows how yardstick runs a test case. Below is the
 200 sequence graph about the test execution flow using heat context, and each
 201 object represents one module in yardstick:
 202
 203 .. image:: images/test_execution_flow.png
 204    :width: 800px
 205    :alt: Yardstick Process View
 206
 207 A user wants to do a test with yardstick. He can use the CLI to input the
 208 command to start a task. "TaskCommands" will receive the command and ask
 209 "HeatContext" to parse the context. "HeatContext" will then ask "Model" to
 210 convert the model. After the model is generated, "HeatContext" will inform
 211 "Openstack" to deploy the heat stack by heat template. After "Openstack"
 212 deploys the stack, "HeatContext" will inform "Runner" to run the specific test
 213 case.
 214
 215 Firstly, "Runner" would ask "TestScenario" to process the specific scenario.
 216 Then "TestScenario" will start to log on the openstack by ssh protocal and
 217 execute the test case on the specified VMs. After the script execution
 218 finishes, "TestScenario" will send a message to inform "Runner". When the
 219 testing job is done, "Runner" will inform "Dispatcher" to output the test
 220 result via file, influxdb or http. After the result is output, "HeatContext"
 221 will call "Openstack" to undeploy the heat stack. Once the stack is
 222 undepoyed, the whole test ends.
 223
 224 Deployment View
 225 ===============
 226 Yardstick deployment view shows how the yardstick tool can be deployed into the
 227 underlying platform. Generally, yardstick tool is installed on JumpServer(see
 228 `07-installation` for detail installation steps), and JumpServer is
 229 connected with other control/compute servers by networking. Based on this
 230 deployment, yardstick can run the test cases on these hosts, and get the test
 231 result for better showing.
 232
 233 .. image:: images/Deployment.png
 234    :width: 800px
 235    :alt: Yardstick Deployment View
 236
 237 Yardstick Directory structure
 238 =============================
 239
 240 **yardstick/** - Yardstick main directory.
 241
 242 *tests/ci/* - Used for continuous integration of Yardstick at different PODs and
 243         with support for different installers.
 244
 245 *docs/* - All documentation is stored here, such as configuration guides,
 246           user guides and Yardstick test case descriptions.
 247
 248 *etc/* - Used for test cases requiring specific POD configurations.
 249
 250 *samples/* - test case samples are stored here, most of all scenario and
 251              feature samples are shown in this directory.
 252
 253 *tests/* - The test cases run to verify the NFVI (*opnfv/*) are stored here.
 254            The configurations of what to run daily and weekly at the different
 255            PODs are also located here.
 256
 257 *tools/* - Contains tools to build image for VMs which are deployed by Heat.
 258            Currently contains how to build the yardstick-image with the
 259            different tools that are needed from within the image.
 260
 261 *plugin/* - Plug-in configuration files are stored here.
 262
 263 *yardstick/* - Contains the internals of Yardstick: :term:`Runners <runner>`,
 264                :term:`Scenarios <scenario>`, :term:`Contexts <context>`, CLI
 265                parsing, keys, plotting tools, dispatcher, plugin
 266                install/remove scripts and so on.
 267
 268 *yardstick/tests* - The Yardstick internal tests (*functional/* and *unit/*)
 269                     are stored here.