diff options
Diffstat (limited to 'docs/userguide/07-installation.rst')
| -rw-r--r-- | docs/userguide/07-installation.rst | 321 |
1 files changed, 321 insertions, 0 deletions
diff --git a/docs/userguide/07-installation.rst b/docs/userguide/07-installation.rst new file mode 100644 index 000000000..25c125851 --- /dev/null +++ b/docs/userguide/07-installation.rst @@ -0,0 +1,321 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International +.. License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) OPNFV, Ericsson AB, Huawei Technologies Co.,Ltd and others. + +Yardstick Installation +====================== + +Abstract +-------- + +Yardstick currently supports installation on Ubuntu 14.04 or by using a Docker +image. Detailed steps about installing Yardstick using both of these options +can be found below. + +To use Yardstick you should have access to an OpenStack environment, +with at least Nova, Neutron, Glance, Keystone and Heat installed. + +The steps needed to run Yardstick are: + +1. Install Yardstick and create the test configuration .yaml file. +2. Build a guest image and load the image into the OpenStack environment. +3. Create a Neutron external network and load OpenStack environment variables. +4. Run the test case. + + +Installing Yardstick on Ubuntu 14.04 +------------------------------------ + +.. _install-framework: + +Installing Yardstick framework +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Install dependencies: +:: + + sudo apt-get update && sudo apt-get install -y \ + wget \ + git \ + sshpass \ + qemu-utils \ + kpartx \ + libffi-dev \ + libssl-dev \ + python \ + python-dev \ + python-virtualenv \ + libxml2-dev \ + libxslt1-dev \ + python-setuptools + +Create a python virtual environment, source it and update setuptools: +:: + + virtualenv ~/yardstick_venv + source ~/yardstick_venv/bin/activate + easy_install -U setuptools + +Download source code and install python dependencies: +:: + + git clone https://gerrit.opnfv.org/gerrit/yardstick + cd yardstick + python setup.py install + +There is also a YouTube video, showing the above steps: + +.. image:: http://img.youtube.com/vi/4S4izNolmR0/0.jpg + :alt: http://www.youtube.com/watch?v=4S4izNolmR0 + :target: http://www.youtube.com/watch?v=4S4izNolmR0 + +Installing extra tools +^^^^^^^^^^^^^^^^^^^^^^ +yardstick-plot +"""""""""""""" +Yardstick has an internal plotting tool ``yardstick-plot``, which can be installed +using the following command: +:: + + sudo apt-get install -y g++ libfreetype6-dev libpng-dev pkg-config + python setup.py develop easy_install yardstick[plot] + +.. _guest-image: + +Building a guest image +^^^^^^^^^^^^^^^^^^^^^^ +Yardstick has a tool for building an Ubuntu Cloud Server image containing all +the required tools to run test cases supported by Yardstick. It is necessary to +have sudo rights to use this tool. + +Also you may need install several additional packages to use this tool, by +follwing the commands below: +:: + + apt-get update && apt-get install -y \ + qemu-utils \ + kpartx + +This image can be built using the following command while in the directory where +Yardstick is installed (``~/yardstick`` if the framework is installed +by following the commands above): +:: + + sudo ./tools/yardstick-img-modify tools/ubuntu-server-cloudimg-modify.sh + +**Warning:** the script will create files by default in: +``/tmp/workspace/yardstick`` and the files will be owned by root! + +The created image can be added to OpenStack using the ``glance image-create`` or +via the OpenStack Dashboard. + +Example command: +:: + + glance --os-image-api-version 1 image-create \ + --name yardstick-trusty-server --is-public true \ + --disk-format qcow2 --container-format bare \ + --file /tmp/workspace/yardstick/yardstick-trusty-server.img + + +Installing Yardstick using Docker +--------------------------------- + +Yardstick has two Docker images, first one (**Yardstick-framework**) serves as a +replacement for installing the Yardstick framework in a virtual environment (for +example as done in :ref:`install-framework`), while the other image is mostly for +CI purposes (**Yardstick-CI**). + +Yardstick-framework image +^^^^^^^^^^^^^^^^^^^^^^^^^ +Download the source code: + +:: + + git clone https://gerrit.opnfv.org/gerrit/yardstick + +Build the Docker image and tag it as *yardstick-framework*: + +:: + + cd yardstick + docker build -t yardstick-framework . + +Run the Docker instance: + +:: + + docker run --name yardstick_instance -i -t yardstick-framework + +To build a guest image for Yardstick, see :ref:`guest-image`. + +Yardstick-CI image +^^^^^^^^^^^^^^^^^^ +Pull the Yardstick-CI Docker image from Docker hub: + +:: + + docker pull opnfv/yardstick:$DOCKER_TAG + +Where ``$DOCKER_TAG`` is latest for master branch, as for the release branches, +this coincides with its release name, such as brahmaputra.1.0. + +Run the Docker image: + +:: + + docker run \ + --privileged=true \ + --rm \ + -t \ + -e "INSTALLER_TYPE=${INSTALLER_TYPE}" \ + -e "INSTALLER_IP=${INSTALLER_IP}" \ + opnfv/yardstick \ + exec_tests.sh ${YARDSTICK_DB_BACKEND} ${YARDSTICK_SUITE_NAME} + +Where ``${INSTALLER_TYPE}`` can be apex, compass, fuel or joid, ``${INSTALLER_IP}`` +is the installer master node IP address (i.e. 10.20.0.2 is default for fuel). ``${YARDSTICK_DB_BACKEND}`` +is the IP and port number of DB, ``${YARDSTICK_SUITE_NAME}`` is the test suite you want to run. +For more details, please refer to the Jenkins job defined in Releng project, labconfig information +and sshkey are required. See the link +https://git.opnfv.org/cgit/releng/tree/jjb/yardstick/yardstick-ci-jobs.yml. + +Note: exec_tests.sh is used for executing test suite here, furthermore, if someone wants to execute the +test suite manually, it can be used as long as the parameters are configured correct. Another script +called run_tests.sh is used for unittest in Jenkins verify job, in local manaul environment, +it is recommended to run before test suite execuation. + +Basic steps performed by the **Yardstick-CI** container: + +1. clone yardstick and releng repos +2. setup OS credentials (releng scripts) +3. install yardstick and dependencies +4. build yardstick cloud image and upload it to glance +5. upload cirros-0.3.3 cloud image to glance +6. run yardstick test scenarios +7. cleanup + + +OpenStack parameters and credentials +------------------------------------ + +Yardstick-flavor +^^^^^^^^^^^^^^^^ +Most of the sample test cases in Yardstick are using an OpenStack flavor called +*yardstick-flavor* which deviates from the OpenStack standard m1.tiny flavor by the +disk size - instead of 1GB it has 3GB. Other parameters are the same as in m1.tiny. + +Environment variables +^^^^^^^^^^^^^^^^^^^^^ +Before running Yardstick it is necessary to export OpenStack environment variables +from the OpenStack *openrc* file (using the ``source`` command) and export the +external network name ``export EXTERNAL_NETWORK="external-network-name"``, +the default name for the external network is ``net04_ext``. + +Credential environment variables in the *openrc* file have to include at least: + +* OS_AUTH_URL +* OS_USERNAME +* OS_PASSWORD +* OS_TENANT_NAME + +Yardstick default key pair +^^^^^^^^^^^^^^^^^^^^^^^^^^ +Yardstick uses a SSH key pair to connect to the guest image. This key pair can +be found in the ``resources/files`` directory. To run the ``ping-hot.yaml`` test +sample, this key pair needs to be imported to the OpenStack environment. + + +Examples and verifying the install +---------------------------------- + +It is recommended to verify that Yardstick was installed successfully +by executing some simple commands and test samples. Below is an example invocation +of yardstick help command and ping.py test sample: +:: + + yardstick –h + yardstick task start samples/ping.yaml + +Each testing tool supported by Yardstick has a sample configuration file. +These configuration files can be found in the **samples** directory. + +Example invocation of ``yardstick-plot`` tool: +:: + + yardstick-plot -i /tmp/yardstick.out -o /tmp/plots/ + +Default location for the output is ``/tmp/yardstick.out``. + +More info about the tool can be found by executing: +:: + + yardstick-plot -h + + +Deploy InfluxDB and Grafana locally +------------------------------------ + +.. pull docker images + +Pull docker images +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + docker pull tutum/influxdb + docker pull grafana/grafana + +Run influxdb and config +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Run influxdb +:: + + docker run -d --name influxdb -p 8083:8083 -p 8086:8086 --expose 8090 --expose 8099 tutum/influxdb + docker exec -it influxdb bash + +Config influxdb +:: + + influx + >CREATE USER root WITH PASSWORD 'root' WITH ALL PRIVILEGES + >CREATE DATABASE yardstick; + >use yardstick; + >show MEASUREMENTS; + +Run grafana and config +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Run grafana +:: + + docker run -d --name grafana -p 3000:3000 grafana/grafana + +Config grafana +:: + + http://{YOUR_IP_HERE}:3000 + log on using admin/admin and config database resource to be {YOUR_IP_HERE}:8086 + +.. image:: images/Grafana_config.png + +Config yardstick conf +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +cp ./etc/yardstick/yardstick.conf.sample /etc/yardstick/yardstick.conf + +vi /etc/yardstick/yardstick.conf +Config yardstick.conf +:: + + [DEFAULT] + debug = True + dispatcher = influxdb + + [dispatcher_influxdb] + timeout = 5 + target = http://{YOUR_IP_HERE}:8086 + db_name = yardstick + username = root + password = root + +Now you can run yardstick test case and store the results in influxdb +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |