1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
2 .. http://creativecommons.org/licenses/by/4.0
4 ==================================
5 OPNFV FUNCTEST Configuration Guide
6 ==================================
15 +------------+----------+------------------+----------------------------------+
16 | **Date** | **Ver.** | **Author** | **Comment** |
18 +------------+----------+------------------+----------------------------------+
19 | 2016-08-17 | 1.0.0 | Juha Haapavirta | Colorado release |
20 | | | Column Gaynor | |
21 +------------+----------+------------------+----------------------------------+
22 | 2017-01-19 | 1.0.1 | Morgan Richomme | Adaptations for Danube |
23 | | | | * update testcase list |
24 | | | | * update docker command |
25 +------------+----------+------------------+----------------------------------+
29 This document describes how to install and configure Functest in OPNFV.
30 The Functest CLI is utilized during the Functest environment preparation
31 step. The given example commands should work in both virtual and bare
34 High level architecture
35 -----------------------
37 The high level architecture of Functest within OPNFV can be described as
40 CIMC/Lights+out management Admin Mgmt/API Public Storage Private
44 | +----------------------------+ | | | | |
46 +-----+ Jumphost | | | | | |
47 | | +--------+ | | | |
49 | | +--------------------+ | | | | | |
51 | | | Tools | +----------------+ | | |
52 | | | - Rally | | | | | | |
53 | | | - Robot | | | | | | |
54 | | | - TestON | | | | | | |
55 | | | | |-------------------------+ | |
56 | | | Testcases | | | | | | |
57 | | | - VIM | | | | | | |
58 | | | -- healthcheck | | | | | | |
59 | | | -- vPing_ssh | | | | | | |
60 | | | -- vPing_userdata | | | | | | |
61 | | | -- SNAPS_cases | | | | | | |
62 | | | -- Tempest_smoke | | | | | | |
63 | | | -- Rally_sanity | | | | | | |
64 | | | -- Tempest_full | | | | | | |
65 | | | -- Rally_full | | | | | | |
67 | | | - SDN Controller | | | | | | |
68 | | | -- odl | | | | | | |
69 | | | -- onos | | | | | | |
71 | | | - Features | | | | | | |
73 | | | - VNF | | | | | | |
75 | | +--------------------+ | | | | | |
76 | | Functest Docker + | | | | |
80 | +----------------------------+ | | | | |
82 | +----------------+ | | | | |
84 +----+ +--------------+-+ | | | | |
86 | | | +--------------+-+ | | | | |
88 | | | | +--------------+-+ | | | | |
89 | | | | | 4 | | | | | |
90 | +-+ | | +--------------+-+ | | | | |
91 | | | | | 5 +-------------+ | | | |
92 | +-+ | | nodes for | | | | | |
93 | | | | deploying +---------------------+ | | |
94 | +-+ | OPNFV | | | | | |
95 | | | +------------------------------+ | |
97 | | +--------------------------------------+ |
99 | | +----------------------------------------------+
100 | +----------------+ | | | | |
103 SUT = System Under Test
105 All the libraries and dependencies needed by all of the Functest tools
106 are pre-installed into the Docker image. This allows running Functest
107 on any platform on any Operating System.
109 The automated mechanisms inside the Functest Docker container will:
111 * Retrieve OpenStack credentials
112 * Prepare the environment according to the SUT
113 * Perform the appropriate functional tests
114 * Push the test results into the OPNFV test result database
116 This Docker image can be integrated into CI or deployed independently.
118 Please note that the Functest Docker container has been designed for
119 OPNFV, however, it would be possible to adapt it to any VIM + controller
120 environment, since most of the test cases are integrated from upstream
123 The functional test cases are described in the Functest User Guide `[2]`_
128 The OPNFV deployment is out of the scope of this document but it can be
129 found in http://docs.opnfv.org.
130 The OPNFV platform is considered as the System Under Test (SUT) in this
133 Several prerequisites are needed for Functest:
135 #. A Jumphost to run Functest on
136 #. A Docker daemon shall be installed on the Jumphost
137 #. A public/external network created on the SUT
138 #. An admin/management network created on the SUT
139 #. Connectivity from the Jumphost to the SUT public/external network
140 #. Connectivity from the Jumphost to the SUT admin/management network
142 WARNING: Connectivity from Jumphost is essential and it is of paramount
143 importance to make sure it is working before even considering to install
144 and run Functest. Make also sure you understand how your networking is
147 NOTE: **Jumphost** refers to any server which meets the previous
148 requirements. Normally it is the same server from where the OPNFV
149 deployment has been triggered previously.
151 NOTE: If your Jumphost is operating behind a company http proxy and/or
152 Firewall, please consult first the section `Proxy Support`_, towards
153 the end of this document. The section details some tips/tricks which
154 *may* be of help in a proxified environment.
158 Docker installation and configuration is only needed to be done once
159 through the life cycle of Jumphost.
161 If your Jumphost is based on Ubuntu, RHEL or CentOS linux, please
162 consult the references below for more detailed instructions. The
163 commands below are offered as a short reference.
165 *Tip:* For running docker containers behind the proxy, you need first
166 some extra configuration which is described in section
167 `Docker Installation on CentOS behind http proxy`_. You should follow
168 that section before installing the docker engine.
170 Docker installation needs to be done as root user. You may use other
171 userid's to create and run the actual containers later if so desired.
172 Log on to your Jumphost as root user and install the Docker Engine
173 (e.g. for CentOS family)::
175 curl -sSL https://get.docker.com/ | sh
176 systemctl start docker
178 *Tip:* If you are working through proxy, please set the https_proxy
179 environment variable first before executing the curl command.
181 Add your user to docker group to be able to run commands without sudo::
183 sudo usermod -aG docker <your_user>
185 A reconnect is needed. There are 2 ways for this:
186 #. Re-login to your account
189 References - Installing Docker Engine on different Linux Operating Systems:
194 .. _Ubuntu: https://docs.docker.com/engine/installation/linux/ubuntulinux/
195 .. _RHEL: https://docs.docker.com/engine/installation/linux/rhel/
196 .. _CentOS: https://docs.docker.com/engine/installation/linux/centos/
198 Public/External network on SUT
199 ------------------------------
200 Some of the tests against the VIM (Virtual Infrastructure Manager) need
201 connectivity through an existing public/external network in order to
202 succeed. This is needed, for example, to create floating IPs to access
203 VM instances through the public/external network (i.e. from the Docker
206 By default, the four OPNFV installers provide a fresh installation with
207 a public/external network created along with a router. Make sure that
208 the public/external subnet is reachable from the Jumphost.
210 *Hint:* For the given OPNFV Installer in use, the IP sub-net address
211 used for the public/external network is usually a planning item and
212 should thus be known. Consult the OPNFV Configuration guide `[4]`_, and
213 ensure you can reach each node in the SUT, from the Jumphost using the
214 'ping' command using the respective IP address on the public/external
215 network for each node in the SUT. The details of how to determine the
216 needed IP addresses for each node in the SUT may vary according to the
217 used installer and are therefore ommitted here.
219 Connectivity to Admin/Management network on SUT
220 -----------------------------------------------
221 Some of the Functest tools need to have access to the OpenStack
222 admin/management network of the controllers `[1]`_.
224 For this reason, check the connectivity from the Jumphost to all the
225 controllers in cluster in the OpenStack admin/management network range.
227 Installation and configuration
228 ==============================
230 .. include:: ./configguide.rst
234 In CI we use the Docker image and execute the appropriate commands within the
235 container from Jenkins.
237 Docker creation in set-functest-env builder `[3]`_::
239 envs="-e INSTALLER_TYPE=${INSTALLER_TYPE} -e INSTALLER_IP=${INSTALLER_IP} -e NODE_NAME=${NODE_NAME}"
241 docker pull opnfv/functest:$DOCKER_TAG >/dev/null
242 cmd="sudo docker run -id ${envs} ${volumes} ${custom_params} ${TESTCASE_OPTIONS} opnfv/functest:${DOCKER_TAG} /bin/bash"
243 echo "Functest: Running docker run command: ${cmd}"
246 container_id=$(docker ps | grep "opnfv/functest:${DOCKER_TAG}" | awk '{print $1}' | head -1)
247 echo "Container ID=${container_id}"
248 if [ -z ${container_id} ]; then
249 echo "Cannot find opnfv/functest container ID ${container_id}. Please check if it is existing."
253 echo "Starting the container: docker start ${container_id}"
254 docker start ${container_id}
256 docker ps >${redirect}
257 if [ $(docker ps | grep "opnfv/functest:${DOCKER_TAG}" | wc -l) == 0 ]; then
258 echo "The container opnfv/functest with ID=${container_id} has not been properly started. Exiting..."
262 cmd="python ${FUNCTEST_REPO_DIR}/functest/ci/prepare_env.py start"
263 echo "Executing command inside the docker: ${cmd}"
264 docker exec ${container_id} ${cmd}
267 Test execution in functest-all builder `[3]`_::
269 branch=${GIT_BRANCH##*/}
270 echo "Functest: run $FUNCTEST_SUITE_NAME on branch ${branch}"
271 cmd="functest testcase run $FUNCTEST_SUITE_NAME"
273 container_id=$(docker ps -a | grep opnfv/functest | awk '{print $1}' | head -1)
274 docker exec $container_id $cmd
278 Docker clean in functest-cleanup builder `[3]`_ calling docker rm and docker rmi
283 .. _`[1]`: https://ask.openstack.org/en/question/68144/keystone-unable-to-use-the-public-endpoint/
284 .. _`[2]`: http://artifacts.opnfv.org/functest/docs/userguide/index.html
285 .. _`[3]`: https://git.opnfv.org/cgit/releng/tree/jjb/functest/functest-ci-jobs.yml
286 .. _`[4]`: http://artifacts.opnfv.org/functest/danube/docs/configguide/index.html
289 OPNFV main site: opnfvmain_.
291 OPNFV functional test page: opnfvfunctest_.
293 IRC support channel: #opnfv-functest
295 .. _opnfvmain: http://www.opnfv.org
296 .. _opnfvfunctest: https://wiki.opnfv.org/functest