aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--docs/userguide/07-installation.rst157
-rw-r--r--docs/userguide/10-grafana.rst86
-rw-r--r--docs/userguide/11-list-of-tcs.rst (renamed from docs/userguide/10-list-of-tcs.rst)0
-rw-r--r--docs/userguide/images/TC002.pngbin0 -> 106382 bytes
-rw-r--r--docs/userguide/images/add.pngbin0 -> 169904 bytes
-rw-r--r--docs/userguide/images/login.pngbin0 -> 32761 bytes
-rw-r--r--docs/userguide/index.rst3
7 files changed, 205 insertions, 41 deletions
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/11-list-of-tcs.rst
index 8798a8f51..8798a8f51 100644
--- a/docs/userguide/10-list-of-tcs.rst
+++ b/docs/userguide/11-list-of-tcs.rst
diff --git a/docs/userguide/images/TC002.png b/docs/userguide/images/TC002.png
new file mode 100644
index 000000000..89154efcc
--- /dev/null
+++ b/docs/userguide/images/TC002.png
Binary files differ
diff --git a/docs/userguide/images/add.png b/docs/userguide/images/add.png
new file mode 100644
index 000000000..a88a1b146
--- /dev/null
+++ b/docs/userguide/images/add.png
Binary files differ
diff --git a/docs/userguide/images/login.png b/docs/userguide/images/login.png
new file mode 100644
index 000000000..045e010e4
--- /dev/null
+++ b/docs/userguide/images/login.png
Binary files 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
class="n">wl->hw, &wl->irq_work); } static const struct sdio_device_id wl1251_devices[] = { { SDIO_DEVICE(SDIO_VENDOR_ID_TI, SDIO_DEVICE_ID_TI_WL1251) }, {} }; MODULE_DEVICE_TABLE(sdio, wl1251_devices); static void wl1251_sdio_read(struct wl1251 *wl, int addr, void *buf, size_t len) { int ret; struct sdio_func *func = wl_to_func(wl); sdio_claim_host(func); ret = sdio_memcpy_fromio(func, buf, addr, len); if (ret) wl1251_error("sdio read failed (%d)", ret); sdio_release_host(func); } static void wl1251_sdio_write(struct wl1251 *wl, int addr, void *buf, size_t len) { int ret; struct sdio_func *func = wl_to_func(wl); sdio_claim_host(func); ret = sdio_memcpy_toio(func, addr, buf, len); if (ret) wl1251_error("sdio write failed (%d)", ret); sdio_release_host(func); } static void wl1251_sdio_read_elp(struct wl1251 *wl, int addr, u32 *val) { int ret = 0; struct wl1251_sdio *wl_sdio = wl->if_priv; struct sdio_func *func = wl_sdio->func; /* * The hardware only supports RAW (read after write) access for * reading, regular sdio_readb won't work here (it interprets * the unused bits of CMD52 as write data even if we send read * request). */ sdio_claim_host(func); *val = sdio_writeb_readb(func, wl_sdio->elp_val, addr, &ret); sdio_release_host(func); if (ret) wl1251_error("sdio_readb failed (%d)", ret); } static void wl1251_sdio_write_elp(struct wl1251 *wl, int addr, u32 val) { int ret = 0; struct wl1251_sdio *wl_sdio = wl->if_priv; struct sdio_func *func = wl_sdio->func; sdio_claim_host(func); sdio_writeb(func, val, addr, &ret); sdio_release_host(func); if (ret) wl1251_error("sdio_writeb failed (%d)", ret); else wl_sdio->elp_val = val; } static void wl1251_sdio_reset(struct wl1251 *wl) { } static void wl1251_sdio_enable_irq(struct wl1251 *wl) { struct sdio_func *func = wl_to_func(wl); sdio_claim_host(func); sdio_claim_irq(func, wl1251_sdio_interrupt); sdio_release_host(func); } static void wl1251_sdio_disable_irq(struct wl1251 *wl) { struct sdio_func *func = wl_to_func(wl); sdio_claim_host(func); sdio_release_irq(func); sdio_release_host(func); } /* Interrupts when using dedicated WLAN_IRQ pin */ static irqreturn_t wl1251_line_irq(int irq, void *cookie) { struct wl1251 *wl = cookie; ieee80211_queue_work(wl->hw, &wl->irq_work); return IRQ_HANDLED; } static void wl1251_enable_line_irq(struct wl1251 *wl) { return enable_irq(wl->irq); } static void wl1251_disable_line_irq(struct wl1251 *wl) { return disable_irq(wl->irq); } static int wl1251_sdio_set_power(struct wl1251 *wl, bool enable) { struct sdio_func *func = wl_to_func(wl); int ret; if (enable) { /* * Power is controlled by runtime PM, but we still call board * callback in case it wants to do any additional setup, * for example enabling clock buffer for the module. */ if (gpio_is_valid(wl->power_gpio)) gpio_set_value(wl->power_gpio, true); ret = pm_runtime_get_sync(&func->dev); if (ret < 0) { pm_runtime_put_sync(&func->dev); goto out; } sdio_claim_host(func); sdio_enable_func(func); sdio_release_host(func); } else { sdio_claim_host(func); sdio_disable_func(func); sdio_release_host(func); ret = pm_runtime_put_sync(&func->dev); if (ret < 0) goto out; if (gpio_is_valid(wl->power_gpio)) gpio_set_value(wl->power_gpio, false); } out: return ret; } static struct wl1251_if_operations wl1251_sdio_ops = { .read = wl1251_sdio_read, .write = wl1251_sdio_write, .write_elp = wl1251_sdio_write_elp, .read_elp = wl1251_sdio_read_elp, .reset = wl1251_sdio_reset, .power = wl1251_sdio_set_power, }; static int wl1251_sdio_probe(struct sdio_func *func, const struct sdio_device_id *id) { int ret; struct wl1251 *wl; struct ieee80211_hw *hw; struct wl1251_sdio *wl_sdio; const struct wl1251_platform_data *wl1251_board_data; hw = wl1251_alloc_hw(); if (IS_ERR(hw)) return PTR_ERR(hw); wl = hw->priv; wl_sdio = kzalloc(sizeof(*wl_sdio), GFP_KERNEL); if (wl_sdio == NULL) { ret = -ENOMEM; goto out_free_hw; } sdio_claim_host(func); ret = sdio_enable_func(func); if (ret) goto release; sdio_set_block_size(func, 512); sdio_release_host(func); SET_IEEE80211_DEV(hw, &func->dev); wl_sdio->func = func; wl->if_priv = wl_sdio; wl->if_ops = &wl1251_sdio_ops; wl1251_board_data = wl1251_get_platform_data(); if (!IS_ERR(wl1251_board_data)) { wl->power_gpio = wl1251_board_data->power_gpio; wl->irq = wl1251_board_data->irq; wl->use_eeprom = wl1251_board_data->use_eeprom; } if (gpio_is_valid(wl->power_gpio)) { ret = devm_gpio_request(&func->dev, wl->power_gpio, "wl1251 power"); if (ret) { wl1251_error("Failed to request gpio: %d\n", ret); goto disable; } } if (wl->irq) { irq_set_status_flags(wl->irq, IRQ_NOAUTOEN); ret = request_irq(wl->irq, wl1251_line_irq, 0, "wl1251", wl); if (ret < 0) { wl1251_error("request_irq() failed: %d", ret); goto disable; } irq_set_irq_type(wl->irq, IRQ_TYPE_EDGE_RISING); wl1251_sdio_ops.enable_irq = wl1251_enable_line_irq; wl1251_sdio_ops.disable_irq = wl1251_disable_line_irq; wl1251_info("using dedicated interrupt line"); } else { wl1251_sdio_ops.enable_irq = wl1251_sdio_enable_irq; wl1251_sdio_ops.disable_irq = wl1251_sdio_disable_irq; wl1251_info("using SDIO interrupt"); } ret = wl1251_init_ieee80211(wl); if (ret) goto out_free_irq; sdio_set_drvdata(func, wl); /* Tell PM core that we don't need the card to be powered now */ pm_runtime_put_noidle(&func->dev); return ret; out_free_irq: if (wl->irq) free_irq(wl->irq, wl); disable: sdio_claim_host(func); sdio_disable_func(func); release: sdio_release_host(func); kfree(wl_sdio); out_free_hw: wl1251_free_hw(wl); return ret; } static void wl1251_sdio_remove(struct sdio_func *func) { struct wl1251 *wl = sdio_get_drvdata(func); struct wl1251_sdio *wl_sdio = wl->if_priv; /* Undo decrement done above in wl1251_probe */ pm_runtime_get_noresume(&func->dev); if (wl->irq) free_irq(wl->irq, wl); wl1251_free_hw(wl); kfree(wl_sdio); sdio_claim_host(func); sdio_release_irq(func); sdio_disable_func(func); sdio_release_host(func); } static int wl1251_suspend(struct device *dev) { /* * Tell MMC/SDIO core it's OK to power down the card * (if it isn't already), but not to remove it completely. */ return 0; } static int wl1251_resume(struct device *dev) { return 0; } static const struct dev_pm_ops wl1251_sdio_pm_ops = { .suspend = wl1251_suspend, .resume = wl1251_resume, }; static struct sdio_driver wl1251_sdio_driver = { .name = "wl1251_sdio", .id_table = wl1251_devices, .probe = wl1251_sdio_probe, .remove = wl1251_sdio_remove, .drv.pm = &wl1251_sdio_pm_ops, }; static int __init wl1251_sdio_init(void) { int err; err = sdio_register_driver(&wl1251_sdio_driver); if (err) wl1251_error("failed to register sdio driver: %d", err); return err; } static void __exit wl1251_sdio_exit(void) { sdio_unregister_driver(&wl1251_sdio_driver); wl1251_notice("unloaded"); } module_init(wl1251_sdio_init); module_exit(wl1251_sdio_exit); MODULE_LICENSE("GPL"); MODULE_AUTHOR("Kalle Valo <kvalo@adurom.com>");