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