summaryrefslogtreecommitdiffstats
path: root/docs/configguide/configguide.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/configguide/configguide.rst')
-rw-r--r--docs/configguide/configguide.rst204
1 files changed, 168 insertions, 36 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/