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 via a Docker image. The
  13 installation procedure on Ubuntu 14.04 or via the docker image are detailed in
  14 the section below.
  15
  16 To use Yardstick you should have access to an OpenStack environment, with at
  17 least Nova, Neutron, Glance, Keystone and Heat installed.
  18
  19 The steps needed to run Yardstick are:
  20
  21 1. Install Yardstick.
  22 2. Load OpenStack environment variables.
  23 3. Create a Neutron external network.
  24 4. Build Yardstick flavor and a guest image.
  25 5. Load the guest image into the OpenStack environment.
  26 6. Create the test configuration .yaml file.
  27 7. Run the test case.
  28
  29
  30 Prerequisites
  31 -------------
  32
  33 The OPNFV deployment is out of the scope of this document but it can be
  34 found in http://artifacts.opnfv.org/opnfvdocs/colorado/docs/configguide/index.html.
  35 The OPNFV platform is considered as the System Under Test (SUT) in this
  36 document.
  37
  38 Several prerequisites are needed for Yardstick:
  39
  40     #. A Jumphost to run Yardstick on
  41     #. A Docker daemon shall be installed on the Jumphost
  42     #. A public/external network created on the SUT
  43     #. Connectivity from the Jumphost to the SUT public/external network
  44
  45 WARNING: Connectivity from Jumphost is essential and it is of paramount
  46 importance to make sure it is working before even considering to install
  47 and run Yardstick. Make also sure you understand how your networking is
  48 designed to work.
  49
  50 NOTE: **Jumphost** refers to any server which meets the previous
  51 requirements. Normally it is the same server from where the OPNFV
  52 deployment has been triggered previously.
  53
  54 NOTE: If your Jumphost is operating behind a company http proxy and/or
  55 Firewall, please consult first the section `Proxy Support`_, towards
  56 the end of this document. The section details some tips/tricks which
  57 *may* be of help in a proxified environment.
  58
  59
  60 Installing Yardstick on Ubuntu 14.04
  61 ------------------------------------
  62
  63 .. _install-framework:
  64
  65 You can install Yardstick framework directly on Ubuntu 14.04 or in an Ubuntu
  66 14.04 Docker image. No matter which way you choose to install Yardstick
  67 framework, the following installation steps are identical.
  68
  69 If you choose to use the Ubuntu 14.04 Docker image, You can pull the Ubuntu
  70 14.04 Docker image from Docker hub:
  71
  72 ::
  73
  74   docker pull ubuntu:14.04
  75
  76 Installing Yardstick framework
  77 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  78 Download source code and install python dependencies:
  79
  80 ::
  81
  82   git clone https://gerrit.opnfv.org/gerrit/yardstick
  83   cd yardstick
  84   ./install.sh
  85
  86
  87 Installing Yardstick using Docker
  88 ---------------------------------
  89
  90 Yardstick has a Docker image, this Docker image (**Yardstick-stable**)
  91 serves as a replacement for installing the Yardstick framework in a virtual
  92 environment (for example as done in :ref:`install-framework`).
  93 It is recommended to use this Docker image to run Yardstick test.
  94
  95 Pulling the Yardstick Docker image
  96 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  97
  98 .. _dockerhub: https://hub.docker.com/r/opnfv/yardstick/
  99
 100 Pull the Yardstick Docker image ('opnfv/yardstick') from the public dockerhub
 101 registry under the OPNFV account: [dockerhub_], with the following docker
 102 command::
 103
 104   docker pull opnfv/yardstick:stable
 105
 106 After pulling the Docker image, check that it is available with the
 107 following docker command::
 108
 109   [yardsticker@jumphost ~]$ docker images
 110   REPOSITORY         TAG       IMAGE ID        CREATED      SIZE
 111   opnfv/yardstick    stable    a4501714757a    1 day ago    915.4 MB
 112
 113 Run the Docker image:
 114
 115 ::
 116
 117   docker run --privileged=true -it opnfv/yardstick:stable /bin/bash
 118
 119 In the container the Yardstick repository is located in the /home/opnfv/repos
 120 directory.
 121
 122
 123 OpenStack parameters and credentials
 124 ------------------------------------
 125
 126 Environment variables
 127 ^^^^^^^^^^^^^^^^^^^^^
 128 Before running Yardstick it is necessary to export OpenStack environment variables
 129 from the OpenStack *openrc* file (using the ``source`` command) and export the
 130 external network name ``export EXTERNAL_NETWORK="external-network-name"``,
 131 the default name for the external network is ``net04_ext``.
 132
 133 Credential environment variables in the *openrc* file have to include at least:
 134
 135 * OS_AUTH_URL
 136 * OS_USERNAME
 137 * OS_PASSWORD
 138 * OS_TENANT_NAME
 139
 140 A sample openrc file may look like this:
 141
 142 * export OS_PASSWORD=console
 143 * export OS_TENANT_NAME=admin
 144 * export OS_AUTH_URL=http://172.16.1.222:35357/v2.0
 145 * export OS_USERNAME=admin
 146 * export OS_VOLUME_API_VERSION=2
 147 * export EXTERNAL_NETWORK=net04_ext
 148
 149
 150 Yardstick falvor and guest images
 151 ---------------------------------
 152
 153 Before executing Yardstick test cases, make sure that yardstick guest image and
 154 yardstick flavor are available in OpenStack.
 155 Detailed steps about creating yardstick flavor and building yardstick-trusty-server
 156 image can be found below.
 157
 158 Yardstick-flavor
 159 ^^^^^^^^^^^^^^^^
 160 Most of the sample test cases in Yardstick are using an OpenStack flavor called
 161 *yardstick-flavor* which deviates from the OpenStack standard m1.tiny flavor by the
 162 disk size - instead of 1GB it has 3GB. Other parameters are the same as in m1.tiny.
 163
 164 Create yardstick-flavor:
 165
 166 ::
 167
 168   nova flavor-create yardstick-flavor 100 512 3 1
 169
 170
 171 .. _guest-image:
 172
 173 Building a guest image
 174 ^^^^^^^^^^^^^^^^^^^^^^
 175 Most of the sample test cases in Yardstick are using a guest image called
 176 *yardstick-trusty-server* which deviates from an Ubuntu Cloud Server image
 177 containing all the required tools to run test cases supported by Yardstick.
 178 Yardstick has a tool for building this custom image. It is necessary to have
 179 sudo rights to use this tool.
 180
 181 Also you may need install several additional packages to use this tool, by
 182 follwing the commands below:
 183
 184 ::
 185
 186   apt-get update && apt-get install -y \
 187       qemu-utils \
 188       kpartx
 189
 190 This image can be built using the following command while in the directory where
 191 Yardstick is installed (``~/yardstick`` if the framework is installed
 192 by following the commands above):
 193
 194 ::
 195
 196   export YARD_IMG_ARCH="amd64"
 197   sudo echo "Defaults env_keep += \"YARD_IMG_ARCH\"" >> /etc/sudoers
 198   sudo ./tools/yardstick-img-modify tools/ubuntu-server-cloudimg-modify.sh
 199
 200 **Warning:** the script will create files by default in:
 201 ``/tmp/workspace/yardstick`` and the files will be owned by root!
 202
 203 If you are building this guest image in inside a docker container make sure the
 204 container is granted with privilege.
 205
 206 The created image can be added to OpenStack using the ``glance image-create`` or
 207 via the OpenStack Dashboard.
 208
 209 Example command:
 210
 211 ::
 212
 213   glance --os-image-api-version 1 image-create \
 214   --name yardstick-image --is-public true \
 215   --disk-format qcow2 --container-format bare \
 216   --file /tmp/workspace/yardstick/yardstick-image.img
 217
 218 Some Yardstick test cases use a Cirros image, you can find one at
 219 http://download.cirros-cloud.net/0.3.3/cirros-0.3.3-x86_64-disk.img
 220
 221
 222 Automatic flavor and image creation
 223 -----------------------------------
 224 Yardstick has a script for automatic creating yardstick flavor and building
 225 guest images. This script is mainly used in CI, but you can still use it in
 226 your local environment.
 227
 228 Example command:
 229
 230 ::
 231
 232   export YARD_IMG_ARCH="amd64"
 233   sudo echo "Defaults env_keep += \"YARD_IMG_ARCH\"" >> /etc/sudoers
 234   source $YARDSTICK_REPO_DIR/tests/ci/load_images.sh
 235
 236
 237 Yardstick default key pair
 238 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 239 Yardstick uses a SSH key pair to connect to the guest image. This key pair can
 240 be found in the ``resources/files`` directory. To run the ``ping-hot.yaml`` test
 241 sample, this key pair needs to be imported to the OpenStack environment.
 242
 243
 244 Examples and verifying the install
 245 ----------------------------------
 246
 247 It is recommended to verify that Yardstick was installed successfully
 248 by executing some simple commands and test samples. Before executing yardstick
 249 test cases make sure yardstick flavor and building yardstick-trusty-server
 250 image can be found in glance and openrc file is sourced. Below is an example
 251 invocation of yardstick help command and ping.py test sample:
 252 ::
 253
 254   yardstick –h
 255   yardstick task start samples/ping.yaml
 256
 257 Each testing tool supported by Yardstick has a sample configuration file.
 258 These configuration files can be found in the **samples** directory.
 259
 260 Default location for the output is ``/tmp/yardstick.out``.
 261
 262
 263 Deploy InfluxDB and Grafana locally
 264 ------------------------------------
 265
 266 .. pull docker images
 267
 268 Pull docker images
 269
 270 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 271
 272 ::
 273
 274   docker pull tutum/influxdb
 275   docker pull grafana/grafana
 276
 277 Run influxdb and config
 278 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 279 Run influxdb
 280 ::
 281
 282   docker run -d --name influxdb \
 283   -p 8083:8083 -p 8086:8086 --expose 8090 --expose 8099 \
 284   tutum/influxdb
 285   docker exec -it influxdb bash
 286
 287 Config influxdb
 288 ::
 289
 290   influx
 291   >CREATE USER root WITH PASSWORD 'root' WITH ALL PRIVILEGES
 292   >CREATE DATABASE yardstick;
 293   >use yardstick;
 294   >show MEASUREMENTS;
 295
 296 Run grafana and config
 297 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 298 Run grafana
 299 ::
 300
 301   docker run -d --name grafana -p 3000:3000 grafana/grafana
 302
 303 Config grafana
 304 ::
 305
 306   http://{YOUR_IP_HERE}:3000
 307   log on using admin/admin and config database resource to be {YOUR_IP_HERE}:8086
 308
 309 .. image:: images/Grafana_config.png
 310    :width: 800px
 311    :alt: Grafana data source configration
 312
 313 Config yardstick conf
 314 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 315 cp ./etc/yardstick/yardstick.conf.sample /etc/yardstick/yardstick.conf
 316
 317 vi /etc/yardstick/yardstick.conf
 318 Config yardstick.conf
 319 ::
 320
 321   [DEFAULT]
 322   debug = True
 323   dispatcher = influxdb
 324
 325   [dispatcher_influxdb]
 326   timeout = 5
 327   target = http://{YOUR_IP_HERE}:8086
 328   db_name = yardstick
 329   username = root
 330   password = root
 331
 332 Now you can run yardstick test cases and store the results in influxdb
 333 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 334
 335
 336 Create a test suite for yardstick
 337 ------------------------------------
 338
 339 A test suite in yardstick is a yaml file which include one or more test cases.
 340 Yardstick is able to support running test suite task, so you can customize you
 341 own test suite and run it in one task.
 342
 343 "tests/opnfv/test_suites" is where yardstick put ci test-suite. A typical test
 344 suite is like below:
 345
 346 fuel_test_suite.yaml
 347
 348 ::
 349
 350   ---
 351   # Fuel integration test task suite
 352
 353   schema: "yardstick:suite:0.1"
 354
 355   name: "fuel_test_suite"
 356   test_cases_dir: "samples/"
 357   test_cases:
 358   -
 359     file_name: ping.yaml
 360   -
 361     file_name: iperf3.yaml
 362
 363 As you can see, there are two test cases in fuel_test_suite, the syntax is simple
 364 here, you must specify the schema and the name, then you just need to list the
 365 test cases in the tag "test_cases" and also mark their relative directory in the
 366 tag "test_cases_dir".
 367
 368 Yardstick test suite also support constraints and task args for each test case.
 369 Here is another sample to show this, which is digested from one big test suite.
 370
 371 os-nosdn-nofeature-ha.yaml
 372
 373 ::
 374
 375  ---
 376
 377  schema: "yardstick:suite:0.1"
 378
 379  name: "os-nosdn-nofeature-ha"
 380  test_cases_dir: "tests/opnfv/test_cases/"
 381  test_cases:
 382  -
 383      file_name: opnfv_yardstick_tc002.yaml
 384  -
 385      file_name: opnfv_yardstick_tc005.yaml
 386  -
 387      file_name: opnfv_yardstick_tc043.yaml
 388         constraint:
 389            installer: compass
 390            pod: huawei-pod1
 391         task_args:
 392            huawei-pod1: '{"pod_info": "etc/yardstick/.../pod.yaml",
 393            "host": "node4.LF","target": "node5.LF"}'
 394
 395 As you can see in test case "opnfv_yardstick_tc043.yaml", there are two tags, "constraint" and
 396 "task_args". "constraint" is where you can specify which installer or pod it can be run in
 397 the ci environment. "task_args" is where you can specify the task arguments for each pod.
 398
 399 All in all, to create a test suite in yardstick, you just need to create a suite yaml file
 400 and add test cases and constraint or task arguments if necessary.
 401