Updates and fixes in the Config Guide

Change-Id: I71474490e18fcf33b70766cb4446ade2d58a80b8
Signed-off-by: jose.lausuch <jose.lausuch@ericsson.com>

2 files changed, 250 insertions, 156 deletions

diff --git a/docs/configguide/configguide.rst b/docs/configguide/configguide.rst
index 671b46333..82ba1e373 100644
--- a/docs/configguide/configguide.rst
+++ b/docs/configguide/configguide.rst
@@ -2,27 +2,27 @@
 .. http://creativecommons.org/licenses/by/4.0
 
 
-Functional testing Installation
--------------------------------
+Preparing the Docker container
+------------------------------
 
 Pull the Functest Docker image from the Docker hub::
 
-  $ docker pull opnfv/functest:brahmaputra.1.0
+  docker pull opnfv/functest:brahmaputra.1.0
 
 
 Check that the image is available::
 
- $ docker images
+  docker images
 
-Run the docker container giving the environment variables::
+Run the docker container giving the environment variables:
 
- - INSTALLER_TYPE. Possible values are "apex", "compass", "fuel" or "joid".
- - INSTALLER_IP. each installer has its installation strategy.
+ * INSTALLER_TYPE : possible values are "apex", "compass", "fuel" or "joid".
+ * INSTALLER_IP : IP of the installer node/VM.
 
-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...).
+Functest may need to know the IP of the installer to retrieve the credentials from
+the installer node/VM or even from the actual controllers.
 
-The minimum command to create the Functest docker file can be described as
+The minimum command to create the Functest Docker container can be described as
 follows::
 
   docker run -it -e "INSTALLER_IP=10.20.0.2" -e "INSTALLER_TYPE=fuel" opnfv/functest:brahmaputra.1.0 /bin/bash
@@ -32,15 +32,18 @@ Optionally, it is possible to precise the container name through the option
 
   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::
+It is also possible to to indicate the path of the OpenStack credentials 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:brahmaputra.1.0 /bin/bash
 
 The local file will be mounted in the container under
 /home/opnfv/functest/conf/openstack.creds
 
-After the run command the prompt appears which means that we are inside the
-container and ready to run Functest.
+If the intention is to run Functest against any of the supported OPNFV scenarios,
+it is recommended to include also the environment variable **DEPLOY_SCENARIO**,
+For instance::
+
+  docker run -it -e "INSTALLER_IP=10.20.0.2" -e "INSTALLER_TYPE=fuel" -e "DEPLOY_SCENARIO=os-odl_l2-nofeature-ha" opnfv/functest:brahmaputra.1.0 /bin/bash
 
 Inside the container, the following directory structure should be in place::
 
@@ -52,8 +55,11 @@ Inside the container, the following directory structure should be in place::
         |   `-- results
         `-- repos
             |-- bgpvpn
+            |-- doctor
             |-- functest
             |-- odl_integration
+            |-- onos
+            |-- promise
             |-- rally
             |-- releng
             `-- vims-test
@@ -61,15 +67,15 @@ Inside the container, the following directory structure should be in place::
 
 Basically the container includes:
 
-  * Functest directory to store the configuration (the OpenStack creds are paste
-    in /home/opngb/functest/conf), the data (images neede for test for offline
-    testing), results (some temporary artifacts may be stored here)
+  * Functest directory to store the configuration (the OpenStack creds are stored
+    in /home/opngb/functest/conf/openstack.creds), the data (cirros image needed for
+    some tests), results (some temporary result logs may be stored here)
   * Repositories: the functest repository will be used to prepare the
-    environment, run the tests. Other repositories are used for the installation
-    of the tooling (e.g. rally) and/or the retrieval of feature projects
-    scenarios (e.g. bgpvpn)
+    environment and run the tests. Other repositories are used for the installation
+    of the needed tooling (e.g. rally) and/or the retrieval of feature projects
+    scenarios (e.g. promise)
 
-The arborescence under the functest repo can be described as follow::
+The structure under the Functest repository can be described as follows::
 
   .
     |-- INFO
@@ -86,38 +92,164 @@ The arborescence under the functest repo can be described as follow::
     |   `-- run_tests.sh
     |-- docs
     |   |-- configguide
-    |   |-- functest.rst
+    |   |-- devguide
     |   |-- images
+    |   |-- results
     |   `-- userguide
     `-- testcases
         |-- Controllers
+        |-- features
+        |-- tests
         |-- VIM
+        |-- vIMS
+        |-- vPing
         |-- __init__.py
         |-- config_functest.py
         |-- config_functest.yaml
-        |-- functest_utils.py
-        |-- functest_utils.pyc
-        |-- vIMS
-        `-- vPing
+        `-- functest_utils.py
 
 We may distinguish 4 different folders:
 
-  * commons: it is a folder dedicated to store traffic profile or any test
+  * **commons**: it is a folder dedicated to store traffic profile or any test
     inputs that could be reused by any test project
-  * docker: this folder includes the scripts that will be used to setup the
+  * **docker**: this folder includes the scripts that will be used to setup the
     environment and run the tests
-  * docs: this folder includes the user and installation/configuration guide
-  * testcases: this folder includes the scripts required by Functest internal
-    test cases
+  * **docs**: this folder includes the user and installation/configuration guide
+  * **testcases**: this folder includes the scripts required by Functest internal
+    test cases and other feature projects test cases.
+
+After the *run* command, a new prompt appears which means that we are inside the
+container and ready to move to the next step.
+
+
+Useful Docker commands
+----------------------
+
+When typing **exit** in the container prompt, this will cause sometimes
+exiting the container and stopping it. When stopping a running Docker container
+all the changes will be lost when it is started again. There is a shortcut to
+quit the container without stopping it. Type CTRL+P+Q to keep the changes.
+To reconnect to the running container **DO NOT** use the *run* command again
+(since it will create a new container) use *exec* instead::
+
+  docker ps
+  <copy the container ID>
+  docker exec -ti <CONTAINER_ID> bash
+
+or simply::
+
+  docker exec -ti $(docker ps|grep functest|awk '{print $1}') bash
+
+There are other useful Docker commands that might be needed to manage possible
+issues with the containers.
+
+ * List the running containers::
+
+  docker ps
+
+ * List all the containers including the stopped ones::
+
+  docker ps -a
+
+ * It is useful sometimes to remove a container if there are some problems::
+
+  docker rm <CONTAINER_ID>
+
+ * Use the *-f* option if the container is still running, it will force to destroy it::
+
+  docker -f rm <CONTAINER_ID>
+
+The Docker image is named **opnfv/functest** and it is stored in the public
+Docker registry under the OPNFV account: dockerhub_.
+The are many different tags that have been created automatically by the CI
+mechanisms, but the one that this document refers to is **brahmaputra.1.0**.
+Other tags might cause some problems while running the tests.
+
+Check the Docker documentation dockerdocs_ for more information.
+
+
+Preparing the Functest environment
+----------------------------------
+
+Once the docker container is up and running, execute the following command in the
+prompt::
+
+ ${repos_dir}/functest/docker/prepare_env.sh
+
+NOTE: **${repos_dir}** is a default environment variable inside the docker
+container, which points to */home/opnfv/repos/*
+
+This script will make sure that the requirements to run the tests are met and will
+install the needed libraries and tools by all Functest test cases. It must be run
+only once every time the docker is started.
+
+
+Focus on the OpenStack credentials
+----------------------------------
+
+The OpenStack credentials are needed to run the tests against 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 credentials 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::
+
+    source /home/opnfv/functest/conf/openstack.creds
+
+or simply using the environment variable **$creds**::
+
+    . $creds
+
+After this, try to run any OpenStack command to see if you get any output,
+for instance::
+
+    openstack user list
+
+This will return a list of the actual users in the OpenStack deployment. In any
+other case, check that the credentials are sourced::
+
+    env|grep OS_
+
+This command must show a set of environment variables starting with *OS_*, for example::
+
+    OS_REGION_NAME=RegionOne
+    OS_DEFAULT_DOMAIN=default
+    OS_PROJECT_NAME=admin
+    OS_PASSWORD=admin
+    OS_AUTH_STRATEGY=keystone
+    OS_AUTH_URL=http://172.30.10.3:5000/v2.0
+    OS_USERNAME=admin
+    OS_TENANT_NAME=admin
+    OS_ENDPOINT_TYPE=internalURL
+    OS_NO_CACHE=true
+
+If still the OpenStack command does not show anything or complains about
+connectivity issues, it could be due to an incorrect url given to the OS_AUTH_URL
+environment variable. Check the deployment settings.
+
+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::
 
-Firstly run the script to install functest environment::
+    wget https://git.opnfv.org/cgit/functest/plain/testcases/config_functest.yaml
 
- $ ${repos_dir}/functest/docker/prepare_env.sh
+    <modify the file accordingly>
 
-NOTE: ${repos_dir} is a default environment variable inside the docker
-container, which points to /home/opnfv/repos
+    docker run -ti -e \
+    "INSTALLER_TYPE=fuel" -e "INSTALLER_IP=10.20.0.2" \
+    opnfv/functest:brahmaputra.1.0 \
+    -v $(pwd)/config_functest.yaml:/home/opnfv/functest/conf/config_functest.yaml \
+    /bin/bash\
 
-Run the script to start the tests::
+However, this is not recommended since most of the test cases rely on static
+parameters read from this file, and changing them might cause problems.
 
- $ ${repos_dir}/functest/docker/run_tests.sh
+.. _dockerdocs: https://docs.docker.com/
+.. _dockerhub: https://hub.docker.com/r/opnfv/functest/
diff --git a/docs/configguide/index.rst b/docs/configguide/index.rst
index e4a04330e..fc7b25bca 100644
--- a/docs/configguide/index.rst
+++ b/docs/configguide/index.rst
@@ -1,3 +1,6 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
 ===============================================
 OPNFV FUNCTEST configuration/installation guide
 ===============================================
@@ -9,85 +12,12 @@ OPNFV FUNCTEST configuration/installation guide
 Introduction
 ============
 
-** DOCUMENT IS IN PROGRESS FOR BRAHMAPUTRA **
-
 This document describes how to install and configure Functest in OPNFV.
 
-Prerequisites
-=============
-
-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:
-
-    #. A Jumphost to run Functest on
-    #. 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
-    #. 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
--------------------
-
-.. _Ubuntu: https://docs.docker.com/installation/ubuntulinux/
-.. _RHEL: https://docs.docker.com/installation/rhel/
-
-Log on your jumphost then install docker (e.g. for Ubuntu)::
-
- curl -sSL https://get.docker.com/ | sh
-
-Add your user to docker group to be able to run commands without sudo::
-
- sudo usermod -aG docker <your_user>
-
-
-References:
-
-  * Ubuntu_
-  * RHEL_
-
-Connectivity to OPNFV management network
-----------------------------------------
-
-Some of the Functest tools need to have access to the OpenStack management
-network of the controllers `[1]`_.
-
-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.
- .
- 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
- $ ip addr add 192.168.1.66/24 dev eth1.300
-
-
-External network on SUT
------------------------
-
-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.
-
-
-
 High level architecture
-=======================
+-----------------------
 
-The high level architecture of Functest within OPNFV can be described as follow::
+The high level architecture of Functest within OPNFV can be described as follows::
 
  CIMC/Lights+out management                 Admin     Private   Public   Storage
                                              PXE
@@ -152,7 +82,7 @@ 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:
+The automated mechanisms inside the Functest Docker container will:
 
   * retrieve OpenStack credentials
   * prepare the environment according to the SUT
@@ -160,55 +90,98 @@ The Docker image will:
   * push the results into the OPNFV test result database
 
 
-
 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.
+would be possible to adapt it to any VIM+controller environment since most of the
+test cases are integrated from upstream communities.
 
-.. include:: ./configguide.rst
+The test cases are described in the Functest User Guide `[2]`_
+
+
+Prerequisites
+=============
+
+The OPNFV deployment is out of the scope of this document but it can be found in
+`[4]`_. The OPNFV platform is considered as the System Under Test (SUT) in this
+document.
+
+Several prerequisites are needed for Functest:
+
+    #. A Jumphost to run Functest on
+    #. 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
+    #. 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
+-------------------
+
+.. _Ubuntu: https://docs.docker.com/installation/ubuntulinux/
+.. _RHEL: https://docs.docker.com/installation/rhel/
+
+Log on your Jumphost and install docker (e.g. for Ubuntu)::
+
+ curl -sSL https://get.docker.com/ | sh
+
+Add your user to docker group to be able to run commands without sudo::
+
+ sudo usermod -aG docker <your_user>
 
-NOTE: This will run ALL the tests by default, see `[2]`_ for details
 
-Focus on the OpenStack credentials
-----------------------------------
+References:
+
+  * Ubuntu_
+  * RHEL_
+
+External network on SUT
+-----------------------
+
+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, the four OPNFV installers provide a fresh installation with
+an external network created along with a router. Make sure that subnet
+is reachable from the Jumphost
+
+
+Connectivity to OPNFV management network
+----------------------------------------
 
-The OpenStack credentials are needed to test the VIM. There are 3 ways to
-provide them to Functest:
+Some of the Functest tools need to have access to the OpenStack management
+network of the controllers `[1]`_.
+
+For this reason, an interface shall be configured in the Jumphost in the
+OpenStack management network range.
 
-  * 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
+For example, if the management network is on VLAN 300 and subnet 192.168.1.0/24
+and assuming that eth1 is the physical interface with access to that subnet::
 
-Once the credentials are there, they shall be sourced before running the tests::
+ $ ip link add name eth1.300 link eth1 type vlan id 300
+ $ ip link set eth1.300 up
+ $ ip addr add 192.168.1.66/24 dev eth1.300
 
-    source /home/opnfv/functest/conf/openstack.creds
+This is just an example about how to configure an interface with vlan, but it might
+defer depending on the deployment settings on each installer. Check the
+corresponding installer instructions for more info.
 
-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::
+Installation and configuration
+==============================
 
-    $ wget https://git.opnfv.org/cgit/functest/plain/testcases/config_functest.yaml
-    $ cmd1 = "/home/opnfv/repos/functest/docker/prepare_env.sh"
-    $ cmd2 = "/home/opnfv/repos/functest/docker/run_tests.sh"
-    $ docker run -t -e "INSTALLER_TYPE=fuel" -e "INSTALLER_IP=10.20.0.2" opnfv/functest \
-        -v $(pwd)/config_functest.yaml:/home/opnfv/functest/conf/config_functest.yaml \
-        "${cmd1} && ${cmd2}"
+.. include:: ./configguide.rst
 
 
 Integration in CI
 =================
 
-In CI we use the docker file and execute commande within the container from
-Jenkins.
+In CI we use the Docker image and execute the appropriate commands within the
+container from Jenkins.
 
 Docker creation in set-functest-env builder `[3]`_::
 
@@ -269,24 +242,13 @@ Docker clean in functest-cleanup builder `[3]`_::
     fi
 
 
-Configuration
-=============
-
-Everything is preconfigured in the docker file.
-It is however possible to customize the list of tests, see `[2]` for details.
-
-Errors
-======
-
-
-
-
 
 References
 ==========
 .. _`[1]`: https://ask.openstack.org/en/question/68144/keystone-unable-to-use-the-public-endpoint/
-.. _`[2]`: url functest user guide
+.. _`[2]`: http://artifacts.opnfv.org/functest/docs/userguide/index.html
 .. _`[3]`: https://git.opnfv.org/cgit/releng/tree/jjb/functest/functest-ci-jobs.yml
+.. _`[4]`: http://artifacts.opnfv.org/opnfvdocs/brahmaputra/docs/configguide/index.html
 
 
 OPNFV main site: opnfvmain_.