1 ===============================================
2 OPNFV FUNCTEST configuration/installation guide
3 ===============================================
12 ** DOCUMENT IS IN PROGRESS FOR BRAHMAPUTRA **
14 This document describes how to install and configure Functest in OPNFV.
19 The OPNFV deployment is out of the scope of this document but it can be found in
20 XXX. The OPNFV platform is considered as the System Under Test (SUT) in this
23 Several prerequisites are needed for functest:
25 #. A Jumphost to run Functest on
26 #. Docker daemon shall be installed on the Jumphost
27 #. A public/external network created on the SUT
28 #. Connectivity from the Jumphost to the SUT public/external network
29 #. Connectivity from the Jumphost to the SUT management network
31 NOTE: “Jumphost” refers to any server which meets the previous requirements.
32 Normally it is the same server from where the OPNFV deployment has been
38 .. _Ubuntu: https://docs.docker.com/installation/ubuntulinux/
39 .. _RHEL: https://docs.docker.com/installation/rhel/
41 Log on your jumphost then install docker (e.g. for Ubuntu)::
43 curl -sSL https://get.docker.com/ | sh
45 Add your user to docker group to be able to run commands without sudo::
47 sudo usermod -aG docker <your_user>
55 Connectivity to OPNFV management network
56 ----------------------------------------
58 Some of the Functest tools need to have access to the OpenStack management
59 network of the controllers `[1]`_.
61 For this reason, an interface shall be configured in the Jumphost in the
62 OpenStack management network range.
66 The OPNFV Fuel installation uses VLAN tagged 300 and subnet 192.168.1.0/24 as
67 Openstack Management network.
69 Supposing that eth1 is the physical interface with access to that subnet:
70 $ ip link add name eth1.300 link eth1 type vlan id 300
71 $ ip link set eth1.300 up
72 $ ip addr add 192.168.1.66/24 dev eth1.300
75 External network on SUT
76 -----------------------
78 Some of the tests against the VIM (Virtual Infrastructure Manager) need an
79 existing public network to succeed. This is needed, for example, to create
80 floating IPs to access instances from the public network (i.e. Jumphost).
82 By default, any of the four OPNFV installers provide a fresh installation with
83 an external network created along with a router.
87 High level architecture
88 =======================
90 The high level architecture of Functest within OPNFV can be described as follow::
92 CIMC/Lights+out management Admin Private Public Storage
98 | +----------------------------+ | | + |
100 +-----+ Jumphost | | | | |
101 | | +----------+ | | |
103 | | +--------------------+ | | | | |
105 | | | Tools | +--------------------+ | |
106 | | | - Rally | | | | | |
107 | | | - Robot | | | | | |
108 | | | - TestON | | | | | |
110 | | | Testcases | | | | | |
111 | | | - VIM | | | | | |
112 | | | -- vPing | | | | | |
113 | | | -- vPing_userdata | | | | | |
114 | | | -- Tempest | | | | | |
115 | | | -- Rally | | | | | |
116 | | | - Controller | | | | | |
117 | | | -- odl | | | | | |
118 | | | -- onos | | | | | |
119 | | | -- opencontrail | | | | | |
121 | | | Features | | | | | |
122 | | | - vIMS | | | | | |
124 | | +--------------------+ | | | | |
125 | | +------------------------------+ |
126 | | Functest Docker | | | | |
127 | | +---------------------------------------+
129 | +----------------------------+ | | | |
131 | +----------------+ | | | |
133 +----+ +--------------+-+ | | | |
135 | | | +--------------+-+ | | | |
137 | | | | +--------------+-+ | | | |
138 | | | | | 4 | | | | |
139 | +-+ | | +--------------+-+ | | | |
140 | | | | | 5 +---------------+ | | |
141 | +-+ | | nodes for | | | | |
142 | | | | deploying +-------------------------+ | |
143 | +-+ | opnfv | | | | |
144 | | | SUT +-----------------------------------+ |
146 | | +--------------------------------------------+
147 | +----------------+ | | | |
151 All the libraries and dependencies needed by all the Functest tools are
152 pre-installed in the Docker image.
153 This allows running Functest on any platform with any Operating System.
155 The Docker image will:
157 * retrieve OpenStack credentials
158 * prepare the environment according to the SUT
159 * perform the appropriate tests
160 * push the results into the OPNFV test result database
164 This Docker image can be integrated into CI or deployed **independently** of the CI.
165 A description of the Brahmaputra testcases can be retrieved in the Functest user
168 Please note that the Functest container has been designed for OPNFV, however, it
169 would be possible to adapt it to any VIM+controller environment as most of the
170 testcases are upstream testcases.
175 Pull the Functest Docker image from the Docker hub::
177 $ docker pull opnfv/functest:brahmaputra.1.0
180 Check that the image is available::
184 Run the docker container giving the environment variables::
186 - INSTALLER_TYPE. Possible values are "apex", "compass", "fuel" or "joid".
187 - INSTALLER_IP. each installer has its installation strategy.
189 Functest may need to know the IP of the installer to retrieve the credentials
190 (e.g. usually "10.20.0.2" for fuel, not neede for joid...).
192 The minimum command to create the Functest docker file can be described as
195 docker run -it -e "INSTALLER_IP=10.20.0.2" -e "INSTALLER_TYPE=fuel" opnfv/functest:brahmaputra.1.0 /bin/bash
197 Optionally, it is possible to precise the container name through the option
200 docker run --name "CONTAINER_NAME" -it -e "INSTALLER_IP=10.20.0.2" -e "INSTALLER_TYPE=fuel" opnfv/functest:brahmaputra.1.0 /bin/bash
202 It is also possible to to indicate the path of the OpenStack creds using -v::
204 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
206 The local file will be mounted in the container under
207 /home/opnfv/functest/conf/openstack.creds
209 After the run command the prompt appears which means that we are inside the
210 container and ready to run Functest.
212 Inside the container, you must have the following directory structure::
229 Basically the container includes:
231 * Functest directory to store the configuration (the OpenStack creds are paste
232 in /home/opngb/functest/conf), the data (images neede for test for offline
233 testing), results (some temporary artifacts may be stored here)
234 * Repositories: the functest repository will be used to prepare the
235 environment, run the tests. Other repositories are used for the installation
236 of the tooling (e.g. rally) and/or the retrieval of feature projects
237 scenarios (e.g. bgpvpn)
239 The arborescence under the functest repo can be described as follow::
247 | `-- traffic-profile-guidelines.rst
252 | |-- requirements.pip
263 |-- config_functest.py
264 |-- config_functest.yaml
265 |-- functest_utils.py
266 |-- functest_utils.pyc
270 We may distinguish 4 different folders:
272 * commons: it is a folder dedicated to store traffic profile or any test
273 inputs that could be reused by any test project
274 * docker: this folder includes the scripts that will be used to setup the
275 environment and run the tests
276 * docs: this folder includes the user and installation/configuration guide
277 * testcases: this folder includes the scripts required by Functest internal
281 Firstly run the script to install functest environment::
283 $ ${repos_dir}/functest/docker/prepare_env.sh
285 NOTE: ${repos_dir} is a default environment variable inside the docker
286 container, which points to /home/opnfv/repos
288 Run the script to start the tests::
290 $ ${repos_dir}/functest/docker/run_tests.sh
292 NOTE: This will run ALL the tests by default, see `[2]`_ for details
294 Focus on the OpenStack credentials
295 ----------------------------------
297 The OpenStack credentials are needed to test the VIM. There are 3 ways to
298 provide them to Functest:
300 * using the -v option when running the Docker container
301 * create an empty file in /home/opnfv/functest/conf/openstack.creds and paste
302 the needed info in it.
303 * automatically retrieved using the following script::
304 $repos_dir/releng/utils/fetch_os_creds.sh
306 Once the credentials are there, they shall be sourced before running the tests::
308 source /home/opnfv/functest/conf/openstack.creds
313 In case you need to provide different configuration parameters to Functest (e.g.
314 commit IDs or branches for the repositories, ...) copy the config_functest.yaml
315 from the repository to your current directory and run docker with a volume::
317 $ wget https://git.opnfv.org/cgit/functest/plain/testcases/config_functest.yaml
318 $ cmd1 = "/home/opnfv/repos/functest/docker/prepare_env.sh"
319 $ cmd2 = "/home/opnfv/repos/functest/docker/run_tests.sh"
320 $ docker run -t -e "INSTALLER_TYPE=fuel" -e "INSTALLER_IP=10.20.0.2" opnfv/functest \
321 -v $(pwd)/config_functest.yaml:/home/opnfv/functest/conf/config_functest.yaml \
328 In CI we use the docker file and execute commande within the container from
331 Docker creation in set-functest-env builder `[3]`_::
333 envs="INSTALLER_TYPE=${INSTALLER_TYPE} -e INSTALLER_IP=${INSTALLER_IP} -e NODE_NAME=${NODE_NAME}"
335 docker pull opnfv/functest:latest_stable
336 cmd="docker run -id -e $envs ${labconfig} ${sshkey} ${res_volume} opnfv/functest:latest_stable /bin/bash"
337 echo "Functest: Running docker run command: ${cmd}"
341 container_id=$(docker ps | grep 'opnfv/functest:latest_stable' | awk '{print $1}' | head -1)
342 echo "Container ID=${container_id}"
343 if [ -z ${container_id} ]; then
344 echo "Cannot find opnfv/functest container ID ${container_id}. Please check if it is existing."
348 echo "Starting the container: docker start ${container_id}"
349 docker start ${container_id}
352 if [ $(docker ps | grep 'opnfv/functest:latest_stable' | wc -l) == 0 ]; then
353 echo "The container opnfv/functest with ID=${container_id} has not been properly started. Exiting..."
356 cmd="${FUNCTEST_REPO_DIR}/docker/prepare_env.sh"
357 echo "Executing command inside the docker: ${cmd}"
358 docker exec ${container_id} ${cmd}
361 Test execution in functest-all builder `[3]`_::
363 echo "Functest: run $FUNCTEST_SUITE_NAME"
364 cmd="${FUNCTEST_REPO_DIR}/docker/run_tests.sh --test $FUNCTEST_SUITE_NAME ${flag}"
365 container_id=$(docker ps -a | grep opnfv/functest | awk '{print $1}' | head -1)
366 docker exec $container_id $cmd
368 Docker clean in functest-cleanup builder `[3]`_::
370 echo "Cleaning up docker containers/images..."
371 # Remove previous running containers if exist
372 if [[ ! -z $(docker ps -a | grep opnfv/functest) ]]; then
373 echo "Removing existing opnfv/functest containers..."
374 docker ps | grep opnfv/functest | awk '{print $1}' | xargs docker stop
375 docker ps -a | grep opnfv/functest | awk '{print $1}' | xargs docker rm
378 # Remove existing images if exist
379 if [[ ! -z $(docker images | grep opnfv/functest) ]]; then
380 echo "Docker images to remove:"
381 docker images | head -1 && docker images | grep opnfv/functest
382 image_tags=($(docker images | grep opnfv/functest | awk '{print $2}'))
383 for tag in "${image_tags[@]}"; do
384 echo "Removing docker image opnfv/functest:$tag..."
385 docker rmi opnfv/functest:$tag
393 Everything is preconfigured in the docker file.
394 It is however possible to customize the list of tests, see `[2]` for details.
405 .. _`[1]`: https://ask.openstack.org/en/question/68144/keystone-unable-to-use-the-public-endpoint/
406 .. _`[2]`: url functest user guide
407 .. _`[3]`: https://git.opnfv.org/cgit/releng/tree/jjb/functest/functest-ci-jobs.yml
410 OPNFV main site: opnfvmain_.
412 OPNFV functional test page: opnfvfunctest_.
414 IRC support channel: #opnfv-testperf
416 .. _opnfvmain: http://www.opnfv.org
417 .. _opnfvfunctest: https://wiki.opnfv.org/opnfv_functional_testing
418 .. _`OpenRC`: http://docs.openstack.org/user-guide/common/cli_set_environment_variables_using_openstack_rc.html
419 .. _`Rally installation procedure`: https://rally.readthedocs.org/en/latest/tutorial/step_0_installation.html
420 .. _`config_test.py` : https://git.opnfv.org/cgit/functest/tree/testcases/config_functest.py
421 .. _`config_functest.yaml` : https://git.opnfv.org/cgit/functest/tree/testcases/config_functest.yaml