1 ***********************************************
2 OPNFV FUNCTEST configuration/installation guide
3 ***********************************************
13 ** DOCUMENT IS IN PROGRESS FOR BRAHMAPUTRA **
15 This document describes how to install and configure Functest in OPNFV.
21 The installation of the OPNFV solution is out of scope of this document but can be found in XXX.
22 In the rest of the document the OPNFV solution would be considered as the System Under Test (SUT).
24 Several prerequisites are needed for functest:
25 1) docker must be installed on the Jumphost
26 2) a connectivity from the jumphost to the SUT management network is needed
27 3) an external network must be configured
32 .. _Ubuntu: https://docs.docker.com/installation/ubuntulinux/
33 .. _RHEL: https://docs.docker.com/installation/rhel/
35 Log on your jumphost then install docker (e.g. for Ubuntu)::
37 curl -sSL https://get.docker.com/ | sh
39 Add your user to docker group to be able to run commands without sudo::
41 sudo usermod -aG docker <your_user>
48 Connectivy to OPNFV management network
49 ======================================
51 Some of the Functest tools need to have access to the OpenStack management network of the controllers `[1]`_.
53 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).
57 The OPNFV Fuel installation uses VLAN tagged 300 and subnet 192.168.1.0/24 as Openstack Management network.
58 Supposing that eth1 is the physical interface with access to that subnet:
59 $ ip link add name eth1.300 link eth1 type vlan id 300
60 $ ip link set eth1.300 up
61 $ ip addr add 192.168.1.66/24 dev eth1.300
64 External network on SUT
65 =======================
67 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.
68 A default floating ip pool must be configured in nova.conf.
72 =======================
73 High level architecture
74 =======================
76 The high level architecture of Functest within OPNFV can be described as follow::
78 CIMC/Lights+out management Admin Private Public Storage
84 | +--------------------------+ | | + |
86 +-----+ Jumphost | | | | |
87 | | +--------------------+ | | |
89 | | +------------------+ | | | | |
91 | | | Tools | +------------------------------+ | |
92 | | | - Rally | | | | | |
93 | | | - Robot | | | | | |
94 | | | - TestON | | | | | |
96 | | | Testcases | | | | | |
97 | | | - VIM | | | | | |
98 | | | -- vPing | | | | | |
99 | | | -- Tempest | | | | | |
100 | | | -- Rally | | | | | |
101 | | | - Controller | | | | | |
102 | | | -- odl | | | | | |
103 | | | -- onos | | | | | |
104 | | | -- opencontrail | | | | | |
106 | | | Features | | | | | |
107 | | | - vIMS | | | | | |
109 | | +------------------+ | | | | |
110 | | +----------------------------------------+ |
111 | | Functest Docker | | | | |
112 | | +-------------------------------------------------+
114 | +--------------------------+ | | | |
116 | +----------------+ | | | |
118 +----+ +--------------+-+ | | | |
120 | | | +--------------+-+ | | | |
122 | | | | +--------------+-+ | | | |
123 | | | | | 4 | | | | |
124 | +-+ | | +--------------+-+ | | | |
125 | | | | | 5 +-----------------------+ | | |
126 | +-+ | | nodes for | | | | |
127 | | | | deploying +---------------------------------+ | |
128 | +-+ | opnfv | | | | |
129 | | | SUT +-------------------------------------------+ |
131 | | +----------------------------------------------------+
132 | +----------------+ | | | |
136 All the components needed by Functest are in the docker file.
137 Thanks to docker, there is no more library issues.
139 This docker file will:
140 * prepare the environment for functional testing
141 * retrieve SUT credentials
143 * push the results into the OPNFV test result database
145 This docker file can be integrated into CI or deployed independantly of the CI.
146 A description of the Brahmaputra testcases can be retrieved in the Functest user guide `[2]`_
148 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.
154 Pull the Functest Docker image from the hub::
156 $ docker pull opnfv/functest
158 Check that the image is available::
162 Run the docker container giving the environment variables
163 - INSTALLER_TYPE. Possible values are "apex", "compass", "fuel", "joid" or "foreman" (Arno).
164 - 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...)
166 The minimum command to create the Functest docker file can be described as follow::
168 docker run -it -e "INSTALLER_IP=10.20.0.2" -e "INSTALLER_TYPE=fuel" opnfv/functest:latest_stable /bin/bash
170 Optionnaly, it is possible to precise the container name through the option --name::
172 docker run --name "CONTAINER_NAME" -it -e "INSTALLER_IP=10.20.0.2" -e "INSTALLER_TYPE=fuel" opnfv/functest:latest_stable /bin/bash
174 It is also possible to to indicate the path of the OpenStack creds using -v::
176 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
178 Your local file will be paste within the container under /home/opnfv/functest/conf/openstack.creds and used by the different test suites.
180 Once run you shall be inside the docker container and ready to run Functest.
182 Inside the container, you must have the following arborescence::
199 Basically the container includes:
201 * 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)
202 * Repositories: the functest repository will be used to prepare the environement, 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)
204 The arborescence under the functest repo can be described as follow::
212 | `-- traffic-profile-guidelines.rst
217 | |-- requirements.pip
228 |-- config_functest.py
229 |-- config_functest.yaml
230 |-- functest_utils.py
231 |-- functest_utils.pyc
235 We may distinguish 4 different folders:
237 * commons: it is a folder dedicated to store traffic profile or any test inputs that could be reused by any test project
238 * docker: this folder includes the scripts that will be used to setup the environment and run the tests
239 * docs: this folder includes the user and installation/configuration guide
240 * testcases: this folder includes the scripts required by Functest internal test cases
243 Firstly run the script to install functest environment::
245 $ ${repos_dir}/functest/docker/prepare_env.sh
247 NOTE: ${repos_dir} is a default environment variable inside the docker container, which points to /home/opnfv/repos
249 Run the script to start the tests::
251 $ ${repos_dir}/functest/docker/run_tests.sh
253 NOTE: This will run ALL the tests by default, see `[2]`_ for details
255 Focus on the OpenStack credentials
256 ==================================
258 The OpenStack creds are needed to test the VIM. They can be retrieved in several ways:
259 * using the -v option when creating
260 * sourcing them manually once connected on the docker, once log perform a source <openstack_creds>
261 * automatically retrieved via a script (CI)
263 If not source you will get an error during the test environnement preparation.
268 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::
270 $ wget https://git.opnfv.org/cgit/functest/plain/testcases/config_functest.yaml
271 $ cmd1 = "/home/opnfv/repos/functest/docker/prepare_env.sh"
272 $ cmd2 = "/home/opnfv/repos/functest/docker/run_tests.sh"
273 $ docker run -t -e "INSTALLER_TYPE=fuel" -e "INSTALLER_IP=10.20.0.2" opnfv/functest \
274 -v $(pwd)/config_functest.yaml:/home/opnfv/functest/conf/config_functest.yaml \
280 In CI we use the docker file and execute commande within the container from Jenkins.
282 Docker creation in set-functest-env builder `[3]`_::
284 envs="INSTALLER_TYPE=${INSTALLER_TYPE} -e INSTALLER_IP=${INSTALLER_IP} -e NODE_NAME=${NODE_NAME}"
286 docker pull opnfv/functest:latest_stable
287 cmd="docker run -id -e $envs ${labconfig} ${sshkey} ${res_volume} opnfv/functest:latest_stable /bin/bash"
288 echo "Functest: Running docker run command: ${cmd}"
292 container_id=$(docker ps | grep 'opnfv/functest:latest_stable' | awk '{print $1}' | head -1)
293 echo "Container ID=${container_id}"
294 if [ -z ${container_id} ]; then
295 echo "Cannot find opnfv/functest container ID ${container_id}. Please check if it is existing."
299 echo "Starting the container: docker start ${container_id}"
300 docker start ${container_id}
303 if [ $(docker ps | grep 'opnfv/functest:latest_stable' | wc -l) == 0 ]; then
304 echo "The container opnfv/functest with ID=${container_id} has not been properly started. Exiting..."
307 cmd="${FUNCTEST_REPO_DIR}/docker/prepare_env.sh"
308 echo "Executing command inside the docker: ${cmd}"
309 docker exec ${container_id} ${cmd}
312 Test execution in functest-all builder `[3]`_::
314 echo "Functest: run $FUNCTEST_SUITE_NAME"
315 cmd="${FUNCTEST_REPO_DIR}/docker/run_tests.sh --test $FUNCTEST_SUITE_NAME ${flag}"
316 container_id=$(docker ps -a | grep opnfv/functest | awk '{print $1}' | head -1)
317 docker exec $container_id $cmd
319 Docker clean in functest-cleanup builder `[3]`_::
321 echo "Cleaning up docker containers/images..."
322 # Remove previous running containers if exist
323 if [[ ! -z $(docker ps -a | grep opnfv/functest) ]]; then
324 echo "Removing existing opnfv/functest containers..."
325 docker ps | grep opnfv/functest | awk '{print $1}' | xargs docker stop
326 docker ps -a | grep opnfv/functest | awk '{print $1}' | xargs docker rm
329 # Remove existing images if exist
330 if [[ ! -z $(docker images | grep opnfv/functest) ]]; then
331 echo "Docker images to remove:"
332 docker images | head -1 && docker images | grep opnfv/functest
333 image_tags=($(docker images | grep opnfv/functest | awk '{print $2}'))
334 for tag in "${image_tags[@]}"; do
335 echo "Removing docker image opnfv/functest:$tag..."
336 docker rmi opnfv/functest:$tag
345 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.
358 .. _`[1]`: https://ask.openstack.org/en/question/68144/keystone-unable-to-use-the-public-endpoint/
359 .. _`[2]`: url functest user guide
360 .. _`[3]`: https://git.opnfv.org/cgit/releng/tree/jjb/functest/functest-ci-jobs.yml
363 OPNFV main site: opnfvmain_.
365 OPNFV functional test page: opnfvfunctest_.
367 IRC support chan: #opnfv-testperf
369 .. _opnfvmain: http://www.opnfv.org
370 .. _opnfvfunctest: https://wiki.opnfv.org/opnfv_functional_testing
371 .. _`OpenRC`: http://docs.openstack.org/user-guide/common/cli_set_environment_variables_using_openstack_rc.html
372 .. _`Rally installation procedure`: https://rally.readthedocs.org/en/latest/tutorial/step_0_installation.html
373 .. _`config_test.py` : https://git.opnfv.org/cgit/functest/tree/testcases/config_functest.py
374 .. _`config_functest.yaml` : https://git.opnfv.org/cgit/functest/tree/testcases/config_functest.yaml