docs/userguide/07-installation.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, Ericsson AB, Huawei Technologies Co.,Ltd and others.
   5
   6 Yardstick Installation
   7 ======================
   8
   9 Abstract
  10 --------
  11
  12 Yardstick supports installation on Ubuntu 14.04 or by using a Docker image.
  13 The installation procedure on Ubuntu 14.04 or via the docker image are
  14 detailed in the section below.
  15
  16 To use Yardstick you should have access to an OpenStack environment,
  17 with at least Nova, Neutron, Glance, Keystone and Heat installed.
  18
  19 The steps needed to run Yardstick are:
  20
  21 1. Install Yardstick.
  22 2. Create the test configuration .yaml file.
  23 3. Build a guest image。
  24 4. Load the image into the OpenStack environment.
  25 5. Create a Neutron external network.
  26 6. Load OpenStack environment variables.
  27 6. Run the test case.
  28
  29
  30 Installing Yardstick on Ubuntu 14.04
  31 ------------------------------------
  32
  33 .. _install-framework:
  34
  35 You can install Yardstick framework directly on Ubuntu 14.04 or in an Ubuntu
  36 14.04 Docker image.
  37 No matter which way you choose to install Yardstick framework, the following
  38 installation steps are identical.
  39 If you choose to use the Ubuntu 14.04 Docker image, You can pull the Ubuntu
  40 14.04 Docker image from Docker hub:
  41
  42 ::
  43
  44   docker pull ubuntu:14.04
  45
  46 Installing Yardstick framework
  47 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  48 Install dependencies:
  49
  50 ::
  51
  52   sudo apt-get update && sudo apt-get install -y \
  53       wget \
  54       git \
  55       sshpass \
  56       qemu-utils \
  57       kpartx \
  58       libffi-dev \
  59       libssl-dev \
  60       python \
  61       python-dev \
  62       python-virtualenv \
  63       libxml2-dev \
  64       libxslt1-dev \
  65       python-setuptools
  66
  67 Create a python virtual environment, source it and update setuptools:
  68
  69 ::
  70
  71   virtualenv ~/yardstick_venv
  72   source ~/yardstick_venv/bin/activate
  73   easy_install -U setuptools
  74
  75 Download source code and install python dependencies:
  76
  77 ::
  78
  79   git clone https://gerrit.opnfv.org/gerrit/yardstick
  80   cd yardstick
  81   python setup.py install
  82
  83 A Youtube video tutorial on this installation mode is available
  84 at: http://www.youtube.com/watch?v=4S4izNolmR0
  85
  86 .. image:: http://img.youtube.com/vi/4S4izNolmR0/0.jpg
  87    :alt: http://www.youtube.com/watch?v=4S4izNolmR0
  88    :target: http://www.youtube.com/watch?v=4S4izNolmR0
  89
  90
  91 Installing Yardstick using Docker
  92 ---------------------------------
  93
  94 Yardstick iteself has a Docker image, this Docker image (**Yardstick-stable**)
  95 serves as a replacement for installing the Yardstick framework in a virtual
  96 environment (for example as done in :ref:`install-framework`).
  97 It is recommended to use this Docker image to run Yardstick test.
  98
  99 Yardstick-stable image
 100 ^^^^^^^^^^^^^^^^^^^^^^
 101 Pull the Yardstick-stable Docker image from Docker hub:
 102
 103 ::
 104
 105   docker pull opnfv/yardstick:stable
 106
 107 Run the Docker image:
 108
 109 ::
 110
 111   docker run --privileged=true -it openfv/yardstick /bin/bash
 112
 113 In the container run yardstick task command to execute a test case.
 114 Before executing Yardstick test case, make sure that yardstick-trusty-server
 115 image and yardstick flavor is available in OpenStack.
 116 Detailed steps about creating yardstick flavor and building yardstick-trusty-server
 117 image can be found below.
 118
 119
 120 OpenStack parameters and credentials
 121 ------------------------------------
 122
 123 Yardstick-flavor
 124 ^^^^^^^^^^^^^^^^
 125 Most of the sample test cases in Yardstick are using an OpenStack flavor called
 126 *yardstick-flavor* which deviates from the OpenStack standard m1.tiny flavor by the
 127 disk size - instead of 1GB it has 3GB. Other parameters are the same as in m1.tiny.
 128
 129 Create yardstick-flavor:
 130
 131 ::
 132
 133   nova flavor-create yardstick-flavor 100 512 3 1
 134
 135 Environment variables
 136 ^^^^^^^^^^^^^^^^^^^^^
 137 Before running Yardstick it is necessary to export OpenStack environment variables
 138 from the OpenStack *openrc* file (using the ``source`` command) and export the
 139 external network name ``export EXTERNAL_NETWORK="external-network-name"``,
 140 the default name for the external network is ``net04_ext``.
 141
 142 Credential environment variables in the *openrc* file have to include at least:
 143
 144 * OS_AUTH_URL
 145 * OS_USERNAME
 146 * OS_PASSWORD
 147 * OS_TENANT_NAME
 148
 149
 150 .. _guest-image:
 151
 152 Building a guest image
 153 ^^^^^^^^^^^^^^^^^^^^^^
 154 Yardstick has a tool for building an Ubuntu Cloud Server image containing all
 155 the required tools to run test cases supported by Yardstick. It is necessary to
 156 have sudo rights to use this tool.
 157
 158 Also you may need install several additional packages to use this tool, by
 159 follwing the commands below:
 160
 161 ::
 162
 163   apt-get update && apt-get install -y \
 164       qemu-utils \
 165       kpartx
 166
 167 This image can be built using the following command while in the directory where
 168 Yardstick is installed (``~/yardstick`` if the framework is installed
 169 by following the commands above):
 170
 171 ::
 172
 173   export YARD_IMG_ARCH="amd64"
 174   sudo echo "Defaults env_keep += \"YARD_IMG_ARCH\"" >> /etc/sudoers
 175   sudo ./tools/yardstick-img-modify tools/ubuntu-server-cloudimg-modify.sh
 176
 177 **Warning:** the script will create files by default in:
 178 ``/tmp/workspace/yardstick`` and the files will be owned by root!
 179 If you are building this guest image in inside a docker container make sure the
 180 container is granted with privilege.
 181 The created image can be added to OpenStack using the ``glance image-create`` or
 182 via the OpenStack Dashboard.
 183
 184 Example command:
 185
 186 ::
 187
 188   glance --os-image-api-version 1 image-create \
 189   --name yardstick-trusty-server --is-public true \
 190   --disk-format qcow2 --container-format bare \
 191   --file /tmp/workspace/yardstick/yardstick-trusty-server.img
 192
 193
 194 Yardstick default key pair
 195 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 196 Yardstick uses a SSH key pair to connect to the guest image. This key pair can
 197 be found in the ``resources/files`` directory. To run the ``ping-hot.yaml`` test
 198 sample, this key pair needs to be imported to the OpenStack environment.
 199
 200
 201 Examples and verifying the install
 202 ----------------------------------
 203
 204 It is recommended to verify that Yardstick was installed successfully
 205 by executing some simple commands and test samples. Before executing yardstick
 206 test cases make sure yardstick flavor and building yardstick-trusty-server
 207 image can be found in glance and openrc file is sourced. Below is an example
 208 invocation of yardstick help command and ping.py test sample:
 209 ::
 210
 211   yardstick –h
 212   yardstick task start samples/ping.yaml
 213
 214 Each testing tool supported by Yardstick has a sample configuration file.
 215 These configuration files can be found in the **samples** directory.
 216
 217 Default location for the output is ``/tmp/yardstick.out``.
 218
 219
 220 Deploy InfluxDB and Grafana locally
 221 ------------------------------------
 222
 223 .. pull docker images
 224
 225 Pull docker images
 226
 227 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 228
 229 ::
 230
 231   docker pull tutum/influxdb
 232   docker pull grafana/grafana
 233
 234 Run influxdb and config
 235 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 236 Run influxdb
 237 ::
 238
 239   docker run -d --name influxdb \
 240   -p 8083:8083 -p 8086:8086 --expose 8090 --expose 8099 \
 241   tutum/influxdb
 242   docker exec -it influxdb bash
 243
 244 Config influxdb
 245 ::
 246
 247   influx
 248   >CREATE USER root WITH PASSWORD 'root' WITH ALL PRIVILEGES
 249   >CREATE DATABASE yardstick;
 250   >use yardstick;
 251   >show MEASUREMENTS;
 252
 253 Run grafana and config
 254 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 255 Run grafana
 256 ::
 257
 258   docker run -d --name grafana -p 3000:3000 grafana/grafana
 259
 260 Config grafana
 261 ::
 262
 263   http://{YOUR_IP_HERE}:3000
 264   log on using admin/admin and config database resource to be {YOUR_IP_HERE}:8086
 265
 266 .. image:: images/Grafana_config.png
 267    :width: 800px
 268    :alt: Grafana data source configration
 269
 270 Config yardstick conf
 271 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 272 cp ./etc/yardstick/yardstick.conf.sample /etc/yardstick/yardstick.conf
 273
 274 vi /etc/yardstick/yardstick.conf
 275 Config yardstick.conf
 276 ::
 277
 278   [DEFAULT]
 279   debug = True
 280   dispatcher = influxdb
 281
 282   [dispatcher_influxdb]
 283   timeout = 5
 284   target = http://{YOUR_IP_HERE}:8086
 285   db_name = yardstick
 286   username = root
 287   password = root
 288
 289 Now you can run yardstick test cases and store the results in influxdb
 290 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 291
 292
 293 Create a test suite for yardstick
 294 ------------------------------------
 295
 296 A test suite in yardstick is a yaml file which include one or more test cases.
 297 Yardstick is able to support running test suite task, so you can customize you
 298 own test suite and run it in one task.
 299
 300 "tests/opnfv/test_suites" is where yardstick put ci test-suite. A typical test
 301 suite is like below:
 302
 303 fuel_test_suite.yaml
 304
 305 ::
 306
 307   ---
 308   # Fuel integration test task suite
 309
 310   schema: "yardstick:suite:0.1"
 311
 312   name: "fuel_test_suite"
 313   test_cases_dir: "samples/"
 314   test_cases:
 315   -
 316     file_name: ping.yaml
 317   -
 318     file_name: iperf3.yaml
 319
 320 As you can see, there are two test cases in fuel_test_suite, the syntax is simple
 321 here, you must specify the schema and the name, then you just need to list the
 322 test cases in the tag "test_cases" and also mark their relative directory in the
 323 tag "test_cases_dir".
 324
 325 Yardstick test suite also support constraints and task args for each test suite.
 326 Here is another sample to show this, which is digested from one big test suite.
 327
 328 os-nosdn-nofeature-ha.yaml
 329
 330 ::
 331
 332  ---
 333
 334  schema: "yardstick:suite:0.1"
 335
 336  name: "os-nosdn-nofeature-ha"
 337  test_cases_dir: "tests/opnfv/test_cases/"
 338  test_cases:
 339  -
 340      file_name: opnfv_yardstick_tc002.yaml
 341  -
 342      file_name: opnfv_yardstick_tc005.yaml
 343  -
 344      file_name: opnfv_yardstick_tc043.yaml
 345         constraint:
 346            installer: compass
 347            pod: huawei-pod1
 348         task_args:
 349            huawei-pod1: '{"pod_info": "etc/yardstick/.../pod.yaml",
 350            "host": "node4.LF","target": "node5.LF"}'
 351
 352 As you can see in test case "opnfv_yardstick_tc043.yaml", there are two tags, "constraint" and
 353 "task_args". "constraint" is where you can specify which installer or pod it can be run in
 354 the ci environment. "task_args" is where you can 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 suite yaml file
 357 and add test cases and constraint or task arguments if necessary.
 358