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 ==================================
14 This document describes how to install and configure Functest in OPNFV.
15 The Functest CLI is utilized during the Functest environment preparation
16 step. The given example commands should work in both virtual and bare
19 High level architecture
20 -----------------------
22 The high level architecture of Functest within OPNFV can be described as
25 CIMC/Lights+out management Admin Private Public Storage
29 | +----------------------------+ | | | |
31 +-----+ Jumphost | | | | |
34 | | +--------------------+ | | | | |
36 | | | Tools | +----------------+ | |
37 | | | - Rally | | | | | |
38 | | | - Robot | | | | | |
39 | | | - TestON | | | | | |
41 | | | Testcases | | | | | |
42 | | | - VIM | | | | | |
43 | | | -- healthcheck | | | | | |
44 | | | -- vPing_ssh | | | | | |
45 | | | -- vPing_userdata | | | | | |
46 | | | -- Tempest_smoke | | | | | |
47 | | | -- Rally_sanity | | | | | |
48 | | | -- Tempest_full | | | | | |
49 | | | -- Rally_full | | | | | |
51 | | | - SDN Controller | | | | | |
52 | | | -- odl | | | | | |
53 | | | -- onos | | | | | |
55 | | | - VNF | | | | | |
56 | | | -- vIMS | | | | | |
58 | | +--------------------+ | | | | |
59 | | +-------------------------+ |
60 | | Functest Docker | | | | |
61 | | +---------------------------------+
63 | +----------------------------+ | | | |
65 | +----------------+ | | | |
67 +----+ +--------------+-+ | | | |
69 | | | +--------------+-+ | | | |
71 | | | | +--------------+-+ | | | |
73 | +-+ | | +--------------+-+ | | | |
74 | | | | | 5 +-------------+ | | |
75 | +-+ | | nodes for | | | | |
76 | | | | deploying +---------------------+ | |
77 | +-+ | OPNFV | | | | |
78 | | | +------------------------------+ |
80 | | +--------------------------------------+
81 | +----------------+ | | | |
84 SUT = System Under Test
86 All the libraries and dependencies needed by all of the Functest tools
87 are pre-installed into the Docker image. This allows running Functest
88 on any platform on any Operating System.
90 The automated mechanisms inside the Functest Docker container will:
92 * Retrieve OpenStack credentials
93 * Prepare the environment according to the SUT
94 * Perform the appropriate functional tests
95 * Push the test results into the OPNFV test result database
97 This Docker image can be integrated into CI or deployed independently.
99 Please note that the Functest Docker container has been designed for
100 OPNFV, however, it would be possible to adapt it to any VIM + controller
101 environment, since most of the test cases are integrated from upstream
104 The functional test cases are described in the Functest User Guide `[2]`_
109 The OPNFV deployment is out of the scope of this document but it can be
110 found in http://artifacts.opnfv.org/opnfvdocs/colorado/docs/configguide/index.html.
111 The OPNFV platform is considered as the System Under Test (SUT) in this
114 Several prerequisites are needed for Functest:
116 #. A Jumphost to run Functest on
117 #. A Docker daemon shall be installed on the Jumphost
118 #. A public/external network created on the SUT
119 #. An admin/management network created on the SUT
120 #. Connectivity from the Jumphost to the SUT public/external network
121 #. Connectivity from the Jumphost to the SUT admin/management network
123 WARNING: Connectivity from Jumphost is essential and it is of paramount
124 importance to make sure it is working before even considering to install
125 and run Functest. Make also sure you understand how your networking is
128 NOTE: **Jumphost** refers to any server which meets the previous
129 requirements. Normally it is the same server from where the OPNFV
130 deployment has been triggered previously.
132 NOTE: If your Jumphost is operating behind a company http proxy and/or
133 Firewall, please consult first the section `Proxy Support`_, towards
134 the end of this document. The section details some tips/tricks which
135 *may* be of help in a proxified environment.
139 Docker installation and configuration is only needed to be done once
140 through the life cycle of Jumphost.
142 If your Jumphost is based on Ubuntu, RHEL or CentOS linux, please
143 consult the references below for more detailed instructions. The
144 commands below are offered as a short reference.
146 *Tip:* For running docker containers behind the proxy, you need first
147 some extra configuration which is described in section
148 `Docker Installation on CentOS behind http proxy`_. You should follow
149 that section before installing the docker engine.
151 Docker installation needs to be done as root user. You may use other
152 userid's to create and run the actual containers later if so desired.
153 Log on to your Jumphost as root user and install the Docker Engine
154 (e.g. for CentOS family)::
156 curl -sSL https://get.docker.com/ | sh
157 systemctl start docker
159 *Tip:* If you are working through proxy, please set the https_proxy
160 environment variable first before executing the curl command.
162 Add your user to docker group to be able to run commands without sudo::
164 sudo usermod -aG docker <your_user>
166 A reconnect is needed. There are 2 ways for this:
167 #. Re-login to your account
170 References - Installing Docker Engine on different Linux Operating Systems:
175 .. _Ubuntu: https://docs.docker.com/engine/installation/linux/ubuntulinux/
176 .. _RHEL: https://docs.docker.com/engine/installation/linux/rhel/
177 .. _CentOS: https://docs.docker.com/engine/installation/linux/centos/
179 Public/External network on SUT
180 ------------------------------
181 Some of the tests against the VIM (Virtual Infrastructure Manager) need
182 connectivity through an existing public/external network in order to
183 succeed. This is needed, for example, to create floating IPs to access
184 VM instances through the public/external network (i.e. from the Docker
187 By default, the four OPNFV installers provide a fresh installation with
188 a public/external network created along with a router. Make sure that
189 the public/external subnet is reachable from the Jumphost.
191 *Hint:* For the given OPNFV Installer in use, the IP sub-net address
192 used for the public/external network is usually a planning item and
193 should thus be known. Consult the OPNFV Configuration guide `[4]`_, and
194 ensure you can reach each node in the SUT, from the Jumphost using the
195 'ping' command using the respective IP address on the public/external
196 network for each node in the SUT. The details of how to determine the
197 needed IP addresses for each node in the SUT may vary according to the
198 used installer and are therefore ommitted here.
200 Connectivity to Admin/Management network on SUT
201 -----------------------------------------------
202 Some of the Functest tools need to have access to the OpenStack
203 admin/management network of the controllers `[1]`_.
205 For this reason, check the connectivity from the Jumphost to all the
206 controllers in cluster in the OpenStack admin/management network range.
208 Installation and configuration
209 ==============================
211 .. include:: ./configguide.rst
215 In CI we use the Docker image and execute the appropriate commands within the
216 container from Jenkins.
218 Docker creation in set-functest-env builder `[3]`_::
220 envs="INSTALLER_TYPE=${INSTALLER_TYPE} -e INSTALLER_IP=${INSTALLER_IP} -e NODE_NAME=${NODE_NAME}"
222 docker pull opnfv/functest:latest_stable
223 cmd="docker run -id -e $envs ${labconfig} ${sshkey} ${res_volume} opnfv/functest:latest_stable /bin/bash"
224 echo "Functest: Running docker run command: ${cmd}"
228 container_id=$(docker ps | grep 'opnfv/functest:latest_stable' | awk '{print $1}' | head -1)
229 echo "Container ID=${container_id}"
230 if [ -z ${container_id} ]; then
231 echo "Cannot find opnfv/functest container ID ${container_id}. Please check if it is existing."
235 echo "Starting the container: docker start ${container_id}"
236 docker start ${container_id}
239 if [ $(docker ps | grep 'opnfv/functest:latest_stable' | wc -l) == 0 ]; then
240 echo "The container opnfv/functest with ID=${container_id} has not been properly started. Exiting..."
243 cmd="${FUNCTEST_REPO_DIR}/docker/prepare_env.sh"
244 echo "Executing command inside the docker: ${cmd}"
245 docker exec ${container_id} ${cmd}
248 Test execution in functest-all builder `[3]`_::
250 echo "Functest: run $FUNCTEST_SUITE_NAME"
251 cmd="${FUNCTEST_REPO_DIR}/docker/run_tests.sh --test $FUNCTEST_SUITE_NAME ${flag}"
252 container_id=$(docker ps -a | grep opnfv/functest | awk '{print $1}' | head -1)
253 docker exec $container_id $cmd
255 Docker clean in functest-cleanup builder `[3]`_::
257 echo "Cleaning up docker containers/images..."
258 # Remove previous running containers if exist
259 if [[ ! -z $(docker ps -a | grep opnfv/functest) ]]; then
260 echo "Removing existing opnfv/functest containers..."
261 docker ps | grep opnfv/functest | awk '{print $1}' | xargs docker stop
262 docker ps -a | grep opnfv/functest | awk '{print $1}' | xargs docker rm
265 # Remove existing images if exist
266 if [[ ! -z $(docker images | grep opnfv/functest) ]]; then
267 echo "Docker images to remove:"
268 docker images | head -1 && docker images | grep opnfv/functest
269 image_tags=($(docker images | grep opnfv/functest | awk '{print $2}'))
270 for tag in "${image_tags[@]}"; do
271 echo "Removing docker image opnfv/functest:$tag..."
272 docker rmi opnfv/functest:$tag
279 .. _`[1]`: https://ask.openstack.org/en/question/68144/keystone-unable-to-use-the-public-endpoint/
280 .. _`[2]`: http://artifacts.opnfv.org/functest/docs/userguide/index.html
281 .. _`[3]`: https://git.opnfv.org/cgit/releng/tree/jjb/functest/functest-ci-jobs.yml
282 .. _`[4]`: http://artifacts.opnfv.org/opnfvdocs/colorado/docs/configguide/index.html
285 OPNFV main site: opnfvmain_.
287 OPNFV functional test page: opnfvfunctest_.
289 IRC support channel: #opnfv-functest
291 .. _opnfvmain: http://www.opnfv.org
292 .. _opnfvfunctest: https://wiki.opnfv.org/opnfv_functional_testing