X-Git-Url: https://gerrit.opnfv.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2Fuserguide%2F07-installation.rst;h=9c2082a27d3221345e788782f6acaf7b6f4e82e7;hb=ed355ea25b8a32468db9006d9a8eee2363748515;hp=8d87bc09d7b4a54e3a7b9d4f3fb31862b9d130df;hpb=5bdaffe7a8b573c4755e46ec86647e303f22bb26;p=yardstick.git diff --git a/docs/userguide/07-installation.rst b/docs/userguide/07-installation.rst index 8d87bc09d..9c2082a27 100644 --- a/docs/userguide/07-installation.rst +++ b/docs/userguide/07-installation.rst @@ -9,22 +9,52 @@ Yardstick Installation Abstract -------- -Yardstick supports installation on Ubuntu 14.04 or by using a Docker image. -The installation procedure on Ubuntu 14.04 or via the docker image are -detailed in the section below +Yardstick supports installation on Ubuntu 14.04 or via a Docker image. The +installation procedure on Ubuntu 14.04 or via the docker image are detailed in +the section below. -To use Yardstick you should have access to an OpenStack environment, -with at least Nova, Neutron, Glance, Keystone and Heat installed. +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. -2. Create the test configuration .yaml file. -3. Build a guest image。 -4 .Load the image into the OpenStack environment. -5. Create a Neutron external network. -6. Load OpenStack environment variables. -6. Run the test case. +2. Load OpenStack environment variables. +3. Create a Neutron external network. +4. Build Yardstick flavor and a guest image. +5. Load the guest image into the OpenStack environment. +6. Create the test configuration .yaml file. +7. Run the test case. + + +Prerequisites +------------- + +The OPNFV deployment is out of the scope of this document but it can be +found in http://artifacts.opnfv.org/opnfvdocs/colorado/docs/configguide/index.html. +The OPNFV platform is considered as the System Under Test (SUT) in this +document. + +Several prerequisites are needed for Yardstick: + + #. A Jumphost to run Yardstick on + #. A Docker daemon shall be installed on the Jumphost + #. A public/external network created on the SUT + #. Connectivity from the Jumphost to the SUT public/external network + +WARNING: Connectivity from Jumphost is essential and it is of paramount +importance to make sure it is working before even considering to install +and run Yardstick. Make also sure you understand how your networking is +designed to work. + +NOTE: **Jumphost** refers to any server which meets the previous +requirements. Normally it is the same server from where the OPNFV +deployment has been triggered previously. + +NOTE: If your Jumphost is operating behind a company http proxy and/or +Firewall, please consult first the section `Proxy Support`_, towards +the end of this document. The section details some tips/tricks which +*may* be of help in a proxified environment. Installing Yardstick on Ubuntu 14.04 @@ -33,9 +63,9 @@ Installing Yardstick on Ubuntu 14.04 .. _install-framework: You can install Yardstick framework directly on Ubuntu 14.04 or in an Ubuntu -14.04 Docker image. -No matter which way you choose to install Yardstick framework, the following -installation steps are identical. +14.04 Docker image. No matter which way you choose to install Yardstick +framework, the following installation steps are identical. + If you choose to use the Ubuntu 14.04 Docker image, You can pull the Ubuntu 14.04 Docker image from Docker hub: @@ -45,55 +75,108 @@ If you choose to use the Ubuntu 14.04 Docker image, You can pull the Ubuntu Installing Yardstick framework ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Install dependencies: +Download source code and install python 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: + git clone https://gerrit.opnfv.org/gerrit/yardstick + cd yardstick + ./install.sh -:: - virtualenv ~/yardstick_venv - source ~/yardstick_venv/bin/activate - easy_install -U setuptools +Installing Yardstick using Docker +--------------------------------- -Download source code and install python dependencies: +Yardstick has a Docker image, this Docker image (**Yardstick-stable**) +serves as a replacement for installing the Yardstick framework in a virtual +environment (for example as done in :ref:`install-framework`). +It is recommended to use this Docker image to run Yardstick test. + +Pulling the Yardstick Docker image +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. _dockerhub: https://hub.docker.com/r/opnfv/yardstick/ + +Pull the Yardstick Docker image ('opnfv/yardstick') from the public dockerhub +registry under the OPNFV account: [dockerhub_], with the following docker +command:: + + docker pull opnfv/yardstick:stable + +After pulling the Docker image, check that it is available with the +following docker command:: + + [yardsticker@jumphost ~]$ docker images + REPOSITORY TAG IMAGE ID CREATED SIZE + opnfv/yardstick stable a4501714757a 1 day ago 915.4 MB + +Run the Docker image: :: - git clone https://gerrit.opnfv.org/gerrit/yardstick - cd yardstick - python setup.py install + docker run --privileged=true -it opnfv/yardstick:stable /bin/bash -A Youtube video tutorial on this installation mode is available -at: http://www.youtube.com/watch?v=4S4izNolmR0 +In the container the Yardstick repository is located in the /home/opnfv/repos +directory. + + +OpenStack parameters and credentials +------------------------------------ + +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 + +A sample openrc file may look like this: + +* export OS_PASSWORD=console +* export OS_TENANT_NAME=admin +* export OS_AUTH_URL=http://172.16.1.222:35357/v2.0 +* export OS_USERNAME=admin +* export OS_VOLUME_API_VERSION=2 +* export EXTERNAL_NETWORK=net04_ext + + +Yardstick falvor and guest images +--------------------------------- + +Before executing Yardstick test cases, make sure that yardstick guest image and +yardstick flavor are available in OpenStack. +Detailed steps about creating yardstick flavor and building yardstick-trusty-server +image can be found below. + +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. + +Create yardstick-flavor: + +:: + + nova flavor-create yardstick-flavor 100 512 3 1 -.. 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 .. _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. +Most of the sample test cases in Yardstick are using a guest image called +*yardstick-trusty-server* which deviates from an Ubuntu Cloud Server image +containing all the required tools to run test cases supported by Yardstick. +Yardstick has a tool for building this custom image. 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: @@ -110,13 +193,16 @@ by following the commands above): :: - eport YARD_IMG_ARCH="amd64" + export YARD_IMG_ARCH="amd64" sudo echo "Defaults env_keep += \"YARD_IMG_ARCH\"" >> /etc/sudoers 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! +If you are building this guest image in inside a docker container make sure the +container is granted with privilege. + The created image can be added to OpenStack using the ``glance image-create`` or via the OpenStack Dashboard. @@ -125,106 +211,28 @@ Example command: :: glance --os-image-api-version 1 image-create \ - --name yardstick-trusty-server --is-public true \ + --name yardstick-image --is-public true \ --disk-format qcow2 --container-format bare \ - --file /tmp/workspace/yardstick/yardstick-trusty-server.img + --file /tmp/workspace/yardstick/yardstick-image.img +Some Yardstick test cases use a Cirros image, you can find one at +http://download.cirros-cloud.net/0.3.3/cirros-0.3.3-x86_64-disk.img -Installing Yardstick using Docker ---------------------------------- - -Yardstick iteself has a Docker image, this Docker image (**Yardstick-stable**) -serves as a replacement for installing the Yardstick framework in a virtual -environment (for example as done in :ref:`install-framework`). -It is recommended to use this Docker image to run Yardstick test. - -Yardstick-stable image -^^^^^^^^^^^^^^^^^^^^^^ -Pull the Yardstick-stable Docker image from Docker hub: - -:: - - docker pull opnfv/yardstick:stable - -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-stable** container: - -1. clone yardstick and releng repos -2. setup OS credentials (releng scripts) -3. install yardstick and dependencies -4. build yardstick cloud image -5. Upload yardstick cloud image to glance -6. upload cirros-0.3.3 cloud image and ubuntu-14.04 cloud image to glance -7. run yardstick test scenarios -8. cleanup - -If someone only wants to execute a single test case, one can log into the yardstick-stable -container first using command: - -:: - docker run -it openfv/yardstick /bin/bash +Automatic flavor and image creation +----------------------------------- +Yardstick has a script for automatic creating yardstick flavor and building +guest images. This script is mainly used in CI, but you can still use it in +your local environment. -Then in the container run yardstick task command to execute a single test case. -Before executing Yardstick test case, make sure that yardstick-trusty-server -image and yardstick flavor is available in OpenStack. -Detailed steps about creating yardstick flavor and executing Yardstick test case -can be found below. - - -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. - -Create yardstick-flavor: +Example command: :: - nova flavor-create yardstick-flavor 100 512 3 1 - -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: + export YARD_IMG_ARCH="amd64" + sudo echo "Defaults env_keep += \"YARD_IMG_ARCH\"" >> /etc/sudoers + source $YARDSTICK_REPO_DIR/tests/ci/load_images.sh -* OS_AUTH_URL -* OS_USERNAME -* OS_PASSWORD -* OS_TENANT_NAME Yardstick default key pair ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -237,8 +245,10 @@ 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: +by executing some simple commands and test samples. Before executing yardstick +test cases make sure yardstick flavor and building yardstick-trusty-server +image can be found in glance and openrc file is sourced. Below is an example +invocation of yardstick help command and ping.py test sample: :: yardstick –h @@ -355,7 +365,7 @@ here, you must specify the schema and the name, then you just need to list the test cases in the tag "test_cases" and also mark their relative directory in the tag "test_cases_dir". -Yardstick test suite also support constraints and task args for each test suite. +Yardstick test suite also support constraints and task args for each test case. Here is another sample to show this, which is digested from one big test suite. os-nosdn-nofeature-ha.yaml