docs/testing/user/userguide/04-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 ======================
   7 Yardstick Installation
   8 ======================
   9
  10
  11 Yardstick supports installation by Docker or directly in Ubuntu. The
  12 installation procedure for Docker and direct installation are detailed in
  13 the sections below.
  14
  15 To use Yardstick you should have access to an OpenStack environment, with at
  16 least Nova, Neutron, Glance, Keystone and Heat installed.
  17
  18 The steps needed to run Yardstick are:
  19
  20 1. Install Yardstick.
  21 2. Load OpenStack environment variables.
  22 3. Create Yardstick flavor.
  23 4. Build a guest image and load it into the OpenStack environment.
  24 5. Create the test configuration ``.yaml`` file and run the test case/suite.
  25
  26
  27 Prerequisites
  28 -------------
  29
  30 The OPNFV deployment is out of the scope of this document and can be found in
  31 `User Guide & Configuration Guide`_. The OPNFV platform is considered as the
  32 System Under Test (SUT) in this document.
  33
  34 Several prerequisites are needed for Yardstick:
  35
  36 1. A Jumphost to run Yardstick on
  37 2. A Docker daemon or a virtual environment installed on the Jumphost
  38 3. A public/external network created on the SUT
  39 4. Connectivity from the Jumphost to the SUT public/external network
  40
  41 .. note:: *Jumphost* refers to any server which meets the previous
  42 requirements. Normally it is the same server from where the OPNFV
  43 deployment has been triggered.
  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:: If your Jumphost is operating behind a company http proxy and/or
  51 Firewall, please first consult `Proxy Support`_ section which is towards the
  52 end of this document. That section details some tips/tricks which *may* be of
  53 help in a proxified environment.
  54
  55
  56 Install Yardstick using Docker (first option) (**recommended**)
  57 ---------------------------------------------------------------
  58
  59 Yardstick has a Docker image. It is recommended to use this Docker image to run
  60 Yardstick test.
  61
  62 Prepare the Yardstick container
  63 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  64
  65 Install docker on your guest system with the following command, if not done
  66 yet::
  67
  68    wget -qO- https://get.docker.com/ | sh
  69
  70 Pull the Yardstick Docker image (``opnfv/yardstick``) from the public dockerhub
  71 registry under the OPNFV account in dockerhub_, with the following docker
  72 command::
  73
  74    sudo -EH docker pull opnfv/yardstick:stable
  75
  76 After pulling the Docker image, check that it is available with the
  77 following docker command::
  78
  79    [yardsticker@jumphost ~]$ docker images
  80    REPOSITORY         TAG       IMAGE ID        CREATED      SIZE
  81    opnfv/yardstick    stable    a4501714757a    1 day ago    915.4 MB
  82
  83 Run the Docker image to get a Yardstick container::
  84
  85    docker run -itd --privileged -v /var/run/docker.sock:/var/run/docker.sock \
  86       -p 8888:5000 --name yardstick opnfv/yardstick:stable
  87
  88 .. table:: Description of the parameters used with ``docker run`` command
  89
  90    ======================= ====================================================
  91    Parameters              Detail
  92    ======================= ====================================================
  93    -itd                    -i: interactive, Keep STDIN open even if not
  94                            attached
  95                            -t: allocate a pseudo-TTY detached mode, in the
  96                            background
  97    ======================= ====================================================
  98    --privileged            If you want to build ``yardstick-image`` in
  99                            Yardstick container, this parameter is needed
 100    ======================= ====================================================
 101    -p 8888:5000            Redirect the a host port (8888) to a container port
 102                            (5000)
 103    ======================= ====================================================
 104    -v /var/run/docker.sock If you want to use yardstick env grafana/influxdb to
 105    :/var/run/docker.sock   create a grafana/influxdb container out of Yardstick
 106                            container
 107    ======================= ====================================================
 108    --name yardstick        The name for this container
 109
 110
 111 Configure the Yardstick container environment
 112 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 113
 114 There are three ways to configure environments for running Yardstick, explained
 115 in the following sections. Before that, access the Yardstick container::
 116
 117    docker exec -it yardstick /bin/bash
 118
 119 and then configure Yardstick environments in the Yardstick container.
 120
 121 Using the CLI command ``env prepare`` (first way) (**recommended**)
 122 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 123
 124 In the Yardstick container, the Yardstick repository is located in the
 125 ``/home/opnfv/repos`` directory. Yardstick provides a CLI to prepare OpenStack
 126 environment variables and create Yardstick flavor and guest images
 127 automatically::
 128
 129    yardstick env prepare
 130
 131 .. note:: Since Euphrates release, the above command will not be able to
 132 automatically configure the ``/etc/yardstick/openstack.creds`` file. So before
 133 running the above command, it is necessary to create the
 134 ``/etc/yardstick/openstack.creds`` file and save OpenStack environment
 135 variables into it manually. If you have the openstack credential file saved
 136 outside the Yardstick Docker container, you can do this easily by mapping the
 137 credential file into Yardstick container using::
 138
 139    '-v /path/to/credential_file:/etc/yardstick/openstack.creds'
 140
 141 when running the Yardstick container. For details of the required OpenStack
 142 environment variables please refer to section `Export OpenStack environment
 143 variables`_.
 144
 145 The ``env prepare`` command may take up to 6-8 minutes to finish building
 146 yardstick-image and other environment preparation. Meanwhile if you wish to
 147 monitor the env prepare process, you can enter the Yardstick container in a new
 148 terminal window and execute the following command::
 149
 150   tail -f /var/log/yardstick/uwsgi.log
 151
 152
 153 Manually exporting the env variables and initializing OpenStack (second way)
 154 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 155
 156 Export OpenStack environment variables
 157 ######################################
 158
 159 Before running Yardstick it is necessary to export OpenStack environment
 160 variables::
 161
 162    source openrc
 163
 164 Environment variables in the ``openrc`` file have to include at least::
 165
 166    OS_AUTH_URL
 167    OS_USERNAME
 168    OS_PASSWORD
 169    OS_TENANT_NAME
 170    EXTERNAL_NETWORK
 171
 172 A sample ``openrc`` file may look like this::
 173
 174   export OS_PASSWORD=console
 175   export OS_TENANT_NAME=admin
 176   export OS_AUTH_URL=http://172.16.1.222:35357/v2.0
 177   export OS_USERNAME=admin
 178   export OS_VOLUME_API_VERSION=2
 179   export EXTERNAL_NETWORK=net04_ext
 180
 181
 182 Manual creation of Yardstick flavor and guest images
 183 ####################################################
 184
 185 Before executing Yardstick test cases, make sure that Yardstick flavor and
 186 guest image are available in OpenStack. Detailed steps about creating the
 187 Yardstick flavor and building the Yardstick guest image can be found below.
 188
 189 Most of the sample test cases in Yardstick are using an OpenStack flavor called
 190 ``yardstick-flavor`` which deviates from the OpenStack standard ``m1.tiny``
 191 flavor by the disk size; instead of 1GB it has 3GB. Other parameters are the
 192 same as in ``m1.tiny``.
 193
 194 Create ``yardstick-flavor``::
 195
 196    openstack flavor create --disk 3 --vcpus 1 --ram 512 --swap 100 \
 197       yardstick-flavor
 198
 199 Most of the sample test cases in Yardstick are using a guest image called
 200 ``yardstick-image`` which deviates from an Ubuntu Cloud Server image
 201 containing all the required tools to run test cases supported by Yardstick.
 202 Yardstick has a tool for building this custom image. It is necessary to have
 203 ``sudo`` rights to use this tool.
 204
 205 Also you may need install several additional packages to use this tool, by
 206 follwing the commands below::
 207
 208    sudo -EH apt-get update && sudo -EH apt-get install -y qemu-utils kpartx
 209
 210 This image can be built using the following command in the directory where
 211 Yardstick is installed::
 212
 213    export YARD_IMG_ARCH='amd64'
 214    echo "Defaults env_keep += \'YARD_IMG_ARCH\'" | sudo tee --append \
 215       /etc/sudoers > /dev/null
 216    sudo -EH tools/yardstick-img-modify tools/ubuntu-server-cloudimg-modify.sh
 217
 218 .. warning:: Before building the guest image inside the Yardstick container,
 219 make sure the container is granted with privilege. The script will create files
 220 by default in ``/tmp/workspace/yardstick`` and the files will be owned by root.
 221
 222 The created image can be added to OpenStack using the OpenStack client or via
 223 the OpenStack Dashboard::
 224
 225    openstack image create --disk-format qcow2 --container-format bare \
 226       --public --file /tmp/workspace/yardstick/yardstick-image.img \
 227        yardstick-image
 228
 229
 230 Some Yardstick test cases use a `Cirros 0.3.5`_ image and/or a `Ubuntu 16.04`_
 231 image. Add Cirros and Ubuntu images to OpenStack::
 232
 233    openstack image create --disk-format qcow2 --container-format bare \
 234       --public --file $cirros_image_file cirros-0.3.5
 235    openstack image create --disk-format qcow2 --container-format bare \
 236       --file $ubuntu_image_file Ubuntu-16.04
 237
 238
 239 Automatic initialization of OpenStack (third way)
 240 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 241
 242 Similar to the second way, the first step is also to
 243 `Export OpenStack environment variables`_. Then the following steps should be
 244 done.
 245
 246 Automatic creation of Yardstick flavor and guest images
 247 #######################################################
 248
 249 Yardstick has a script for automatically creating Yardstick flavor and building
 250 Yardstick guest images. This script is mainly used for CI and can be also used
 251 in the local environment::
 252
 253    source $YARDSTICK_REPO_DIR/tests/ci/load_images.sh
 254
 255
 256 The Yardstick container GUI
 257 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 258
 259 In Euphrates release, Yardstick implemented a GUI for Yardstick Docker
 260 container. After booting up Yardstick container, you can visit the GUI at
 261 ``<container_host_ip>:8888/gui/index.html``.
 262
 263 For usage of Yardstick GUI, please watch our demo video at
 264 `Yardstick GUI demo`_.
 265
 266 .. note:: The Yardstick GUI is still in development, the GUI layout and
 267 features may change.
 268
 269 Delete the Yardstick container
 270 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 271
 272 If you want to uninstall Yardstick, just delete the Yardstick container::
 273
 274    sudo docker stop yardstick && docker rm yardstick
 275
 276
 277
 278 Install Yardstick directly in Ubuntu (second option)
 279 ----------------------------------------------------
 280
 281 .. _install-framework:
 282
 283 Alternatively you can install Yardstick framework directly in Ubuntu or in an
 284 Ubuntu Docker image. No matter which way you choose to install Yardstick, the
 285 following installation steps are identical.
 286
 287 If you choose to use the Ubuntu Docker image, you can pull the Ubuntu
 288 Docker image from Docker hub::
 289
 290    sudo -EH docker pull ubuntu:16.04
 291
 292
 293 Install Yardstick
 294 ^^^^^^^^^^^^^^^^^
 295
 296 Prerequisite preparation::
 297
 298    sudo -EH apt-get update && sudo -EH apt-get install -y \
 299       git python-setuptools python-pip
 300    sudo -EH easy_install -U setuptools==30.0.0
 301    sudo -EH pip install appdirs==1.4.0
 302    sudo -EH pip install virtualenv
 303
 304 Create a virtual environment::
 305
 306    virtualenv ~/yardstick_venv
 307    export YARDSTICK_VENV=~/yardstick_venv
 308    source ~/yardstick_venv/bin/activate
 309
 310 Download the source code and install Yardstick from it::
 311
 312    git clone https://gerrit.opnfv.org/gerrit/yardstick
 313    export YARDSTICK_REPO_DIR=~/yardstick
 314    cd ~/yardstick
 315    sudo -EH ./install.sh
 316
 317
 318 Configure the Yardstick environment (**Todo**)
 319 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 320
 321 For installing Yardstick directly in Ubuntu, the ``yardstick env`` command is
 322 not available. You need to prepare OpenStack environment variables and create
 323 Yardstick flavor and guest images manually.
 324
 325
 326 Uninstall Yardstick
 327 ^^^^^^^^^^^^^^^^^^^
 328
 329 For uninstalling Yardstick, just delete the virtual environment::
 330
 331    rm -rf ~/yardstick_venv
 332
 333
 334 Install Yardstick directly in OpenSUSE
 335 --------------------------------------
 336
 337 .. _install-framework:
 338
 339 You can install Yardstick framework directly in OpenSUSE.
 340
 341
 342 Install Yardstick
 343 ^^^^^^^^^^^^^^^^^
 344
 345 Prerequisite preparation::
 346
 347    sudo -EH zypper -n install -y gcc \
 348       wget \
 349       git \
 350       sshpass \
 351       qemu-tools \
 352       kpartx \
 353       libffi-devel \
 354       libopenssl-devel \
 355       python \
 356       python-devel \
 357       python-virtualenv \
 358       libxml2-devel \
 359       libxslt-devel \
 360       python-setuptools-git
 361
 362 Create a virtual environment::
 363
 364    virtualenv ~/yardstick_venv
 365    export YARDSTICK_VENV=~/yardstick_venv
 366    source ~/yardstick_venv/bin/activate
 367    sudo -EH easy_install -U setuptools
 368
 369 Download the source code and install Yardstick from it::
 370
 371    git clone https://gerrit.opnfv.org/gerrit/yardstick
 372    export YARDSTICK_REPO_DIR=~/yardstick
 373    cd yardstick
 374    sudo -EH python setup.py install
 375    sudo -EH pip install -r requirements.txt
 376
 377 Install missing python modules::
 378
 379    sudo -EH pip install pyyaml \
 380       oslo_utils \
 381       oslo_serialization \
 382       oslo_config \
 383       paramiko \
 384       python.heatclient \
 385       python.novaclient \
 386       python.glanceclient \
 387       python.neutronclient \
 388       scp \
 389       jinja2
 390
 391
 392 Configure the Yardstick environment
 393 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 394
 395 Source the OpenStack environment variables::
 396
 397    source DEVSTACK_DIRECTORY/openrc
 398
 399 Export the Openstack external network. The default installation of Devstack
 400 names the external network public::
 401
 402    export EXTERNAL_NETWORK=public
 403    export OS_USERNAME=demo
 404
 405 Change the API version used by Yardstick to v2.0 (the devstack openrc sets it
 406 to v3)::
 407
 408    export OS_AUTH_URL=http://PUBLIC_IP_ADDRESS:5000/v2.0
 409
 410
 411 Uninstall Yardstick
 412 ^^^^^^^^^^^^^^^^^^^
 413
 414 For unistalling Yardstick, just delete the virtual environment::
 415
 416    rm -rf ~/yardstick_venv
 417
 418
 419 Verify the installation
 420 -----------------------
 421
 422 It is recommended to verify that Yardstick was installed successfully
 423 by executing some simple commands and test samples. Before executing Yardstick
 424 test cases make sure ``yardstick-flavor`` and ``yardstick-image`` can be found
 425 in OpenStack and the ``openrc`` file is sourced. Below is an example invocation
 426 of Yardstick ``help`` command and ``ping.py`` test sample::
 427
 428    yardstick -h
 429    yardstick task start samples/ping.yaml
 430
 431 .. note:: The above commands could be run in both the Yardstick container and
 432 the Ubuntu directly.
 433
 434 Each testing tool supported by Yardstick has a sample configuration file.
 435 These configuration files can be found in the ``samples`` directory.
 436
 437 Default location for the output is ``/tmp/yardstick.out``.
 438
 439
 440 Deploy InfluxDB and Grafana using Docker
 441 ----------------------------------------
 442
 443 Without InfluxDB, Yardstick stores results for running test case in the file
 444 ``/tmp/yardstick.out``. However, it's inconvenient to retrieve and display
 445 test results. So we will show how to use InfluxDB to store data and use
 446 Grafana to display data in the following sections.
 447
 448 Automatic deployment of InfluxDB and Grafana containers (**recommended**)
 449 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 450
 451 Firstly, enter the Yardstick container::
 452
 453    sudo -EH docker exec -it yardstick /bin/bash
 454
 455 Secondly, create InfluxDB container and configure with the following command::
 456
 457    yardstick env influxdb
 458
 459 Thirdly, create and configure Grafana container::
 460
 461    yardstick env grafana
 462
 463 Then you can run a test case and visit http://host_ip:3000
 464 (``admin``/``admin``) to see the results.
 465
 466 .. note:: Executing ``yardstick env`` command to deploy InfluxDB and Grafana
 467 requires Jumphost's docker API version => 1.24. Run the following command to
 468 check the docker API version on the Jumphost::
 469
 470    docker version
 471
 472
 473 Manual deployment of InfluxDB and Grafana containers
 474 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 475
 476 You can also deploy influxDB and Grafana containers manually on the Jumphost.
 477 The following sections show how to do.
 478
 479 Pull docker images::
 480
 481    sudo -EH docker pull tutum/influxdb
 482    sudo -EH docker pull grafana/grafana
 483
 484 Run influxDB::
 485
 486    sudo -EH docker run -d --name influxdb \
 487       -p 8083:8083 -p 8086:8086 --expose 8090 --expose 8099 \
 488       tutum/influxdb
 489    docker exec -it influxdb bash
 490
 491 Configure influxDB::
 492
 493    influx
 494       >CREATE USER root WITH PASSWORD 'root' WITH ALL PRIVILEGES
 495       >CREATE DATABASE yardstick;
 496       >use yardstick;
 497       >show MEASUREMENTS;
 498
 499 Run Grafana::
 500
 501    sudo -EH docker run -d --name grafana -p 3000:3000 grafana/grafana
 502
 503 Log on http://{YOUR_IP_HERE}:3000 using ``admin``/``admin`` and configure
 504 database resource to be ``{YOUR_IP_HERE}:8086``.
 505
 506 .. image:: images/Grafana_config.png
 507    :width: 800px
 508    :alt: Grafana data source configuration
 509
 510 Configure ``yardstick.conf``::
 511
 512    sudo -EH docker exec -it yardstick /bin/bash
 513    sudo cp etc/yardstick/yardstick.conf.sample /etc/yardstick/yardstick.conf
 514    sudo vi /etc/yardstick/yardstick.conf
 515
 516 Modify ``yardstick.conf``::
 517
 518    [DEFAULT]
 519    debug = True
 520    dispatcher = influxdb
 521
 522    [dispatcher_influxdb]
 523    timeout = 5
 524    target = http://{YOUR_IP_HERE}:8086
 525    db_name = yardstick
 526    username = root
 527    password = root
 528
 529 Now you can run Yardstick test cases and store the results in influxDB.
 530
 531
 532 Deploy InfluxDB and Grafana directly in Ubuntu (**Todo**)
 533 ---------------------------------------------------------
 534
 535
 536 Yardstick common CLI
 537 --------------------
 538
 539 List test cases
 540 ^^^^^^^^^^^^^^^
 541
 542 ``yardstick testcase list``: This command line would list all test cases in
 543 Yardstick. It would show like below::
 544
 545    +---------------------------------------------------------------------------------------
 546    | Testcase Name         | Description
 547    +---------------------------------------------------------------------------------------
 548    | opnfv_yardstick_tc001 | Measure network throughput using pktgen
 549    | opnfv_yardstick_tc002 | measure network latency using ping
 550    | opnfv_yardstick_tc005 | Measure Storage IOPS, throughput and latency using fio.
 551    ...
 552    +---------------------------------------------------------------------------------------
 553
 554
 555 Show a test case config file
 556 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 557
 558 Take opnfv_yardstick_tc002 for an example. This test case measure network
 559 latency. You just need to type in ``yardstick testcase show
 560 opnfv_yardstick_tc002``, and the console would show the config yaml of this
 561 test case::
 562
 563    ---
 564
 565    schema: "yardstick:task:0.1"
 566    description: >
 567       Yardstick TC002 config file;
 568       measure network latency using ping;
 569
 570    {% set image = image or "cirros-0.3.5" %}
 571
 572    {% set provider = provider or none %}
 573    {% set physical_network = physical_network or 'physnet1' %}
 574    {% set segmentation_id = segmentation_id or none %}
 575    {% set packetsize = packetsize or 100 %}
 576
 577    scenarios:
 578    {% for i in range(2) %}
 579    -
 580     type: Ping
 581     options:
 582       packetsize: {{packetsize}}
 583     host: athena.demo
 584     target: ares.demo
 585
 586     runner:
 587       type: Duration
 588       duration: 60
 589       interval: 10
 590
 591     sla:
 592       max_rtt: 10
 593       action: monitor
 594    {% endfor %}
 595
 596    context:
 597     name: demo
 598     image: {{image}}
 599     flavor: yardstick-flavor
 600     user: cirros
 601
 602     placement_groups:
 603       pgrp1:
 604         policy: "availability"
 605
 606     servers:
 607       athena:
 608         floating_ip: true
 609         placement: "pgrp1"
 610       ares:
 611         placement: "pgrp1"
 612
 613     networks:
 614       test:
 615         cidr: '10.0.1.0/24'
 616         {% if provider == "vlan" %}
 617         provider: {{provider}}
 618         physical_network: {{physical_network}}å
 619           {% if segmentation_id %}
 620         segmentation_id: {{segmentation_id}}
 621           {% endif %}
 622         {% endif %}
 623
 624
 625 Start a task to run yardstick test case
 626 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 627
 628 If you want run a test case, then you need to use ``yardstick task start
 629 <test_case_path>`` this command support some parameters as below::
 630
 631    +---------------------+--------------------------------------------------+
 632    | Parameters          | Detail                                           |
 633    +=====================+==================================================+
 634    | -d                  | show debug log of yardstick running              |
 635    |                     |                                                  |
 636    +---------------------+--------------------------------------------------+
 637    | --task-args         | If you want to customize test case parameters,   |
 638    |                     | use "--task-args" to pass the value. The format  |
 639    |                     | is a json string with parameter key-value pair.  |
 640    |                     |                                                  |
 641    +---------------------+--------------------------------------------------+
 642    | --task-args-file    | If you want to use yardstick                     |
 643    |                     | env prepare command(or                           |
 644    |                     | related API) to load the                         |
 645    +---------------------+--------------------------------------------------+
 646    | --parse-only        |                                                  |
 647    |                     |                                                  |
 648    |                     |                                                  |
 649    +---------------------+--------------------------------------------------+
 650    | --output-file \     | Specify where to output the log. if not pass,    |
 651    | OUTPUT_FILE_PATH    | the default value is                             |
 652    |                     | "/tmp/yardstick/yardstick.log"                   |
 653    |                     |                                                  |
 654    +---------------------+--------------------------------------------------+
 655    | --suite \           | run a test suite, TEST_SUITE_PATH specify where  |
 656    | TEST_SUITE_PATH     | the test suite locates                           |
 657    |                     |                                                  |
 658    +---------------------+--------------------------------------------------+
 659
 660
 661 Run Yardstick in a local environment
 662 ------------------------------------
 663
 664 We also have a guide about how to run Yardstick in a local environment.
 665 This work is contributed by Tapio Tallgren.
 666 You can find this guide at `How to run Yardstick in a local environment`_.
 667
 668
 669 Create a test suite for Yardstick
 670 ------------------------------------
 671
 672 A test suite in yardstick is a yaml file which include one or more test cases.
 673 Yardstick is able to support running test suite task, so you can customize your
 674 own test suite and run it in one task.
 675
 676 ``tests/opnfv/test_suites`` is the folder where Yardstick puts CI test suite.
 677 A typical test suite is like below (the ``fuel_test_suite.yaml`` example)::
 678
 679    ---
 680    # Fuel integration test task suite
 681
 682    schema: "yardstick:suite:0.1"
 683
 684    name: "fuel_test_suite"
 685    test_cases_dir: "samples/"
 686    test_cases:
 687    -
 688     file_name: ping.yaml
 689    -
 690     file_name: iperf3.yaml
 691
 692 As you can see, there are two test cases in the ``fuel_test_suite.yaml``. The
 693 ``schema`` and the ``name`` must be specified. The test cases should be listed
 694 via the tag ``test_cases`` and their relative path is also marked via the tag
 695 ``test_cases_dir``.
 696
 697 Yardstick test suite also supports constraints and task args for each test
 698 case. Here is another sample (the ``os-nosdn-nofeature-ha.yaml`` example) to
 699 show this, which is digested from one big test suite::
 700
 701    ---
 702
 703    schema: "yardstick:suite:0.1"
 704
 705    name: "os-nosdn-nofeature-ha"
 706    test_cases_dir: "tests/opnfv/test_cases/"
 707    test_cases:
 708    -
 709      file_name: opnfv_yardstick_tc002.yaml
 710    -
 711      file_name: opnfv_yardstick_tc005.yaml
 712    -
 713      file_name: opnfv_yardstick_tc043.yaml
 714         constraint:
 715            installer: compass
 716            pod: huawei-pod1
 717         task_args:
 718            huawei-pod1: '{"pod_info": "etc/yardstick/.../pod.yaml",
 719            "host": "node4.LF","target": "node5.LF"}'
 720
 721 As you can see in test case ``opnfv_yardstick_tc043.yaml``, there are two
 722 tags, ``constraint`` and ``task_args``. ``constraint`` is to specify which
 723 installer or pod it can be run in the CI environment. ``task_args`` is to
 724 specify the task arguments for each pod.
 725
 726 All in all, to create a test suite in Yardstick, you just need to create a
 727 yaml file and add test cases, constraint or task arguments if necessary.
 728
 729
 730 Proxy Support
 731 -------------
 732
 733 To configure the Jumphost to access Internet through a proxy its necessary to
 734 export several variables to the environment, contained in the following
 735 script::
 736
 737    #!/bin/sh
 738    _proxy=<proxy_address>
 739    _proxyport=<proxy_port>
 740    _ip=$(hostname -I | awk '{print $1}')
 741
 742    export ftp_proxy=http://$_proxy:$_proxyport
 743    export FTP_PROXY=http://$_proxy:$_proxyport
 744    export http_proxy=http://$_proxy:$_proxyport
 745    export HTTP_PROXY=http://$_proxy:$_proxyport
 746    export https_proxy=http://$_proxy:$_proxyport
 747    export HTTPS_PROXY=http://$_proxy:$_proxyport
 748    export no_proxy=127.0.0.1,localhost,$_ip,$(hostname),<.localdomain>
 749    export NO_PROXY=127.0.0.1,localhost,$_ip,$(hostname),<.localdomain>
 750
 751 To enable Internet access from a container using ``docker``, depends on the OS
 752 version. On Ubuntu 14.04 LTS, which uses SysVinit, ``/etc/default/docker`` must
 753 be modified::
 754
 755    .......
 756    # If you need Docker to use an HTTP proxy, it can also be specified here.
 757    export http_proxy="http://<proxy_address>:<proxy_port>/"
 758    export https_proxy="https://<proxy_address>:<proxy_port>/"
 759
 760 Then its necessary to restart the ``docker`` service::
 761
 762    sudo -EH service docker restart
 763
 764 In Ubuntu 16.04 LTS, which uses Systemd, its necessary to create a drop-in
 765 directory::
 766
 767    sudo mkdir /etc/systemd/system/docker.service.d
 768
 769 Then, the proxy configuration will be stored in the following file::
 770
 771    # cat /etc/systemd/system/docker.service.d/http-proxy.conf
 772    [Service]
 773    Environment="HTTP_PROXY=https://<proxy_address>:<proxy_port>/"
 774    Environment="HTTPS_PROXY=https://<proxy_address>:<proxy_port>/"
 775    Environment="NO_PROXY=localhost,127.0.0.1,<localaddress>,<.localdomain>"
 776
 777 The changes need to be flushed and the ``docker`` service restarted::
 778
 779    sudo systemctl daemon-reload
 780    sudo systemctl restart docker
 781
 782 Any container is already created won't contain these modifications. If needed,
 783 stop and delete the container::
 784
 785    sudo docker stop yardstick
 786    sudo docker rm yardstick
 787
 788 .. warning:: Be careful, the above ``rm`` command will delete the container
 789 completely. Everything on this container will be lost.
 790
 791 Then follow the previous instructions `Prepare the Yardstick container`_ to
 792 rebuild the Yardstick container.
 793
 794
 795 References
 796 ----------
 797
 798 .. _`User Guide & Configuration Guide`: http://docs.opnfv.org/en/latest/release/userguide.introduction.html
 799 .. _dockerhub: https://hub.docker.com/r/opnfv/yardstick/
 800 .. _`Cirros 0.3.5`: http://download.cirros-cloud.net/0.3.5/cirros-0.3.5-x86_64-disk.img
 801 .. _`Ubuntu 16.04`: https://cloud-images.ubuntu.com/xenial/current/xenial-server-cloudimg-amd64-disk1.img
 802 .. _`Yardstick GUI demo`: https://www.youtube.com/watch?v=M3qbJDp6QBk
 803 .. _`How to run Yardstick in a local environment`: https://wiki.opnfv.org/display/yardstick/How+to+run+Yardstick+in+a+local+environment