docs/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 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 Yardstick Use-Case View shows two kinds of users. One is the Tester who will
 131 do testing in cloud, the other is the User who is more concerned with test result
 132 and result analyses.
 133
 134 For testers, they will run a single test case or test case suite to verify
 135 infrastructure compliance or bencnmark their own infrastructure performance.
 136 Test result will be stored by dispatcher module, three kinds of store method
 137 (file, influxdb and http) can be configured. The detail information of
 138 scenarios and runners can be queried with CLI by testers.
 139
 140 For users, they would check test result with four ways.
 141
 142 If dispatcher module is configured as file(default), there are two ways to
 143 check test result. One is to get result from yardstick.out ( default path:
 144 /tmp/yardstick.out), the other is to get plot of test result, it will be shown
 145 if users execute command "yardstick-plot".
 146
 147 If dispatcher module is configured as influxdb, users will check test
 148 result on Grafana which is most commonly used for visualizing time series data.
 149
 150 If dispatcher module is configured as http, users will check test result
 151 on OPNFV testing dashboard which use MongoDB as backend.
 152
 153 .. image:: images/Use_case.png
 154    :width: 800px
 155    :alt: Yardstick Use-Case View
 156
 157 Logical View
 158 ============
 159 Yardstick Logical View describes the most important classes, their
 160 organization, and the most important use-case realizations.
 161
 162 Main classes:
 163
 164 **TaskCommands** - "yardstick task" subcommand handler.
 165
 166 **HeatContext** - Do test yaml file context section model convert to HOT,
 167 deploy and undeploy Openstack heat stack.
 168
 169 **Runner** - Logic that determines how a test scenario is run and reported.
 170
 171 **TestScenario** - Type/class of measurement for example Ping, Pktgen, (Iperf,
 172 LmBench, ...)
 173
 174 **Dispatcher** - Choose user defined way to store test results.
 175
 176 TaskCommands is the "yardstick task" subcommand's main entry. It takes yaml
 177 file (e.g. test.yaml) as input, and uses HeatContext to convert the yaml
 178 file's context section to HOT. After Openstacik heat stack is deployed by
 179 HeatContext with the converted HOT, TaskCommands use Runner to run specified
 180 TestScenario. During first runner initialization, it will create output
 181 process. The output process use Dispatcher to push test results. The Runner
 182 will also create a process to execute TestScenario. And there is a
 183 multiprocessing queue between each runner process and output process, so the
 184 runner process can push the real-time test results to the storage media.
 185 TestScenario is commonly connected with VMs by using ssh. It sets up VMs and
 186 run test measurement scripts through the ssh tunnel. After all TestScenaio
 187 is finished, TaskCommands will undeploy the heat stack. Then the whole test is
 188 finished.
 189
 190 .. image:: images/Logical_view.png
 191    :width: 800px
 192    :alt: Yardstick Logical View
 193
 194 Process View (Test execution flow)
 195 ==================================
 196 Yardstick process view shows how yardstick runs a test case. Below is the
 197 sequence graph about the test execution flow using heat context, and each
 198 object represents one module in yardstick:
 199
 200 .. image:: images/test_execution_flow.png
 201    :width: 800px
 202    :alt: Yardstick Process View
 203
 204 A user wants to do a test with yardstick. He can use the CLI to input the
 205 command to start a task. "TaskCommands" will receive the command and ask
 206 "HeatContext" to parse the context. "HeatContext" will then ask "Model" to
 207 convert the model. After the model is generated, "HeatContext" will inform
 208 "Openstack" to deploy the heat stack by heat template. After "Openstack"
 209 deploys the stack, "HeatContext" will inform "Runner" to run the specific test
 210 case.
 211
 212 Firstly, "Runner" would ask "TestScenario" to process the specific scenario.
 213 Then "TestScenario" will start to log on the openstack by ssh protocal and
 214 execute the test case on the specified VMs. After the script execution
 215 finishes, "TestScenario" will send a message to inform "Runner". When the
 216 testing job is done, "Runner" will inform "Dispatcher" to output the test
 217 result via file, influxdb or http. After the result is output, "HeatContext"
 218 will call "Openstack" to undeploy the heat stack. Once the stack is
 219 undepoyed, the whole test ends.
 220
 221 Deployment View
 222 ===============
 223 Yardstick deployment view shows how the yardstick tool can be deployed into the
 224 underlying platform. Generally, yardstick tool is installed on JumpServer(see
 225 `03-installation` for detail installation steps), and JumpServer is
 226 connected with other control/compute servers by networking. Based on this
 227 deployment, yardstick can run the test cases on these hosts, and get the test
 228 result for better showing.
 229
 230 .. image:: images/Deployment.png
 231    :width: 800px
 232    :alt: Yardstick Deployment View
 233
 234 Yardstick Directory structure
 235 =============================
 236
 237 **yardstick/** - Yardstick main directory.
 238
 239 *ci/* - Used for continuous integration of Yardstick at different PODs and
 240         with support for different installers.
 241
 242 *docs/* - All documentation is stored here, such as configuration guides,
 243           user guides and Yardstick descriptions.
 244
 245 *etc/* - Used for test cases requiring specific POD configurations.
 246
 247 *samples/* - test case samples are stored here, most of all scenario and
 248              feature's samples are shown in this directory.
 249
 250 *tests/* - Here both Yardstick internal tests (*functional/* and *unit/*) as
 251            well as the test cases run to verify the NFVI (*opnfv/*) are stored.
 252            Also configurations of what to run daily and weekly at the different
 253            PODs is located here.
 254
 255 *tools/* - Currently contains tools to build image for VMs which are deployed
 256            by Heat. Currently contains how to build the yardstick-trusty-server
 257            image with the different tools that are needed from within the image.
 258
 259 *vTC/* - Contains the files for running the virtual Traffic Classifier tests.
 260
 261 *yardstick/* - Contains the internals of Yardstick: Runners, Scenario, Contexts,
 262                CLI parsing, keys, plotting tools, dispatcher and so on.
 263