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 currently supports installation on Ubuntu 14.04 or by using a Docker
13 image. Detailed steps about installing Yardstick using both of these options
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:
21 1. Install Yardstick and create the test configuration .yaml file.
22 2. Build a guest image and load the image into the OpenStack environment.
23 3. Create a Neutron external network and load OpenStack environment variables.
27 Installing Yardstick on Ubuntu 14.04
28 ------------------------------------
30 .. _install-framework:
32 You can install Yardstick framework directly on Ubuntu 14.04 or in an Ubuntu
34 No matter which way you choose to install Yardstick framework, the following
35 installation steps are identical.
36 If you choose to use the Ubuntu 14.04 Docker image, You can pull the Ubuntu
37 14.04 Docker image from Docker hub:
41 docker pull ubuntu:14.04
43 Installing Yardstick framework
44 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
49 sudo apt-get update && sudo apt-get install -y \
64 Create a python virtual environment, source it and update setuptools:
68 virtualenv ~/yardstick_venv
69 source ~/yardstick_venv/bin/activate
70 easy_install -U setuptools
72 Download source code and install python dependencies:
76 git clone https://gerrit.opnfv.org/gerrit/yardstick
78 python setup.py install
80 There is also a YouTube video, showing the above steps:
82 .. image:: http://img.youtube.com/vi/4S4izNolmR0/0.jpg
83 :alt: http://www.youtube.com/watch?v=4S4izNolmR0
84 :target: http://www.youtube.com/watch?v=4S4izNolmR0
88 Building a guest image
89 ^^^^^^^^^^^^^^^^^^^^^^
90 Yardstick has a tool for building an Ubuntu Cloud Server image containing all
91 the required tools to run test cases supported by Yardstick. It is necessary to
92 have sudo rights to use this tool.
94 Also you may need install several additional packages to use this tool, by
95 follwing the commands below:
99 apt-get update && apt-get install -y \
103 This image can be built using the following command while in the directory where
104 Yardstick is installed (``~/yardstick`` if the framework is installed
105 by following the commands above):
109 sudo ./tools/yardstick-img-modify tools/ubuntu-server-cloudimg-modify.sh
111 **Warning:** the script will create files by default in:
112 ``/tmp/workspace/yardstick`` and the files will be owned by root!
114 The created image can be added to OpenStack using the ``glance image-create`` or
115 via the OpenStack Dashboard.
121 glance --os-image-api-version 1 image-create \
122 --name yardstick-trusty-server --is-public true \
123 --disk-format qcow2 --container-format bare \
124 --file /tmp/workspace/yardstick/yardstick-trusty-server.img
127 Installing Yardstick using Docker
128 ---------------------------------
130 Yardstick iteself has a Docker image, this Docker image (**Yardstick-stable**)
131 serves as a replacement for installing the Yardstick framework in a virtual
132 environment (for example as done in :ref:`install-framework`).
133 It is recommended to use this Docker image to run Yardstick test.
135 Yardstick-stable image
136 ^^^^^^^^^^^^^^^^^^^^^^
137 Pull the Yardstick-stable Docker image from Docker hub:
141 docker pull opnfv/yardstick:stable
143 Run the Docker image:
151 -e "INSTALLER_TYPE=${INSTALLER_TYPE}" \
152 -e "INSTALLER_IP=${INSTALLER_IP}" \
154 exec_tests.sh ${YARDSTICK_DB_BACKEND} ${YARDSTICK_SUITE_NAME}
156 Where ``${INSTALLER_TYPE}`` can be apex, compass, fuel or joid, ``${INSTALLER_IP}``
157 is the installer master node IP address (i.e. 10.20.0.2 is default for fuel). ``${YARDSTICK_DB_BACKEND}``
158 is the IP and port number of DB, ``${YARDSTICK_SUITE_NAME}`` is the test suite you want to run.
159 For more details, please refer to the Jenkins job defined in Releng project, labconfig information
160 and sshkey are required. See the link
161 https://git.opnfv.org/cgit/releng/tree/jjb/yardstick/yardstick-ci-jobs.yml.
163 Note: exec_tests.sh is used for executing test suite here, furthermore, if someone
164 wants to execute the test suite manually, it can be used as long as the parameters
165 are configured correct. Another script called run_tests.sh is used for unittest in
166 Jenkins verify job, in local manaul environment, it is recommended to run before
167 test suite execuation.
169 Basic steps performed by the **Yardstick-stable** container:
171 1. clone yardstick and releng repos
172 2. setup OS credentials (releng scripts)
173 3. install yardstick and dependencies
174 4. build yardstick cloud image and upload it to glance
175 5. upload cirros-0.3.3 cloud image and ubuntu-14.04 cloud image to glance
176 6. run yardstick test scenarios
179 If someone only wants to execute a single test case, one can log into the yardstick-stable
180 container first using command:
184 docker run -it openfv/yardstick /bin/bash
186 Then in the container run yardstick task command to execute single test case.
187 Detailed steps about executing Yardstick test case can be found below.
190 OpenStack parameters and credentials
191 ------------------------------------
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 flavor by the
197 disk size - instead of 1GB it has 3GB. Other parameters are the same as in m1.tiny.
199 Environment variables
200 ^^^^^^^^^^^^^^^^^^^^^
201 Before running Yardstick it is necessary to export OpenStack environment variables
202 from the OpenStack *openrc* file (using the ``source`` command) and export the
203 external network name ``export EXTERNAL_NETWORK="external-network-name"``,
204 the default name for the external network is ``net04_ext``.
206 Credential environment variables in the *openrc* file have to include at least:
213 Yardstick default key pair
214 ^^^^^^^^^^^^^^^^^^^^^^^^^^
215 Yardstick uses a SSH key pair to connect to the guest image. This key pair can
216 be found in the ``resources/files`` directory. To run the ``ping-hot.yaml`` test
217 sample, this key pair needs to be imported to the OpenStack environment.
220 Examples and verifying the install
221 ----------------------------------
223 It is recommended to verify that Yardstick was installed successfully
224 by executing some simple commands and test samples. Below is an example invocation
225 of yardstick help command and ping.py test sample:
229 yardstick task start samples/ping.yaml
231 Each testing tool supported by Yardstick has a sample configuration file.
232 These configuration files can be found in the **samples** directory.
234 Default location for the output is ``/tmp/yardstick.out``.
237 Deploy InfluxDB and Grafana locally
238 ------------------------------------
240 .. pull docker images
244 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
248 docker pull tutum/influxdb
249 docker pull grafana/grafana
251 Run influxdb and config
252 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
256 docker run -d --name influxdb \
257 -p 8083:8083 -p 8086:8086 --expose 8090 --expose 8099 \
259 docker exec -it influxdb bash
265 >CREATE USER root WITH PASSWORD 'root' WITH ALL PRIVILEGES
266 >CREATE DATABASE yardstick;
270 Run grafana and config
271 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
275 docker run -d --name grafana -p 3000:3000 grafana/grafana
280 http://{YOUR_IP_HERE}:3000
281 log on using admin/admin and config database resource to be {YOUR_IP_HERE}:8086
283 .. image:: images/Grafana_config.png
285 :alt: Grafana data source configration
287 Config yardstick conf
288 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
289 cp ./etc/yardstick/yardstick.conf.sample /etc/yardstick/yardstick.conf
291 vi /etc/yardstick/yardstick.conf
292 Config yardstick.conf
297 dispatcher = influxdb
299 [dispatcher_influxdb]
301 target = http://{YOUR_IP_HERE}:8086
306 Now you can run yardstick test case and store the results in influxdb
307 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
310 Create a test suite for yardstick
311 ------------------------------------
313 A test suite in yardstick is a yaml file which include one or more test cases.
314 Yardstick is able to support running test suite task, so you can customize you
315 own test suite and run it in one task.
317 "tests/opnfv/test_suites" is where yardstick put ci test-suite. A typical test
325 # Fuel integration test task suite
327 schema: "yardstick:suite:0.1"
329 name: "fuel_test_suite"
330 test_cases_dir: "samples/"
335 file_name: iperf3.yaml
337 As you can see, there are two test cases in fuel_test_suite, the syntas is simple
338 here, you must specify the schema and the name, then you just need to list the
339 test cases in the tag "test_cases" and also mark their relative directory in the
340 tag "test_cases_dir".
342 Yardstick test suite also support constraints and task args for each test suite.
343 Here is another sample to show this, which is digested from one big test suite.
345 os-nosdn-nofeature-ha.yaml
351 schema: "yardstick:suite:0.1"
353 name: "os-nosdn-nofeature-ha"
354 test_cases_dir: "tests/opnfv/test_cases/"
357 file_name: opnfv_yardstick_tc002.yaml
359 file_name: opnfv_yardstick_tc005.yaml
361 file_name: opnfv_yardstick_tc043.yaml
366 huawei-pod1: '{"pod_info": "etc/yardstick/.../pod.yaml",
367 "host": "node4.LF","target": "node5.LF"}'
369 As you can see in test case "opnfv_yardstick_tc043.yaml", it has two tags, "constraint" and
370 "task_args". "constraint" is where you can specify which installer or pod it can be run in
371 the ci environment. "task_args" is where you can specify the task arguments for each pod.
373 All in all, to create a test suite in yardstick, you just need to create a suite yaml file
374 and add test cases and constraint or task arguments if necessary.