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 OPNFV deployment is out of the scope of this document but it can be found in
22 XXX. The OPNFV platform is considered as the System Under Test (SUT) in this
25 Several prerequisites are needed for functest:
27 1. A Jumphost to run Functest on
28 2. Docker daemon shall be installed on the Jumphost
29 3. A public/external network created on the SUT
30 4. Connectivity from the Jumphost to the SUT public/external network
31 5. Connectivity from the Jumphost to the SUT management network
33 NOTE: “Jumphost” refers to any server which meets the previous requirements.
34 Normally it is the same server from where the OPNFV deployment has been
40 .. _Ubuntu: https://docs.docker.com/installation/ubuntulinux/
41 .. _RHEL: https://docs.docker.com/installation/rhel/
43 Log on your jumphost then install docker (e.g. for Ubuntu)::
45 curl -sSL https://get.docker.com/ | sh
47 Add your user to docker group to be able to run commands without sudo::
49 sudo usermod -aG docker <your_user>
56 Connectivy to OPNFV management network
57 ======================================
59 Some of the Functest tools need to have access to the OpenStack management
60 network of the controllers `[1]`_.
62 For this reason, an interface shall be configured in the Jumphost in the
63 OpenStack management network range.
67 The OPNFV Fuel installation uses VLAN tagged 300 and subnet 192.168.1.0/24 as
68 Openstack Management network.
70 Supposing that eth1 is the physical interface with access to that subnet:
71 $ ip link add name eth1.300 link eth1 type vlan id 300
72 $ ip link set eth1.300 up
73 $ ip addr add 192.168.1.66/24 dev eth1.300
76 External network on SUT
77 =======================
79 Some of the tests against the VIM (Virtual Infrastructure Manager) need an
80 existing public network to succeed. This is needed, for example, to create
81 floating IPs to access instances from the public network (i.e. Jumphost).
83 By default, any of the four OPNFV installers provide a fresh installation with
84 an external network created along with a router.
88 =======================
89 High level architecture
90 =======================
92 The high level architecture of Functest within OPNFV can be described as follow::
94 CIMC/Lights+out management Admin Private Public Storage
100 | +----------------------------+ | | + |
102 +-----+ Jumphost | | | | |
103 | | +----------+ | | |
105 | | +--------------------+ | | | | |
107 | | | Tools | +--------------------+ | |
108 | | | - Rally | | | | | |
109 | | | - Robot | | | | | |
110 | | | - TestON | | | | | |
112 | | | Testcases | | | | | |
113 | | | - VIM | | | | | |
114 | | | -- vPing | | | | | |
115 | | | -- vPing_userdata | | | | | |
116 | | | -- Tempest | | | | | |
117 | | | -- Rally | | | | | |
118 | | | - Controller | | | | | |
119 | | | -- odl | | | | | |
120 | | | -- onos | | | | | |
121 | | | -- opencontrail | | | | | |
123 | | | Features | | | | | |
124 | | | - vIMS | | | | | |
126 | | +--------------------+ | | | | |
127 | | +------------------------------+ |
128 | | Functest Docker | | | | |
129 | | +---------------------------------------+
131 | +----------------------------+ | | | |
133 | +----------------+ | | | |
135 +----+ +--------------+-+ | | | |
137 | | | +--------------+-+ | | | |
139 | | | | +--------------+-+ | | | |
140 | | | | | 4 | | | | |
141 | +-+ | | +--------------+-+ | | | |
142 | | | | | 5 +---------------+ | | |
143 | +-+ | | nodes for | | | | |
144 | | | | deploying +-------------------------+ | |
145 | +-+ | opnfv | | | | |
146 | | | SUT +-----------------------------------+ |
148 | | +--------------------------------------------+
149 | +----------------+ | | | |
153 All the libraries and dependencies needed by all the Functest tools are
154 pre-installed in the Docker image.
155 This allows running Functest on any platform with any Operating System.
157 The Docker image will:
159 * retrieve OpenStack credentials
160 * prepare the environment according to the SUT
161 * perform the appropriate tests
162 * push the results into the OPNFV test result database
166 This Docker image can be integrated into CI or deployed **independently** of the CI.
167 A description of the Brahmaputra testcases can be retrieved in the Functest user
170 Please note that the Functest container has been designed for OPNFV, however, it
171 would be possible to adapt it to any VIM+controller environment as most of the
172 testcases are upstream testcases.
178 Pull the Functest Docker image from the Docker hub::
180 $ docker pull opnfv/functest:brahmaputra.1.0
183 Check that the image is available::
187 Run the docker container giving the environment variables
188 - INSTALLER_TYPE. Possible values are "apex", "compass", "fuel" or "joid".
189 - INSTALLER_IP. each installer has its installation strategy.
191 Functest may need to know the IP of the installer to retrieve the credentials
192 (e.g. usually "10.20.0.2" for fuel, not neede for joid...)
194 The minimum command to create the Functest docker file can be described as
197 docker run -it -e "INSTALLER_IP=10.20.0.2" -e "INSTALLER_TYPE=fuel" opnfv/functest:brahmaputra.1.0 /bin/bash
199 Optionnaly, it is possible to precise the container name through the option
202 docker run --name "CONTAINER_NAME" -it -e "INSTALLER_IP=10.20.0.2" -e "INSTALLER_TYPE=fuel" opnfv/functest:brahmaputra.1.0 /bin/bash
204 It is also possible to to indicate the path of the OpenStack creds using -v::
206 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
208 The local file will be mounted in the container under /home/opnfv/functest/conf/openstack.creds
210 After the run command the prompt appears which means that we are inside the
211 container and ready to run Functest.
213 Inside the container, you must have the following directory structure::
230 Basically the container includes:
232 * 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)
233 * 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)
235 The arborescence under the functest repo can be described as follow::
243 | `-- traffic-profile-guidelines.rst
248 | |-- requirements.pip
259 |-- config_functest.py
260 |-- config_functest.yaml
261 |-- functest_utils.py
262 |-- functest_utils.pyc
266 We may distinguish 4 different folders:
268 * commons: it is a folder dedicated to store traffic profile or any test inputs that could be reused by any test project
269 * docker: this folder includes the scripts that will be used to setup the environment and run the tests
270 * docs: this folder includes the user and installation/configuration guide
271 * testcases: this folder includes the scripts required by Functest internal test cases
274 Firstly run the script to install functest environment::
276 $ ${repos_dir}/functest/docker/prepare_env.sh
278 NOTE: ${repos_dir} is a default environment variable inside the docker container, which points to /home/opnfv/repos
280 Run the script to start the tests::
282 $ ${repos_dir}/functest/docker/run_tests.sh
284 NOTE: This will run ALL the tests by default, see `[2]`_ for details
286 Focus on the OpenStack credentials
287 ==================================
289 The OpenStack credentials are needed to test the VIM. There are 3 ways to
290 provide them to Functest:
292 * using the -v option when running the Docker container
293 * create an empty file in /home/opnfv/functest/conf/openstack.creds and paste the needed info in it.
294 * automatically retrieved using the following script::
295 $repos_dir/releng/utils/fetch_os_creds.sh
297 Once the credentials are there, they shall be sourced before running the tests::
299 source /home/opnfv/functest/conf/openstack.creds
304 In case you need to provide different configuration parameters to Functest (e.g.
305 commit IDs or branches for the repositories, …) copy the config_functest.yaml
306 from the repository to your current directory and run docker with a volume::
308 $ wget https://git.opnfv.org/cgit/functest/plain/testcases/config_functest.yaml
309 $ cmd1 = "/home/opnfv/repos/functest/docker/prepare_env.sh"
310 $ cmd2 = "/home/opnfv/repos/functest/docker/run_tests.sh"
311 $ docker run -t -e "INSTALLER_TYPE=fuel" -e "INSTALLER_IP=10.20.0.2" opnfv/functest \
312 -v $(pwd)/config_functest.yaml:/home/opnfv/functest/conf/config_functest.yaml \
318 In CI we use the docker file and execute commande within the container from
321 Docker creation in set-functest-env builder `[3]`_::
323 envs="INSTALLER_TYPE=${INSTALLER_TYPE} -e INSTALLER_IP=${INSTALLER_IP} -e NODE_NAME=${NODE_NAME}"
325 docker pull opnfv/functest:latest_stable
326 cmd="docker run -id -e $envs ${labconfig} ${sshkey} ${res_volume} opnfv/functest:latest_stable /bin/bash"
327 echo "Functest: Running docker run command: ${cmd}"
331 container_id=$(docker ps | grep 'opnfv/functest:latest_stable' | awk '{print $1}' | head -1)
332 echo "Container ID=${container_id}"
333 if [ -z ${container_id} ]; then
334 echo "Cannot find opnfv/functest container ID ${container_id}. Please check if it is existing."
338 echo "Starting the container: docker start ${container_id}"
339 docker start ${container_id}
342 if [ $(docker ps | grep 'opnfv/functest:latest_stable' | wc -l) == 0 ]; then
343 echo "The container opnfv/functest with ID=${container_id} has not been properly started. Exiting..."
346 cmd="${FUNCTEST_REPO_DIR}/docker/prepare_env.sh"
347 echo "Executing command inside the docker: ${cmd}"
348 docker exec ${container_id} ${cmd}
351 Test execution in functest-all builder `[3]`_::
353 echo "Functest: run $FUNCTEST_SUITE_NAME"
354 cmd="${FUNCTEST_REPO_DIR}/docker/run_tests.sh --test $FUNCTEST_SUITE_NAME ${flag}"
355 container_id=$(docker ps -a | grep opnfv/functest | awk '{print $1}' | head -1)
356 docker exec $container_id $cmd
358 Docker clean in functest-cleanup builder `[3]`_::
360 echo "Cleaning up docker containers/images..."
361 # Remove previous running containers if exist
362 if [[ ! -z $(docker ps -a | grep opnfv/functest) ]]; then
363 echo "Removing existing opnfv/functest containers..."
364 docker ps | grep opnfv/functest | awk '{print $1}' | xargs docker stop
365 docker ps -a | grep opnfv/functest | awk '{print $1}' | xargs docker rm
368 # Remove existing images if exist
369 if [[ ! -z $(docker images | grep opnfv/functest) ]]; then
370 echo "Docker images to remove:"
371 docker images | head -1 && docker images | grep opnfv/functest
372 image_tags=($(docker images | grep opnfv/functest | awk '{print $2}'))
373 for tag in "${image_tags[@]}"; do
374 echo "Removing docker image opnfv/functest:$tag..."
375 docker rmi opnfv/functest:$tag
384 Everything is preconfigured in the docker file.
385 It is however possible to customize the list of tests, see `[2]` for details.
398 .. _`[1]`: https://ask.openstack.org/en/question/68144/keystone-unable-to-use-the-public-endpoint/
399 .. _`[2]`: url functest user guide
400 .. _`[3]`: https://git.opnfv.org/cgit/releng/tree/jjb/functest/functest-ci-jobs.yml
403 OPNFV main site: opnfvmain_.
405 OPNFV functional test page: opnfvfunctest_.
407 IRC support chan: #opnfv-testperf
409 .. _opnfvmain: http://www.opnfv.org
410 .. _opnfvfunctest: https://wiki.opnfv.org/opnfv_functional_testing
411 .. _`OpenRC`: http://docs.openstack.org/user-guide/common/cli_set_environment_variables_using_openstack_rc.html
412 .. _`Rally installation procedure`: https://rally.readthedocs.org/en/latest/tutorial/step_0_installation.html
413 .. _`config_test.py` : https://git.opnfv.org/cgit/functest/tree/testcases/config_functest.py
414 .. _`config_functest.yaml` : https://git.opnfv.org/cgit/functest/tree/testcases/config_functest.yaml