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