Merge "[docs] Move user guide chapters to make room for new chapter." into stable/fraser

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