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 Private Public Storage
44 | +----------------------------+ | | | |
46 +-----+ Jumphost | | | | |
49 | | +--------------------+ | | | | |
51 | | | Tools | +----------------+ | |
52 | | | - Rally | | | | | |
53 | | | - Robot | | | | | |
54 | | | - TestON | | | | | |
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 +-------------------------+ |
78 | | +---------------------------------+
80 | +----------------------------+ | | | |
82 | +----------------+ | | | |
84 +----+ +--------------+-+ | | | |
86 | | | +--------------+-+ | | | |
88 | | | | +--------------+-+ | | | |
90 | +-+ | | +--------------+-+ | | | |
91 | | | | | 5 +-------------+ | | |
92 | +-+ | | nodes for | | | | |
93 | | | | deploying +---------------------+ | |
94 | +-+ | OPNFV | | | | |
95 | | | +------------------------------+ |
97 | | +--------------------------------------+
98 | +----------------+ | | | |
101 SUT = System Under Test
103 All the libraries and dependencies needed by all of the Functest tools
104 are pre-installed into the Docker image. This allows running Functest
105 on any platform on any Operating System.
107 The automated mechanisms inside the Functest Docker container will:
109 * Retrieve OpenStack credentials
110 * Prepare the environment according to the SUT
111 * Perform the appropriate functional tests
112 * Push the test results into the OPNFV test result database
114 This Docker image can be integrated into CI or deployed independently.
116 Please note that the Functest Docker container has been designed for
117 OPNFV, however, it would be possible to adapt it to any VIM + controller
118 environment, since most of the test cases are integrated from upstream
121 The functional test cases are described in the Functest User Guide `[2]`_
126 The OPNFV deployment is out of the scope of this document but it can be
127 found in http://docs.opnfv.org.
128 The OPNFV platform is considered as the System Under Test (SUT) in this
131 Several prerequisites are needed for Functest:
133 #. A Jumphost to run Functest on
134 #. A Docker daemon shall be installed on the Jumphost
135 #. A public/external network created on the SUT
136 #. An admin/management network created on the SUT
137 #. Connectivity from the Jumphost to the SUT public/external network
138 #. Connectivity from the Jumphost to the SUT admin/management network
140 WARNING: Connectivity from Jumphost is essential and it is of paramount
141 importance to make sure it is working before even considering to install
142 and run Functest. Make also sure you understand how your networking is
145 NOTE: **Jumphost** refers to any server which meets the previous
146 requirements. Normally it is the same server from where the OPNFV
147 deployment has been triggered previously.
149 NOTE: If your Jumphost is operating behind a company http proxy and/or
150 Firewall, please consult first the section `Proxy Support`_, towards
151 the end of this document. The section details some tips/tricks which
152 *may* be of help in a proxified environment.
156 Docker installation and configuration is only needed to be done once
157 through the life cycle of Jumphost.
159 If your Jumphost is based on Ubuntu, RHEL or CentOS linux, please
160 consult the references below for more detailed instructions. The
161 commands below are offered as a short reference.
163 *Tip:* For running docker containers behind the proxy, you need first
164 some extra configuration which is described in section
165 `Docker Installation on CentOS behind http proxy`_. You should follow
166 that section before installing the docker engine.
168 Docker installation needs to be done as root user. You may use other
169 userid's to create and run the actual containers later if so desired.
170 Log on to your Jumphost as root user and install the Docker Engine
171 (e.g. for CentOS family)::
173 curl -sSL https://get.docker.com/ | sh
174 systemctl start docker
176 *Tip:* If you are working through proxy, please set the https_proxy
177 environment variable first before executing the curl command.
179 Add your user to docker group to be able to run commands without sudo::
181 sudo usermod -aG docker <your_user>
183 A reconnect is needed. There are 2 ways for this:
184 #. Re-login to your account
187 References - Installing Docker Engine on different Linux Operating Systems:
192 .. _Ubuntu: https://docs.docker.com/engine/installation/linux/ubuntulinux/
193 .. _RHEL: https://docs.docker.com/engine/installation/linux/rhel/
194 .. _CentOS: https://docs.docker.com/engine/installation/linux/centos/
196 Public/External network on SUT
197 ------------------------------
198 Some of the tests against the VIM (Virtual Infrastructure Manager) need
199 connectivity through an existing public/external network in order to
200 succeed. This is needed, for example, to create floating IPs to access
201 VM instances through the public/external network (i.e. from the Docker
204 By default, the four OPNFV installers provide a fresh installation with
205 a public/external network created along with a router. Make sure that
206 the public/external subnet is reachable from the Jumphost.
208 *Hint:* For the given OPNFV Installer in use, the IP sub-net address
209 used for the public/external network is usually a planning item and
210 should thus be known. Consult the OPNFV Configuration guide `[4]`_, and
211 ensure you can reach each node in the SUT, from the Jumphost using the
212 'ping' command using the respective IP address on the public/external
213 network for each node in the SUT. The details of how to determine the
214 needed IP addresses for each node in the SUT may vary according to the
215 used installer and are therefore ommitted here.
217 Connectivity to Admin/Management network on SUT
218 -----------------------------------------------
219 Some of the Functest tools need to have access to the OpenStack
220 admin/management network of the controllers `[1]`_.
222 For this reason, check the connectivity from the Jumphost to all the
223 controllers in cluster in the OpenStack admin/management network range.
225 Installation and configuration
226 ==============================
228 .. include:: ./configguide.rst
232 In CI we use the Docker image and execute the appropriate commands within the
233 container from Jenkins.
235 Docker creation in set-functest-env builder `[3]`_::
237 envs="-e INSTALLER_TYPE=${INSTALLER_TYPE} -e INSTALLER_IP=${INSTALLER_IP} -e NODE_NAME=${NODE_NAME}"
239 docker pull opnfv/functest:$DOCKER_TAG >/dev/null
240 cmd="sudo docker run -id ${envs} ${volumes} ${custom_params} ${TESTCASE_OPTIONS} opnfv/functest:${DOCKER_TAG} /bin/bash"
241 echo "Functest: Running docker run command: ${cmd}"
244 container_id=$(docker ps | grep "opnfv/functest:${DOCKER_TAG}" | awk '{print $1}' | head -1)
245 echo "Container ID=${container_id}"
246 if [ -z ${container_id} ]; then
247 echo "Cannot find opnfv/functest container ID ${container_id}. Please check if it is existing."
251 echo "Starting the container: docker start ${container_id}"
252 docker start ${container_id}
254 docker ps >${redirect}
255 if [ $(docker ps | grep "opnfv/functest:${DOCKER_TAG}" | wc -l) == 0 ]; then
256 echo "The container opnfv/functest with ID=${container_id} has not been properly started. Exiting..."
260 cmd="python ${FUNCTEST_REPO_DIR}/functest/ci/prepare_env.py start"
261 echo "Executing command inside the docker: ${cmd}"
262 docker exec ${container_id} ${cmd}
265 Test execution in functest-all builder `[3]`_::
267 branch=${GIT_BRANCH##*/}
268 echo "Functest: run $FUNCTEST_SUITE_NAME on branch ${branch}"
269 cmd="functest testcase run $FUNCTEST_SUITE_NAME"
271 container_id=$(docker ps -a | grep opnfv/functest | awk '{print $1}' | head -1)
272 docker exec $container_id $cmd
276 Docker clean in functest-cleanup builder `[3]`_ calling docker rm and docker rmi
281 .. _`[1]`: https://ask.openstack.org/en/question/68144/keystone-unable-to-use-the-public-endpoint/
282 .. _`[2]`: http://artifacts.opnfv.org/functest/docs/userguide/index.html
283 .. _`[3]`: https://git.opnfv.org/cgit/releng/tree/jjb/functest/functest-ci-jobs.yml
284 .. _`[4]`: http://artifacts.opnfv.org/functest/danube/docs/configguide/index.html
287 OPNFV main site: opnfvmain_.
289 OPNFV functional test page: opnfvfunctest_.
291 IRC support channel: #opnfv-functest
293 .. _opnfvmain: http://www.opnfv.org
294 .. _opnfvfunctest: https://wiki.opnfv.org/functest