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 used during the Functest environment preparation
31 phase. 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 | | | - RefStack | | | | | | |
56 | | | | |-------------------------+ | |
57 | | | Testcases | | | | | | |
58 | | | - VIM | | | | | | |
60 | | | - SDN Controller | | | | | | |
62 | | | - Features | | | | | | |
64 | | | - VNF | | | | | | |
66 | | +--------------------+ | | | | | |
67 | | Functest Docker + | | | | |
71 | +----------------------------+ | | | | |
73 | +----------------+ | | | | |
75 +----+ +--------------+-+ | | | | |
77 | | | +--------------+-+ | | | | |
79 | | | | +--------------+-+ | | | | |
80 | | | | | 4 | | | | | |
81 | +-+ | | +--------------+-+ | | | | |
82 | | | | | 5 +-------------+ | | | |
83 | +-+ | | nodes for | | | | | |
84 | | | | deploying +---------------------+ | | |
85 | +-+ | OPNFV | | | | | |
86 | | | +------------------------------+ | |
88 | | +--------------------------------------+ |
90 | | +----------------------------------------------+
91 | +----------------+ | | | | |
94 SUT = System Under Test
96 All the libraries and dependencies needed by all of the Functest tools
97 are pre-installed into the Docker image. This allows running Functest
98 on any platform on any Operating System.
100 The automated mechanisms inside the Functest Docker container will:
102 * Retrieve OpenStack credentials
103 * Prepare the environment according to the System Under Test (SUT)
104 * Perform the appropriate functional tests
105 * Push the test results into the OPNFV test result database
107 This Docker image can be integrated into CI or deployed independently.
109 Please note that the Functest Docker container has been designed for OPNFV,
110 however, it would be possible to adapt it to any OpenStack based VIM +
111 controller environment, since most of the test cases are integrated from
112 upstream communities.
114 The functional test cases are described in the Functest User Guide `[2]`_
119 The OPNFV deployment is out of the scope of this document but it can be
120 found in http://docs.opnfv.org.
121 The OPNFV platform is considered as the SUT in this document.
123 Several prerequisites are needed for Functest:
125 #. A Jumphost to run Functest on
126 #. A Docker daemon shall be installed on the Jumphost
127 #. A public/external network created on the SUT
128 #. An admin/management network created on the SUT
129 #. Connectivity from the Jumphost to the SUT public/external network
130 #. Connectivity from the Jumphost to the SUT admin/management network
132 WARNING: Connectivity from Jumphost is essential and it is of paramount
133 importance to make sure it is working before even considering to install
134 and run Functest. Make also sure you understand how your networking is
137 NOTE: **Jumphost** refers to any server which meets the previous
138 requirements. Normally it is the same server from where the OPNFV
139 deployment has been triggered previously.
141 NOTE: If your Jumphost is operating behind a company http proxy and/or
142 firewall, please consult first the section `Proxy Support`_, towards
143 the end of this document. The section details some tips/tricks which
144 *may* be of help in a proxified environment.
148 Docker installation and configuration is only needed to be done once
149 through the life cycle of Jumphost.
151 If your Jumphost is based on Ubuntu, SUSE, RHEL or CentOS linux, please
152 consult the references below for more detailed instructions. The
153 commands below are offered as a short reference.
155 *Tip:* For running docker containers behind the proxy, you need first
156 some extra configuration which is described in section
157 `Docker Installation on CentOS behind http proxy`_. You should follow
158 that section before installing the docker engine.
160 Docker installation needs to be done as root user. You may use other
161 userid's to create and run the actual containers later if so desired.
162 Log on to your Jumphost as root user and install the Docker Engine
163 (e.g. for CentOS family)::
165 curl -sSL https://get.docker.com/ | sh
166 systemctl start docker
168 *Tip:* If you are working through proxy, please set the https_proxy
169 environment variable first before executing the curl command.
171 Add your user to docker group to be able to run commands without sudo::
173 sudo usermod -aG docker <your_user>
175 A reconnection is needed. There are 2 ways for this:
176 #. Re-login to your account
179 References - Installing Docker Engine on different Linux Operating Systems:
185 .. _Ubuntu: https://docs.docker.com/engine/installation/linux/ubuntulinux/
186 .. _RHEL: https://docs.docker.com/engine/installation/linux/rhel/
187 .. _CentOS: https://docs.docker.com/engine/installation/linux/centos/
188 .. _SUSE: https://docs.docker.com/engine/installation/linux/suse/
190 Public/External network on SUT
191 ------------------------------
192 Some of the tests against the VIM (Virtual Infrastructure Manager) need
193 connectivity through an existing public/external network in order to
194 succeed. This is needed, for example, to create floating IPs to access
195 VM instances through the public/external network (i.e. from the Docker
198 By default, the four OPNFV installers provide a fresh installation with
199 a public/external network created along with a router. Make sure that
200 the public/external subnet is reachable from the Jumphost.
202 *Hint:* For the given OPNFV Installer in use, the IP sub-net address
203 used for the public/external network is usually a planning item and
204 should thus be known. Consult the OPNFV Configuration guide `[4]`_, and
205 ensure you can reach each node in the SUT, from the Jumphost using the
206 'ping' command using the respective IP address on the public/external
207 network for each node in the SUT. The details of how to determine the
208 needed IP addresses for each node in the SUT may vary according to the
209 used installer and are therefore ommitted here.
211 Connectivity to Admin/Management network on SUT
212 -----------------------------------------------
213 Some of the Functest tools need to have access to the OpenStack
214 admin/management network of the controllers `[1]`_.
216 For this reason, check the connectivity from the Jumphost to all the
217 controllers in cluster in the OpenStack admin/management network range.
219 Installation and configuration
220 ==============================
222 .. include:: ./configguide.rst
226 In CI we use the Docker image and execute the appropriate commands within the
227 container from Jenkins.
229 Docker creation in set-functest-env builder `[3]`_::
231 envs="-e INSTALLER_TYPE=${INSTALLER_TYPE} -e INSTALLER_IP=${INSTALLER_IP} -e NODE_NAME=${NODE_NAME}"
233 docker pull opnfv/functest:$DOCKER_TAG >/dev/null
234 cmd="sudo docker run -id ${envs} ${volumes} ${custom_params} ${TESTCASE_OPTIONS} opnfv/functest:${DOCKER_TAG} /bin/bash"
235 echo "Functest: Running docker run command: ${cmd}"
238 container_id=$(docker ps | grep "opnfv/functest:${DOCKER_TAG}" | awk '{print $1}' | head -1)
239 echo "Container ID=${container_id}"
240 if [ -z ${container_id} ]; then
241 echo "Cannot find opnfv/functest container ID ${container_id}. Please check if it is existing."
245 echo "Starting the container: docker start ${container_id}"
246 docker start ${container_id}
248 docker ps >${redirect}
249 if [ $(docker ps | grep "opnfv/functest:${DOCKER_TAG}" | wc -l) == 0 ]; then
250 echo "The container opnfv/functest with ID=${container_id} has not been properly started. Exiting..."
254 cmd="python ${FUNCTEST_REPO_DIR}/functest/ci/prepare_env.py start"
255 echo "Executing command inside the docker: ${cmd}"
256 docker exec ${container_id} ${cmd}
259 Test execution in functest-all builder `[3]`_::
261 branch=${GIT_BRANCH##*/}
262 echo "Functest: run $FUNCTEST_SUITE_NAME on branch ${branch}"
263 cmd="functest testcase run $FUNCTEST_SUITE_NAME"
265 container_id=$(docker ps -a | grep opnfv/functest | awk '{print $1}' | head -1)
266 docker exec $container_id $cmd
270 Docker clean in functest-cleanup builder `[3]`_ calling docker rm and docker rmi
275 .. _`[1]`: https://ask.openstack.org/en/question/68144/keystone-unable-to-use-the-public-endpoint/
276 .. _`[2]`: http://artifacts.opnfv.org/functest/docs/userguide/index.html
277 .. _`[3]`: https://git.opnfv.org/cgit/releng/tree/jjb/functest/functest-ci-jobs.yml
278 .. _`[4]`: http://artifacts.opnfv.org/functest/danube/docs/configguide/index.html
285 IRC support channel: #opnfv-functest
287 .. _`OPNFV main site`: http://www.opnfv.org
288 .. _`Functest page`: https://wiki.opnfv.org/functest