Update doc

Change-Id: I415f090e38fa382e0c768758b4b82dd3a7c9294f
Signed-off-by: Morgan Richomme <morgan.richomme@orange.com>

1 files changed, 138 insertions, 98 deletions

diff --git a/docs/configguide/index.rst b/docs/configguide/index.rst
index 85954e77..52bc6272 100644
--- a/docs/configguide/index.rst
+++ b/docs/configguide/index.rst
@@ -18,13 +18,21 @@ This document describes how to install and configure Functest in OPNFV.
 Prerequisites
 =============
 
-The installation of the OPNFV solution is out of scope of this document but can be found in XXX.
-In the rest of the document the OPNFV solution would be considered as the System Under Test (SUT).
+The OPNFV deployment is out of the scope of this document but it can be found in
+XXX. The OPNFV platform is considered as the System Under Test (SUT) in this
+document.
 
 Several prerequisites are needed for functest:
- 1) docker must be installed on the Jumphost
- 2) a connectivity from the jumphost to the SUT management network is needed
- 3) an external network must be configured
+
+    1. A Jumphost to run Functest on
+    2. Docker daemon shall be installed on the Jumphost
+    3. A public/external network created on the SUT
+    4. Connectivity from the Jumphost to the SUT public/external network
+    5. Connectivity from the Jumphost to the SUT management 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.
 
 Docker installation
 ===================
@@ -48,13 +56,17 @@ References:
 Connectivy to OPNFV management network
 ======================================
 
-Some of the Functest tools need to have access to the OpenStack management network of the controllers `[1]`_.
+Some of the Functest tools need to have access to the OpenStack management
+network of the controllers `[1]`_.
 
-For this reason and besides the public network, you need to configure an interface on the management network as well in your jumphost (or wherever you want to deploy the Functest docker to run the tests).
+For this reason, an interface shall be configured in the Jumphost in the
+OpenStack management network range. 
 
 Example::
 
- The OPNFV Fuel installation uses VLAN tagged 300 and subnet 192.168.1.0/24 as Openstack Management network.
+ The OPNFV Fuel installation uses VLAN tagged 300 and subnet 192.168.1.0/24 as
+ Openstack Management network.
+ 
  Supposing that eth1 is the physical interface with access to that subnet:
  $ ip link add name eth1.300 link eth1 type vlan id 300
  $ ip link set eth1.300 up
@@ -64,8 +76,12 @@ Example::
 External network on SUT
 =======================
 
-Some of the tests on VIM need an external network. You may perform functest without an external network but some of the tests will fail.
-A default floating ip pool must be configured in nova.conf.
+Some of the tests against the VIM (Virtual Infrastructure Manager) need an
+existing public network to succeed. This is needed, for example, to create
+floating IPs to access instances from the public network (i.e. Jumphost).
+
+By default, any of the four OPNFV installers provide a fresh installation with
+an external network created along with a router. 
 
 
 
@@ -75,111 +91,126 @@ High level architecture
 
 The high level architecture of Functest within OPNFV can be described as follow::
 
- CIMC/Lights+out management                         Admin     Private   Public   Storage
-                                                     PXE
-                                                                           +
- +                                                     +     IP_PRIV/24    |        |
- |                                                     |         +         +        |
- |                                                     |         |    IP_PUB/24     |
- |     +--------------------------+                    |         |         +        |
- |     |                          |                    |         |         |        |
- +-----+       Jumphost           |                    |         |         |        |
- |     |                          +--------------------+         |         |        |
- |     |                          |                    |         |         |        |
- |     |   +------------------+   |                    |         |         |        |
- |     |   |                  |   |                    |         |         |        |
- |     |   | Tools            |   +------------------------------+         |        |
- |     |   | - Rally          |   |                    |         |         |        |
- |     |   | - Robot          |   |                    |         |         |        |
- |     |   | - TestON         |   |                    |         |         |        |
- |     |   |                  |   |                    |         |         |        |
- |     |   | Testcases        |   |                    |         |         |        |
- |     |   | - VIM            |   |                    |         |         |        |
- |     |   |  -- vPing        |   |                    |         |         |        |
- |     |   |  -- Tempest      |   |                    |         |         |        |
- |     |   |  -- Rally        |   |                    |         |         |        |
- |     |   | - Controller     |   |                    |         |         |        |
- |     |   |  -- odl          |   |                    |         |         |        |
- |     |   |  -- onos         |   |                    |         |         |        |
- |     |   |  -- opencontrail |   |                    |         |         |        |
- |     |   |                  |   |                    |         |         |        |
- |     |   | Features         |   |                    |         |         |        |
- |     |   | - vIMS           |   |                    |         |         |        |
- |     |   |                  |   |                    |         |         |        |
- |     |   +------------------+   |                    |         |         |        |
- |     |                          +----------------------------------------+        |
- |     |    Functest Docker       |                    |         |         |        |
- |     |                          +-------------------------------------------------+
- |     |                          |                    |         |         |        |
- |     +--------------------------+                    |         |         |        |
- |                                                     |         |         |        |
- |    +----------------+                               |         |         |        |
- |    |             1  |                               |         |         |        |
- +----+ +--------------+-+                             |         |         |        |
- |    | |             2  |                             |         |         |        |
- |    | | +--------------+-+                           |         |         |        |
- |    | | |             3  |                           |         |         |        |
- |    | | | +--------------+-+                         |         |         |        |
- |    | | | |             4  |                         |         |         |        |
- |    +-+ | | +--------------+-+                       |         |         |        |
- |      | | | |             5  +-----------------------+         |         |        |
- |      +-+ | |  nodes for     |                       |         |         |        |
- |        | | |  deploying     +---------------------------------+         |        |
- |        +-+ |  opnfv         |                       |         |         |        |
- |          | |     SUT        +-------------------------------------------+        |
- |          +-+                |                       |         |         |        |
- |            |                +----------------------------------------------------+
- |            +----------------+                       |         |         |        |
- |                                                     |         |         |        |
- |                                                     +         +         +        +
-
-All the components needed by Functest are in the docker file.
-Thanks to docker, there is no more library issues.
-
-This docker file will:
-  * prepare the environment for functional testing
-  * retrieve SUT credentials
-  * perform the tests
+ CIMC/Lights+out management                 Admin     Private   Public   Storage
+                                             PXE
+                                                                   +
+ +                                             +     IP_PRIV/24    |        |
+ |                                             |         +         +        |
+ |                                             |         |    IP_PUB/24     |
+ |     +----------------------------+          |         |         +        |
+ |     |                            |          |         |         |        |
+ +-----+       Jumphost             |          |         |         |        |
+ |     |                            +----------+         |         |        |
+ |     |                            |          |         |         |        |
+ |     |   +--------------------+   |          |         |         |        |
+ |     |   |                    |   |          |         |         |        |
+ |     |   | Tools              |   +--------------------+         |        |
+ |     |   | - Rally            |   |          |         |         |        |
+ |     |   | - Robot            |   |          |         |         |        |
+ |     |   | - TestON           |   |          |         |         |        |
+ |     |   |                    |   |          |         |         |        |
+ |     |   | Testcases          |   |          |         |         |        |
+ |     |   | - VIM              |   |          |         |         |        |
+ |     |   |  -- vPing          |   |          |         |         |        |
+ |     |   |  -- vPing_userdata |   |          |         |         |        |
+ |     |   |  -- Tempest        |   |          |         |         |        |
+ |     |   |  -- Rally          |   |          |         |         |        |
+ |     |   | - Controller       |   |          |         |         |        |
+ |     |   |  -- odl            |   |          |         |         |        |
+ |     |   |  -- onos           |   |          |         |         |        |
+ |     |   |  -- opencontrail   |   |          |         |         |        |
+ |     |   |                    |   |          |         |         |        |
+ |     |   | Features           |   |          |         |         |        |
+ |     |   | - vIMS             |   |          |         |         |        |
+ |     |   |                    |   |          |         |         |        |
+ |     |   +--------------------+   |          |         |         |        |
+ |     |                            +------------------------------+        |
+ |     |    Functest Docker         |          |         |         |        |
+ |     |                            +---------------------------------------+
+ |     |                            |          |         |         |        |
+ |     +----------------------------+          |         |         |        |
+ |                                             |         |         |        |
+ |    +----------------+                       |         |         |        |
+ |    |             1  |                       |         |         |        |
+ +----+ +--------------+-+                     |         |         |        |
+ |    | |             2  |                     |         |         |        |
+ |    | | +--------------+-+                   |         |         |        |
+ |    | | |             3  |                   |         |         |        |
+ |    | | | +--------------+-+                 |         |         |        |
+ |    | | | |             4  |                 |         |         |        |
+ |    +-+ | | +--------------+-+               |         |         |        |
+ |      | | | |             5  +---------------+         |         |        |
+ |      +-+ | |  nodes for     |               |         |         |        |
+ |        | | |  deploying     +-------------------------+         |        |
+ |        +-+ |  opnfv         |               |         |         |        |
+ |          | |     SUT        +-----------------------------------+        |
+ |          +-+                |               |         |         |        |
+ |            |                +--------------------------------------------+
+ |            +----------------+               |         |         |        |
+ |                                             |         |         |        |
+ |                                             +         +         +        +
+
+All the libraries and dependencies needed by all the Functest tools are
+pre-installed in the Docker image.
+This allows running Functest on any platform with any Operating System. 
+
+The Docker image will:
+  
+  * retrieve OpenStack credentials
+  * prepare the environment according to the SUT
+  * perform the appropriate tests
   * push the results into the OPNFV test result database
 
-This docker file can be integrated into CI or deployed independantly of the CI.
-A description of the Brahmaputra testcases can be retrieved in the Functest user guide `[2]`_
+ 
+
+This Docker image can be integrated into CI or deployed **independently** of the CI.
+A description of the Brahmaputra testcases can be retrieved in the Functest user
+guide `[2]`_
 
-Please note that the Functest container has been designed for OPNFV, however, it would be possible to adapt it to any VIM+controller environment as most of the testcases are upstream testcases.
+Please note that the Functest container has been designed for OPNFV, however, it
+would be possible to adapt it to any VIM+controller environment as most of the
+testcases are upstream testcases.
 
 ===================
 Manual Installation
 ===================
 
-Pull the Functest Docker image from the hub::
+Pull the Functest Docker image from the Docker hub::
+
+  $ docker pull opnfv/functest:brahmaputra.1.0  
 
- $ docker pull opnfv/functest
 
 Check that the image is available::
 
  $ docker images
 
 Run the docker container giving the environment variables
- - INSTALLER_TYPE. Possible values are "apex", "compass", "fuel", "joid" or "foreman" (Arno).
- - INSTALLER_IP. each installer has its installation strategy. Functest may need to know the IP of the installer to retrieve the credentials (e.g. usually "10.20.0.2" for fuel, not neede for joid, "172.30.10.73" foreman...)
+ - INSTALLER_TYPE. Possible values are "apex", "compass", "fuel" or "joid".
+ - INSTALLER_IP. each installer has its installation strategy.
+ 
+ Functest may need to know the IP of the installer to retrieve the credentials
+(e.g. usually "10.20.0.2" for fuel, not neede for joid...)
 
-The minimum command to create the Functest docker file can be described as follow::
+The minimum command to create the Functest docker file can be described as
+follows::
 
- docker run -it -e "INSTALLER_IP=10.20.0.2" -e "INSTALLER_TYPE=fuel" opnfv/functest:latest_stable /bin/bash
+  docker run -it -e "INSTALLER_IP=10.20.0.2" -e "INSTALLER_TYPE=fuel" opnfv/functest:brahmaputra.1.0 /bin/bash
 
-Optionnaly, it is possible to precise the container name through the option --name::
+Optionnaly, it is possible to precise the container name through the option
+--name::
 
- docker run --name "CONTAINER_NAME" -it -e "INSTALLER_IP=10.20.0.2" -e "INSTALLER_TYPE=fuel" opnfv/functest:latest_stable /bin/bash
+  docker run --name "CONTAINER_NAME" -it -e "INSTALLER_IP=10.20.0.2" -e "INSTALLER_TYPE=fuel" opnfv/functest:brahmaputra.1.0 /bin/bash
 
 It is also possible to to indicate the path of the OpenStack creds using -v::
 
- docker run  -it -e "INSTALLER_IP=10.20.0.2" -e "INSTALLER_TYPE=fuel" -v <path_to_your_local_creds_file>:/home/opnfv/functest/conf/openstack.creds opnfv/functest:latest_stable /bin/bash
+  docker run  -it -e "INSTALLER_IP=10.20.0.2" -e "INSTALLER_TYPE=fuel" -v <path_to_your_local_creds_file>:/home/opnfv/functest/conf/openstack.creds opnfv/functest:brahmaputra.1.0 /bin/bash
 
-Your local file will be paste within the container under /home/opnfv/functest/conf/openstack.creds and used by the different test suites.
+The local file will be mounted in the container under /home/opnfv/functest/conf/openstack.creds
 
-Once run you shall be inside the docker container and ready to run Functest.
+After the run command the prompt appears which means that we are inside the
+container and ready to run Functest.
 
-Inside the container, you must have the following arborescence::
+Inside the container, you must have the following directory structure::
 
   `-- home
       `-- opnfv
@@ -255,17 +286,24 @@ NOTE: This will run ALL the tests by default, see `[2]`_ for details
 Focus on the OpenStack credentials
 ==================================
 
-The OpenStack creds are needed to test the VIM. They can be retrieved in several ways:
-  * using the -v option when creating
-  * sourcing them manually once connected on the docker, once log perform a source <openstack_creds>
-  * automatically retrieved via a script (CI)
+The OpenStack credentials are needed to test the VIM. There are 3 ways to
+provide them to Functest:
+
+  * using the -v option when running the Docker container
+  * create an empty file in /home/opnfv/functest/conf/openstack.creds and paste the needed info in it.
+  * automatically retrieved using the following script::
+         $repos_dir/releng/utils/fetch_os_creds.sh
+
+Once the credentials are there, they shall be sourced before running the tests::
 
-If not source you will get an error during the test environnement preparation.
+  source /home/opnfv/functest/conf/openstack.creds
 
 Additional Options
 ==================
 
-In case you need to provide different configuration parameters to Functest (e.g. commit IDs or branches for the repositories, …) copy the config_functest.yaml from the repository to your current directory and run docker with a volume::
+In case you need to provide different configuration parameters to Functest (e.g.
+ commit IDs or branches for the repositories, …) copy the config_functest.yaml
+ from the repository to your current directory and run docker with a volume::
 
  $ wget https://git.opnfv.org/cgit/functest/plain/testcases/config_functest.yaml
  $ cmd1 = "/home/opnfv/repos/functest/docker/prepare_env.sh"
@@ -277,7 +315,8 @@ In case you need to provide different configuration parameters to Functest (e.g.
 =================
 Integration in CI
 =================
-In CI we use the docker file and execute commande within the container from Jenkins.
+In CI we use the docker file and execute commande within the container from
+Jenkins.
 
 Docker creation in set-functest-env builder `[3]`_::
 
@@ -342,7 +381,8 @@ Docker clean in functest-cleanup builder `[3]`_::
 Configuration
 =============
 
-Everything is preconfigured in the docker file. So except the credentials, there is no specific configuration needed. it is possible to customize the list of tests, see `[2]` for details.
+Everything is preconfigured in the docker file. 
+It is however possible to customize the list of tests, see `[2]` for details.
 
 ======
 Errors