aboutsummaryrefslogtreecommitdiffstats
path: root/docs/testing/user/userguide/04-installation.rst
diff options
context:
space:
mode:
authorEmma Foley <emma.l.foley@intel.com>2018-03-07 18:40:28 +0000
committerEmma Foley <emma.l.foley@intel.com>2018-04-10 13:56:40 +0000
commitb24dc4e0c48aa7d9aa98c3e06d6d2cd2c6bed1d6 (patch)
treee1468515485aeb63fd0656f629c956ef4b7925ad /docs/testing/user/userguide/04-installation.rst
parenteca2b80b5916aec6bbd65f8db4ae339904005d8d (diff)
[docs] Move user guide chapters to make room for new chapter.
* Increment the numbering on chapters * Fix some of the changes flagged by doc8 Change-Id: I9dbf4a3d33c2b38f7567bc3493466e72a59e1a0c Signed-off-by: Emma Foley <emma.l.foley@intel.com> (cherry picked from commit 3248682fcc789f95ff8246a8d1f208a6a3abd46d)
Diffstat (limited to 'docs/testing/user/userguide/04-installation.rst')
-rw-r--r--docs/testing/user/userguide/04-installation.rst292
1 files changed, 50 insertions, 242 deletions
diff --git a/docs/testing/user/userguide/04-installation.rst b/docs/testing/user/userguide/04-installation.rst
index cac814667..a4846230e 100644
--- a/docs/testing/user/userguide/04-installation.rst
+++ b/docs/testing/user/userguide/04-installation.rst
@@ -39,18 +39,18 @@ Several prerequisites are needed for Yardstick:
4. Connectivity from the Jumphost to the SUT public/external network
.. 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.
+ requirements. Normally it is the same server from where the OPNFV
+ deployment has been triggered.
.. 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.
+ 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:: If your Jumphost is operating behind a company http proxy and/or
-Firewall, please first consult `Proxy Support`_ section which is towards the
-end of this document. That section details some tips/tricks which *may* be of
-help in a proxified environment.
+ Firewall, please first consult `Proxy Support`_ section which is towards
+ the end of this document. That section details some tips/tricks which *may*
+ be of help in a proxified environment.
Install Yardstick using Docker (first option) (**recommended**)
@@ -85,27 +85,30 @@ Run the Docker image to get a Yardstick container::
docker run -itd --privileged -v /var/run/docker.sock:/var/run/docker.sock \
-p 8888:5000 --name yardstick opnfv/yardstick:stable
-.. table:: Description of the parameters used with ``docker run`` command
-
- ======================= ====================================================
- Parameters Detail
- ======================= ====================================================
- -itd -i: interactive, Keep STDIN open even if not
- attached
- -t: allocate a pseudo-TTY detached mode, in the
- background
- ======================= ====================================================
- --privileged If you want to build ``yardstick-image`` in
- Yardstick container, this parameter is needed
- ======================= ====================================================
- -p 8888:5000 Redirect the a host port (8888) to a container port
- (5000)
- ======================= ====================================================
- -v /var/run/docker.sock If you want to use yardstick env grafana/influxdb to
- :/var/run/docker.sock create a grafana/influxdb container out of Yardstick
- container
- ======================= ====================================================
- --name yardstick The name for this container
+Description of the parameters used with ``docker run`` command
+
+ +------------------------+--------------------------------------------------+
+ | Parameters | Detail |
+ +========================+==================================================+
+ | -itd | -i: interactive, Keep STDIN open even if not |
+ | | attached |
+ | +--------------------------------------------------+
+ | | -t: allocate a pseudo-TTY detached mode, in the |
+ | | background |
+ +------------------------+--------------------------------------------------+
+ | --privileged | If you want to build ``yardstick-image`` in |
+ | | Yardstick container, this parameter is needed |
+ +------------------------+--------------------------------------------------+
+ | -p 8888:5000 | Redirect the a host port (8888) to a container |
+ | | port (5000) |
+ +------------------------+--------------------------------------------------+
+ | -v /var/run/docker.sock| If you want to use yardstick env |
+ | :/var/run/docker.sock | grafana/influxdb to create a grafana/influxdb |
+ | | container out of Yardstick container |
+ +------------------------+--------------------------------------------------+
+ | --name yardstick | The name for this container |
+ +------------------------+--------------------------------------------------+
+
If the host is restarted
^^^^^^^^^^^^^^^^^^^^^^^^
@@ -135,18 +138,18 @@ automatically::
yardstick env prepare
.. note:: Since Euphrates release, the above command will not be able to
-automatically configure the ``/etc/yardstick/openstack.creds`` file. So before
-running the above command, it is necessary to create the
-``/etc/yardstick/openstack.creds`` file and save OpenStack environment
-variables into it manually. If you have the openstack credential file saved
-outside the Yardstick Docker container, you can do this easily by mapping the
-credential file into Yardstick container using::
+ automatically configure the ``/etc/yardstick/openstack.creds`` file. So before
+ running the above command, it is necessary to create the
+ ``/etc/yardstick/openstack.creds`` file and save OpenStack environment
+ variables into it manually. If you have the openstack credential file saved
+ outside the Yardstick Docker container, you can do this easily by mapping the
+ credential file into Yardstick container using::
- '-v /path/to/credential_file:/etc/yardstick/openstack.creds'
+ '-v /path/to/credential_file:/etc/yardstick/openstack.creds'
-when running the Yardstick container. For details of the required OpenStack
-environment variables please refer to section `Export OpenStack environment
-variables`_.
+ when running the Yardstick container. For details of the required OpenStack
+ environment variables please refer to section `Export OpenStack environment
+ variables`_.
The ``env prepare`` command may take up to 6-8 minutes to finish building
yardstick-image and other environment preparation. Meanwhile if you wish to
@@ -222,8 +225,8 @@ Yardstick is installed::
sudo -EH tools/yardstick-img-modify tools/ubuntu-server-cloudimg-modify.sh
.. warning:: Before building the guest image inside the Yardstick container,
-make sure the container is granted with privilege. The script will create files
-by default in ``/tmp/workspace/yardstick`` and the files will be owned by root.
+ make sure the container is granted with privilege. 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 OpenStack client or via
the OpenStack Dashboard::
@@ -270,7 +273,7 @@ For usage of Yardstick GUI, please watch our demo video at
`Yardstick GUI demo`_.
.. note:: The Yardstick GUI is still in development, the GUI layout and
-features may change.
+ features may change.
Delete the Yardstick container
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -433,7 +436,7 @@ of Yardstick ``help`` command and ``ping.py`` test sample::
yardstick task start samples/ping.yaml
.. note:: The above commands could be run in both the Yardstick container and
-the Ubuntu directly.
+ the Ubuntu directly.
Each testing tool supported by Yardstick has a sample configuration file.
These configuration files can be found in the ``samples`` directory.
@@ -468,10 +471,10 @@ Then you can run a test case and visit http://host_ip:1948
(``admin``/``admin``) to see the results.
.. note:: Executing ``yardstick env`` command to deploy InfluxDB and Grafana
-requires Jumphost's docker API version => 1.24. Run the following command to
-check the docker API version on the Jumphost::
+ requires Jumphost's docker API version => 1.24. Run the following command to
+ check the docker API version on the Jumphost::
- docker version
+ docker version
Manual deployment of InfluxDB and Grafana containers
@@ -537,200 +540,6 @@ Deploy InfluxDB and Grafana directly in Ubuntu (**Todo**)
---------------------------------------------------------
-Yardstick common CLI
---------------------
-
-List test cases
-^^^^^^^^^^^^^^^
-
-``yardstick testcase list``: This command line would list all test cases in
-Yardstick. It would show like below::
-
- +---------------------------------------------------------------------------------------
- | Testcase Name | Description
- +---------------------------------------------------------------------------------------
- | opnfv_yardstick_tc001 | Measure network throughput using pktgen
- | opnfv_yardstick_tc002 | measure network latency using ping
- | opnfv_yardstick_tc005 | Measure Storage IOPS, throughput and latency using fio.
- ...
- +---------------------------------------------------------------------------------------
-
-
-Show a test case config file
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Take opnfv_yardstick_tc002 for an example. This test case measure network
-latency. You just need to type in ``yardstick testcase show
-opnfv_yardstick_tc002``, and the console would show the config yaml of this
-test case::
-
- ---
-
- schema: "yardstick:task:0.1"
- description: >
- Yardstick TC002 config file;
- measure network latency using ping;
-
- {% set image = image or "cirros-0.3.5" %}
-
- {% set provider = provider or none %}
- {% set physical_network = physical_network or 'physnet1' %}
- {% set segmentation_id = segmentation_id or none %}
- {% set packetsize = packetsize or 100 %}
-
- scenarios:
- {% for i in range(2) %}
- -
- type: Ping
- options:
- packetsize: {{packetsize}}
- host: athena.demo
- target: ares.demo
-
- runner:
- type: Duration
- duration: 60
- interval: 10
-
- sla:
- max_rtt: 10
- action: monitor
- {% endfor %}
-
- context:
- name: demo
- image: {{image}}
- flavor: yardstick-flavor
- user: cirros
-
- placement_groups:
- pgrp1:
- policy: "availability"
-
- servers:
- athena:
- floating_ip: true
- placement: "pgrp1"
- ares:
- placement: "pgrp1"
-
- networks:
- test:
- cidr: '10.0.1.0/24'
- {% if provider == "vlan" %}
- provider: {{provider}}
- physical_network: {{physical_network}}å
- {% if segmentation_id %}
- segmentation_id: {{segmentation_id}}
- {% endif %}
- {% endif %}
-
-
-Start a task to run yardstick test case
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-If you want run a test case, then you need to use ``yardstick task start
-<test_case_path>`` this command support some parameters as below::
-
- +---------------------+--------------------------------------------------+
- | Parameters | Detail |
- +=====================+==================================================+
- | -d | show debug log of yardstick running |
- | | |
- +---------------------+--------------------------------------------------+
- | --task-args | If you want to customize test case parameters, |
- | | use "--task-args" to pass the value. The format |
- | | is a json string with parameter key-value pair. |
- | | |
- +---------------------+--------------------------------------------------+
- | --task-args-file | If you want to use yardstick |
- | | env prepare command(or |
- | | related API) to load the |
- +---------------------+--------------------------------------------------+
- | --parse-only | |
- | | |
- | | |
- +---------------------+--------------------------------------------------+
- | --output-file \ | Specify where to output the log. if not pass, |
- | OUTPUT_FILE_PATH | the default value is |
- | | "/tmp/yardstick/yardstick.log" |
- | | |
- +---------------------+--------------------------------------------------+
- | --suite \ | run a test suite, TEST_SUITE_PATH specify where |
- | TEST_SUITE_PATH | the test suite locates |
- | | |
- +---------------------+--------------------------------------------------+
-
-
-Run Yardstick in a local environment
-------------------------------------
-
-We also have a guide about how to run Yardstick in a local environment.
-This work is contributed by Tapio Tallgren.
-You can find this guide at `How to run Yardstick in a local environment`_.
-
-
-Create a test suite for Yardstick
-------------------------------------
-
-A test suite in yardstick is a yaml file which include one or more test cases.
-Yardstick is able to support running test suite task, so you can customize your
-own test suite and run it in one task.
-
-``tests/opnfv/test_suites`` is the folder where Yardstick puts CI test suite.
-A typical test suite is like below (the ``fuel_test_suite.yaml`` example)::
-
- ---
- # Fuel integration test task suite
-
- schema: "yardstick:suite:0.1"
-
- name: "fuel_test_suite"
- test_cases_dir: "samples/"
- test_cases:
- -
- file_name: ping.yaml
- -
- file_name: iperf3.yaml
-
-As you can see, there are two test cases in the ``fuel_test_suite.yaml``. The
-``schema`` and the ``name`` must be specified. The test cases should be listed
-via the tag ``test_cases`` and their relative path is also marked via the tag
-``test_cases_dir``.
-
-Yardstick test suite also supports constraints and task args for each test
-case. Here is another sample (the ``os-nosdn-nofeature-ha.yaml`` example) to
-show this, which is digested from one big test suite::
-
- ---
-
- schema: "yardstick:suite:0.1"
-
- name: "os-nosdn-nofeature-ha"
- test_cases_dir: "tests/opnfv/test_cases/"
- test_cases:
- -
- file_name: opnfv_yardstick_tc002.yaml
- -
- file_name: opnfv_yardstick_tc005.yaml
- -
- file_name: opnfv_yardstick_tc043.yaml
- constraint:
- installer: compass
- pod: huawei-pod1
- task_args:
- huawei-pod1: '{"pod_info": "etc/yardstick/.../pod.yaml",
- "host": "node4.LF","target": "node5.LF"}'
-
-As you can see in test case ``opnfv_yardstick_tc043.yaml``, there are two
-tags, ``constraint`` and ``task_args``. ``constraint`` is to specify which
-installer or pod it can be run in the CI environment. ``task_args`` is to
-specify the task arguments for each pod.
-
-All in all, to create a test suite in Yardstick, you just need to create a
-yaml file and add test cases, constraint or task arguments if necessary.
-
-
Proxy Support
-------------
@@ -790,7 +599,7 @@ stop and delete the container::
sudo docker rm yardstick
.. warning:: Be careful, the above ``rm`` command will delete the container
-completely. Everything on this container will be lost.
+ completely. Everything on this container will be lost.
Then follow the previous instructions `Prepare the Yardstick container`_ to
rebuild the Yardstick container.
@@ -804,4 +613,3 @@ References
.. _`Cirros 0.3.5`: http://download.cirros-cloud.net/0.3.5/cirros-0.3.5-x86_64-disk.img
.. _`Ubuntu 16.04`: https://cloud-images.ubuntu.com/xenial/current/xenial-server-cloudimg-amd64-disk1.img
.. _`Yardstick GUI demo`: https://www.youtube.com/watch?v=M3qbJDp6QBk
-.. _`How to run Yardstick in a local environment`: https://wiki.opnfv.org/display/yardstick/How+to+run+Yardstick+in+a+local+environment