1 .. This work is licensed under a Creative Commons Attribution 4.0 International
3 .. http://creativecommons.org/licenses/by/4.0
4 .. (c) OPNFV, Ericsson AB, Huawei Technologies Co.,Ltd and others.
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.
16 To use Yardstick you should have access to an OpenStack environment,
17 with at least Nova, Neutron, Glance, Keystone and Heat installed.
19 The steps needed to run Yardstick are:
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.
30 Installing Yardstick on Ubuntu 14.04
31 ------------------------------------
33 .. _install-framework:
35 You can install Yardstick framework directly on Ubuntu 14.04 or in an Ubuntu
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:
44 docker pull ubuntu:14.04
46 Installing Yardstick framework
47 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
52 sudo apt-get update && sudo apt-get install -y \
67 Create a python virtual environment, source it and update setuptools:
71 virtualenv ~/yardstick_venv
72 source ~/yardstick_venv/bin/activate
73 easy_install -U setuptools
75 Download source code and install python dependencies:
79 git clone https://gerrit.opnfv.org/gerrit/yardstick
81 python setup.py install
83 A Youtube video tutorial on this installation mode is available
84 at: http://www.youtube.com/watch?v=4S4izNolmR0
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
91 Installing Yardstick using Docker
92 ---------------------------------
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.
99 Yardstick-stable image
100 ^^^^^^^^^^^^^^^^^^^^^^
101 Pull the Yardstick-stable Docker image from Docker hub:
105 docker pull opnfv/yardstick:stable
107 Run the Docker image:
111 docker run --privileged=true -it openfv/yardstick /bin/bash
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.
120 OpenStack parameters and credentials
121 ------------------------------------
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.
129 Create yardstick-flavor:
133 nova flavor-create yardstick-flavor 100 512 3 1
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``.
142 Credential environment variables in the *openrc* file have to include at least:
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.
158 Also you may need install several additional packages to use this tool, by
159 follwing the commands below:
163 apt-get update && apt-get install -y \
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):
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
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.
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
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.
201 Examples and verifying the install
202 ----------------------------------
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:
212 yardstick task start samples/ping.yaml
214 Each testing tool supported by Yardstick has a sample configuration file.
215 These configuration files can be found in the **samples** directory.
217 Default location for the output is ``/tmp/yardstick.out``.
220 Deploy InfluxDB and Grafana locally
221 ------------------------------------
223 .. pull docker images
227 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
231 docker pull tutum/influxdb
232 docker pull grafana/grafana
234 Run influxdb and config
235 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
239 docker run -d --name influxdb \
240 -p 8083:8083 -p 8086:8086 --expose 8090 --expose 8099 \
242 docker exec -it influxdb bash
248 >CREATE USER root WITH PASSWORD 'root' WITH ALL PRIVILEGES
249 >CREATE DATABASE yardstick;
253 Run grafana and config
254 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
258 docker run -d --name grafana -p 3000:3000 grafana/grafana
263 http://{YOUR_IP_HERE}:3000
264 log on using admin/admin and config database resource to be {YOUR_IP_HERE}:8086
266 .. image:: images/Grafana_config.png
268 :alt: Grafana data source configration
270 Config yardstick conf
271 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
272 cp ./etc/yardstick/yardstick.conf.sample /etc/yardstick/yardstick.conf
274 vi /etc/yardstick/yardstick.conf
275 Config yardstick.conf
280 dispatcher = influxdb
282 [dispatcher_influxdb]
284 target = http://{YOUR_IP_HERE}:8086
289 Now you can run yardstick test cases and store the results in influxdb
290 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
293 Create a test suite for yardstick
294 ------------------------------------
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.
300 "tests/opnfv/test_suites" is where yardstick put ci test-suite. A typical test
308 # Fuel integration test task suite
310 schema: "yardstick:suite:0.1"
312 name: "fuel_test_suite"
313 test_cases_dir: "samples/"
318 file_name: iperf3.yaml
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".
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.
328 os-nosdn-nofeature-ha.yaml
334 schema: "yardstick:suite:0.1"
336 name: "os-nosdn-nofeature-ha"
337 test_cases_dir: "tests/opnfv/test_cases/"
340 file_name: opnfv_yardstick_tc002.yaml
342 file_name: opnfv_yardstick_tc005.yaml
344 file_name: opnfv_yardstick_tc043.yaml
349 huawei-pod1: '{"pod_info": "etc/yardstick/.../pod.yaml",
350 "host": "node4.LF","target": "node5.LF"}'
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.
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.