From f0af8fd11aaf9860bbe8a2e047cf7932ea8e6e7a Mon Sep 17 00:00:00 2001 From: JingLu5 Date: Thu, 20 Oct 2016 18:48:01 +0800 Subject: Bugfix: correct a typo in the yardstick userguide JIRA: YARDSTICK-374 Also refine the userguide Change-Id: Iae2af02684ee326abe2a21940e5023b935d4a8da Signed-off-by: JingLu5 --- docs/userguide/07-installation.rst | 157 +++++++++++++++++++++++++++---------- docs/userguide/10-grafana.rst | 86 ++++++++++++++++++++ docs/userguide/10-list-of-tcs.rst | 128 ------------------------------ docs/userguide/11-list-of-tcs.rst | 128 ++++++++++++++++++++++++++++++ docs/userguide/images/TC002.png | Bin 0 -> 106382 bytes docs/userguide/images/add.png | Bin 0 -> 169904 bytes docs/userguide/images/login.png | Bin 0 -> 32761 bytes docs/userguide/index.rst | 3 +- 8 files changed, 333 insertions(+), 169 deletions(-) create mode 100644 docs/userguide/10-grafana.rst delete mode 100644 docs/userguide/10-list-of-tcs.rst create mode 100644 docs/userguide/11-list-of-tcs.rst create mode 100644 docs/userguide/images/TC002.png create mode 100644 docs/userguide/images/add.png create mode 100644 docs/userguide/images/login.png diff --git a/docs/userguide/07-installation.rst b/docs/userguide/07-installation.rst index aa45b61af..d3d7bc1ce 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: @@ -91,47 +121,42 @@ at: http://www.youtube.com/watch?v=4S4izNolmR0 Installing Yardstick using Docker --------------------------------- -Yardstick iteself has a Docker image, this Docker image (**Yardstick-stable**) +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. -Yardstick-stable image -^^^^^^^^^^^^^^^^^^^^^^ -Pull the Yardstick-stable Docker image from Docker hub: +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: :: - docker run --privileged=true -it openfv/yardstick /bin/bash + docker run --privileged=true -it opnfv/yardstick /bin/bash -In the container run yardstick task command to execute a 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 building yardstick-trusty-server -image can be found below. +In the container the Yardstick repository is located in the /home/opnfv/repos +directory. 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: - -:: - - nova flavor-create yardstick-flavor 100 512 3 1 - Environment variables ^^^^^^^^^^^^^^^^^^^^^ Before running Yardstick it is necessary to export OpenStack environment variables @@ -146,14 +171,46 @@ Credential environment variables in the *openrc* file have to include at least: * 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 + .. _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: @@ -176,8 +233,10 @@ by following the commands above): **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. @@ -190,6 +249,24 @@ Example command: --disk-format qcow2 --container-format bare \ --file /tmp/workspace/yardstick/yardstick-trusty-server.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 + + +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. + +Example command: + +:: + + export YARD_IMG_ARCH="amd64" + sudo echo "Defaults env_keep += \"YARD_IMG_ARCH\"" >> /etc/sudoers + source $YARDSTICK_REPO_DIR/tests/ci/load_images.sh + Yardstick default key pair ^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/userguide/10-grafana.rst b/docs/userguide/10-grafana.rst new file mode 100644 index 000000000..e871a18da --- /dev/null +++ b/docs/userguide/10-grafana.rst @@ -0,0 +1,86 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International +.. License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) 2016 Huawei Technologies Co.,Ltd and others + +================= +Grafana dashboard +================= + +Abstract +======== + +This chapter describes the Yardstick grafana dashboard. The Yardstick grafana +dashboard can be found here: http://testresults.opnfv.org/grafana/ + + +.. image:: images/login.png + :width: 800px + :alt: Yardstick grafana dashboard + +Public access +============= + +Yardstick provids a public account for accessing to the dashboard. The username +and password are both set to ‘opnfv’. + +Testcase dashboard +================== + +For each test case, there is a dedicated dashboard. Shown here is the dashboard +of TC002. + + +.. image:: images/TC002.png + :width: 800px + :alt:TC002 dashboard + +For each test case dashboard. On the top left, we have a dashboard selection, +you can switch to different test cases using this pull-down menu. + +Underneath, we have a pod and scenario selection. +All the pods and scenarios that have ever published test data to the Influx DB +will be shown here. + +You can check multiple pods or scenarios. + +For each test case, we have a short description and a link to detailed test case information in Yardstick user guide. + +Underneath, it is the result presentation section. +You can use the time period selection on the top right corner to zoom in or zoom out the chart. + +Add a dashboard into yardstick grafana +====================================== + +Due to security concern, users that using the public opnfv account are not able +to edit the yardstick grafana directly.It takes a few more steps for a +non-yardstick user to add a custom dashboard into yardstick grafana. + +There are 6 steps to go. + + +.. image:: images/add.png + :width: 800px + :alt: Add a dashboard into yardstick grafana + + +First, You need to build a local influxdb and grafana, so you can do the work +locally. You can refer to How to deploy InfluxDB and Grafana locally wiki page +about how to do this. + +Once step one is done, you can fetch the existing grafana dashboard +configuration file from the yardstick repository and import it to your local +grafana. After import is done, you grafana dashboard will be ready to use just +like the community’s dashboard. + +The third step is running some test cases to generate test results and +publishing it to your local influxdb. + +Now you have some data to visualize in your dashboard. In the fourth step, it +is time to create your own dashboard. You can either modify an existing +dashboard or try to create a new one from scratch. + +Either way, once you finish the dashboard, the next step is exporting the +configuration file and propose a patch into Yardstick. Yardstick team will +review and merge it into Yardstick repository. + diff --git a/docs/userguide/10-list-of-tcs.rst b/docs/userguide/10-list-of-tcs.rst deleted file mode 100644 index 8798a8f51..000000000 --- a/docs/userguide/10-list-of-tcs.rst +++ /dev/null @@ -1,128 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International -.. License. -.. http://creativecommons.org/licenses/by/4.0 -.. (c) OPNFV, Ericsson AB and others. - -==================== -Yardstick Test Cases -==================== - -Abstract -======== - -This chapter lists available Yardstick test cases. -Yardstick test cases are divided in two main categories: - -* *Generic NFVI Test Cases* - Test Cases developed to realize the methodology -described in :doc:`02-methodology` - -* *OPNFV Feature Test Cases* - Test Cases developed to verify one or more -aspect of a feature delivered by an OPNFV Project, including the test cases -developed for the :term:`VTC`. - -Generic NFVI Test Case Descriptions -=================================== - -.. toctree:: - :maxdepth: 1 - - opnfv_yardstick_tc001.rst - opnfv_yardstick_tc002.rst - opnfv_yardstick_tc004.rst - opnfv_yardstick_tc005.rst - opnfv_yardstick_tc008.rst - opnfv_yardstick_tc009.rst - opnfv_yardstick_tc010.rst - opnfv_yardstick_tc011.rst - opnfv_yardstick_tc012.rst - opnfv_yardstick_tc014.rst - opnfv_yardstick_tc024.rst - opnfv_yardstick_tc037.rst - opnfv_yardstick_tc038.rst - opnfv_yardstick_tc042.rst - opnfv_yardstick_tc043.rst - opnfv_yardstick_tc044.rst - opnfv_yardstick_tc055.rst - opnfv_yardstick_tc061.rst - opnfv_yardstick_tc063.rst - opnfv_yardstick_tc069.rst - opnfv_yardstick_tc070.rst - opnfv_yardstick_tc071.rst - opnfv_yardstick_tc072.rst - opnfv_yardstick_tc073.rst - opnfv_yardstick_tc075.rst - -OPNFV Feature Test Cases -======================== - -H A ---- - -.. toctree:: - :maxdepth: 1 - - opnfv_yardstick_tc019.rst - opnfv_yardstick_tc025.rst - opnfv_yardstick_tc045.rst - opnfv_yardstick_tc046.rst - opnfv_yardstick_tc047.rst - opnfv_yardstick_tc048.rst - opnfv_yardstick_tc049.rst - opnfv_yardstick_tc050.rst - opnfv_yardstick_tc051.rst - opnfv_yardstick_tc052.rst - opnfv_yardstick_tc053.rst - opnfv_yardstick_tc054.rst - -IPv6 ----- - -.. toctree:: - :maxdepth: 1 - - opnfv_yardstick_tc027.rst - -KVM ---- - -.. toctree:: - :maxdepth: 1 - - opnfv_yardstick_tc028.rst - -Parser ------- - -.. toctree:: - :maxdepth: 1 - - opnfv_yardstick_tc040.rst - - StorPerf ------------ - -.. toctree:: - :maxdepth: 1 - - opnfv_yardstick_tc074.rst - -virtual Traffic Classifier --------------------------- - -.. toctree:: - :maxdepth: 1 - - opnfv_yardstick_tc006.rst - opnfv_yardstick_tc007.rst - opnfv_yardstick_tc020.rst - opnfv_yardstick_tc021.rst - -Templates -========= - -.. toctree:: - :maxdepth: 1 - - testcase_description_v2_template - Yardstick_task_templates - diff --git a/docs/userguide/11-list-of-tcs.rst b/docs/userguide/11-list-of-tcs.rst new file mode 100644 index 000000000..8798a8f51 --- /dev/null +++ b/docs/userguide/11-list-of-tcs.rst @@ -0,0 +1,128 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International +.. License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) OPNFV, Ericsson AB and others. + +==================== +Yardstick Test Cases +==================== + +Abstract +======== + +This chapter lists available Yardstick test cases. +Yardstick test cases are divided in two main categories: + +* *Generic NFVI Test Cases* - Test Cases developed to realize the methodology +described in :doc:`02-methodology` + +* *OPNFV Feature Test Cases* - Test Cases developed to verify one or more +aspect of a feature delivered by an OPNFV Project, including the test cases +developed for the :term:`VTC`. + +Generic NFVI Test Case Descriptions +=================================== + +.. toctree:: + :maxdepth: 1 + + opnfv_yardstick_tc001.rst + opnfv_yardstick_tc002.rst + opnfv_yardstick_tc004.rst + opnfv_yardstick_tc005.rst + opnfv_yardstick_tc008.rst + opnfv_yardstick_tc009.rst + opnfv_yardstick_tc010.rst + opnfv_yardstick_tc011.rst + opnfv_yardstick_tc012.rst + opnfv_yardstick_tc014.rst + opnfv_yardstick_tc024.rst + opnfv_yardstick_tc037.rst + opnfv_yardstick_tc038.rst + opnfv_yardstick_tc042.rst + opnfv_yardstick_tc043.rst + opnfv_yardstick_tc044.rst + opnfv_yardstick_tc055.rst + opnfv_yardstick_tc061.rst + opnfv_yardstick_tc063.rst + opnfv_yardstick_tc069.rst + opnfv_yardstick_tc070.rst + opnfv_yardstick_tc071.rst + opnfv_yardstick_tc072.rst + opnfv_yardstick_tc073.rst + opnfv_yardstick_tc075.rst + +OPNFV Feature Test Cases +======================== + +H A +--- + +.. toctree:: + :maxdepth: 1 + + opnfv_yardstick_tc019.rst + opnfv_yardstick_tc025.rst + opnfv_yardstick_tc045.rst + opnfv_yardstick_tc046.rst + opnfv_yardstick_tc047.rst + opnfv_yardstick_tc048.rst + opnfv_yardstick_tc049.rst + opnfv_yardstick_tc050.rst + opnfv_yardstick_tc051.rst + opnfv_yardstick_tc052.rst + opnfv_yardstick_tc053.rst + opnfv_yardstick_tc054.rst + +IPv6 +---- + +.. toctree:: + :maxdepth: 1 + + opnfv_yardstick_tc027.rst + +KVM +--- + +.. toctree:: + :maxdepth: 1 + + opnfv_yardstick_tc028.rst + +Parser +------ + +.. toctree:: + :maxdepth: 1 + + opnfv_yardstick_tc040.rst + + StorPerf +----------- + +.. toctree:: + :maxdepth: 1 + + opnfv_yardstick_tc074.rst + +virtual Traffic Classifier +-------------------------- + +.. toctree:: + :maxdepth: 1 + + opnfv_yardstick_tc006.rst + opnfv_yardstick_tc007.rst + opnfv_yardstick_tc020.rst + opnfv_yardstick_tc021.rst + +Templates +========= + +.. toctree:: + :maxdepth: 1 + + testcase_description_v2_template + Yardstick_task_templates + diff --git a/docs/userguide/images/TC002.png b/docs/userguide/images/TC002.png new file mode 100644 index 000000000..89154efcc Binary files /dev/null and b/docs/userguide/images/TC002.png differ diff --git a/docs/userguide/images/add.png b/docs/userguide/images/add.png new file mode 100644 index 000000000..a88a1b146 Binary files /dev/null and b/docs/userguide/images/add.png differ diff --git a/docs/userguide/images/login.png b/docs/userguide/images/login.png new file mode 100644 index 000000000..045e010e4 Binary files /dev/null and b/docs/userguide/images/login.png differ diff --git a/docs/userguide/index.rst b/docs/userguide/index.rst index 0aa112a45..60e1340ac 100644 --- a/docs/userguide/index.rst +++ b/docs/userguide/index.rst @@ -19,6 +19,7 @@ Yardstick Overview 07-installation 08-yardstick_plugin 09-result-store-InfluxDB - 10-list-of-tcs + 10-grafana + 11-list-of-tcs glossary references -- cgit 1.2.3-korg