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 | | | -- vPing | | | | | |
44 | | | -- vPing_userdata | | | | | |
45 | | | -- Tempest | | | | | |
46 | | | -- Rally | | | | | |
47 | | | - Controller | | | | | |
48 | | | -- odl | | | | | |
49 | | | -- onos | | | | | |
51 | | | Features | | | | | |
52 | | | - vIMS | | | | | |
54 | | +--------------------+ | | | | |
55 | | +-------------------------+ |
56 | | Functest Docker | | | | |
57 | | +---------------------------------+
59 | +----------------------------+ | | | |
61 | +----------------+ | | | |
63 +----+ +--------------+-+ | | | |
65 | | | +--------------+-+ | | | |
67 | | | | +--------------+-+ | | | |
69 | +-+ | | +--------------+-+ | | | |
70 | | | | | 5 +-------------+ | | |
71 | +-+ | | nodes for | | | | |
72 | | | | deploying +---------------------+ | |
73 | +-+ | OPNFV | | | | |
74 | | | +------------------------------+ |
76 | | +--------------------------------------+
77 | +----------------+ | | | |
80 SUT = System Under Test
82 All the libraries and dependencies needed by all of the Functest tools
83 are pre-installed into the Docker image. This allows running Functest
84 on any platform on any Operating System.
86 The automated mechanisms inside the Functest Docker container will:
88 * retrieve OpenStack credentials
89 * prepare the environment according to the SUT
90 * perform the appropriate functional tests
91 * push the test results into the OPNFV test result database
93 This Docker image can be integrated into CI or deployed independently.
95 Please note that the Functest Docker container has been designed for
96 OPNFV, however, it would be possible to adapt it to any VIM + controller
97 environment, since most of the test cases are integrated from upstream
100 The functional test cases are described in the Functest User Guide `[2]`_
104 The OPNFV deployment is out of the scope of this document but it can be
105 found in `[4]`_. The OPNFV platform is considered as the System Under
106 Test (SUT) in this document.
108 Several prerequisites are needed for Functest:
110 #. A Jumphost to run Functest on
111 #. A Docker daemon shall be installed on the Jumphost
112 #. A public/external network created on the SUT
113 #. An admin/management network created on the SUT
114 #. Connectivity from the Jumphost to the SUT public/external network
115 #. Connectivity from the Jumphost to the SUT admin/management network
117 WARNING: Connectivity from Jumphost is essential and it is of paramount
118 importance to make sure it is working before even considering to install
119 and run Functest. Make also sure you understand how your networking is
122 NOTE: **Jumphost** refers to any server which meets the previous
123 requirements. Normally it is the same server from where the OPNFV
124 deployment has been triggered previously.
126 NOTE: If your Jumphost is operating behind a company http proxy and/or
127 Firewall, please consult first the section `Proxy Support`_, towards
128 the end of this document. The section details some tips/tricks which
129 *may* be of help in a proxified environment.
133 Docker installation and configuration is only needed to be done once
134 through the life cycle of Jumphost.
136 If your Jumphost is based on Ubuntu, RHEL or CentOS linux, please
137 consult the references below for more detailed instructions. The
138 commands below are offered as a short reference.
140 *Tip:* For running docker containers behind the proxy, you need first
141 some extra configuration which is described in section
142 `Docker Installation on CentOS behind http proxy`_. You should follow
143 that section before installing the docker engine.
145 Docker installation needs to be done as root user. You may use other
146 userid's to create and run the actual containers later if so desired.
147 Log on to your Jumphost as root user and install the Docker Engine
148 (e.g. for CentOS family)::
150 curl -sSL https://get.docker.com/ | sh
151 systemctl start docker
153 *Tip:* If you are working through proxy, please set the https_proxy
154 environment variable first before executing the curl command.
156 Add your user to docker group to be able to run commands without sudo::
158 sudo usermod -aG docker <your_user>
160 A reconnect is needed. There are 2 ways for this:
161 #. Re-login to your account
164 References - Installing Docker Engine on different Linux Operating Systems:
169 .. _Ubuntu: https://docs.docker.com/engine/installation/linux/ubuntulinux/
170 .. _RHEL: https://docs.docker.com/engine/installation/linux/rhel/
171 .. _CentOS: https://docs.docker.com/engine/installation/linux/centos/
173 Public/External network on SUT
174 ------------------------------
175 Some of the tests against the VIM (Virtual Infrastructure Manager) need
176 connectivity through an existing public/external network in order to
177 succeed. This is needed, for example, to create floating IPs to access
178 VM instances through the public/external network (i.e. from the Docker
181 By default, the four OPNFV installers provide a fresh installation with
182 a public/external network created along with a router. Make sure that
183 the public/external subnet is reachable from the Jumphost.
185 *Hint:* For the given OPNFV Installer in use, the IP sub-net address
186 used for the public/external network is usually a planning item and
187 should thus be known. Consult the OPNFV Configuration guide `[4]`_, and
188 ensure you can reach each node in the SUT, from the Jumphost using the
189 'ping' command using the respective IP address on the public/external
190 network for each node in the SUT. The details of how to determine the
191 needed IP addresses for each node in the SUT may vary according to the
192 used installer and are therefore ommitted here.
194 Connectivity to Admin/Management network on SUT
195 -----------------------------------------------
196 Some of the Functest tools need to have access to the OpenStack
197 admin/management network of the controllers `[1]`_.
199 For this reason, check the connectivity from the Jumphost to all the
200 controllers in cluster in the OpenStack admin/management network range.
202 Installation and configuration
203 ==============================
205 .. include:: ./configguide.rst
209 In CI we use the Docker image and execute the appropriate commands within the
210 container from Jenkins.
212 Docker creation in set-functest-env builder `[3]`_::
214 envs="INSTALLER_TYPE=${INSTALLER_TYPE} -e INSTALLER_IP=${INSTALLER_IP} -e NODE_NAME=${NODE_NAME}"
216 docker pull opnfv/functest:latest_stable
217 cmd="docker run -id -e $envs ${labconfig} ${sshkey} ${res_volume} opnfv/functest:latest_stable /bin/bash"
218 echo "Functest: Running docker run command: ${cmd}"
222 container_id=$(docker ps | grep 'opnfv/functest:latest_stable' | awk '{print $1}' | head -1)
223 echo "Container ID=${container_id}"
224 if [ -z ${container_id} ]; then
225 echo "Cannot find opnfv/functest container ID ${container_id}. Please check if it is existing."
229 echo "Starting the container: docker start ${container_id}"
230 docker start ${container_id}
233 if [ $(docker ps | grep 'opnfv/functest:latest_stable' | wc -l) == 0 ]; then
234 echo "The container opnfv/functest with ID=${container_id} has not been properly started. Exiting..."
237 cmd="${FUNCTEST_REPO_DIR}/docker/prepare_env.sh"
238 echo "Executing command inside the docker: ${cmd}"
239 docker exec ${container_id} ${cmd}
242 Test execution in functest-all builder `[3]`_::
244 echo "Functest: run $FUNCTEST_SUITE_NAME"
245 cmd="${FUNCTEST_REPO_DIR}/docker/run_tests.sh --test $FUNCTEST_SUITE_NAME ${flag}"
246 container_id=$(docker ps -a | grep opnfv/functest | awk '{print $1}' | head -1)
247 docker exec $container_id $cmd
249 Docker clean in functest-cleanup builder `[3]`_::
251 echo "Cleaning up docker containers/images..."
252 # Remove previous running containers if exist
253 if [[ ! -z $(docker ps -a | grep opnfv/functest) ]]; then
254 echo "Removing existing opnfv/functest containers..."
255 docker ps | grep opnfv/functest | awk '{print $1}' | xargs docker stop
256 docker ps -a | grep opnfv/functest | awk '{print $1}' | xargs docker rm
259 # Remove existing images if exist
260 if [[ ! -z $(docker images | grep opnfv/functest) ]]; then
261 echo "Docker images to remove:"
262 docker images | head -1 && docker images | grep opnfv/functest
263 image_tags=($(docker images | grep opnfv/functest | awk '{print $2}'))
264 for tag in "${image_tags[@]}"; do
265 echo "Removing docker image opnfv/functest:$tag..."
266 docker rmi opnfv/functest:$tag
273 .. _`[1]`: https://ask.openstack.org/en/question/68144/keystone-unable-to-use-the-public-endpoint/
274 .. _`[2]`: http://artifacts.opnfv.org/functest/docs/userguide/index.html
275 .. _`[3]`: https://git.opnfv.org/cgit/releng/tree/jjb/functest/functest-ci-jobs.yml
276 .. _`[4]`: http://artifacts.opnfv.org/opnfvdocs/brahmaputra/docs/configguide/index.html
279 OPNFV main site: opnfvmain_.
281 OPNFV functional test page: opnfvfunctest_.
283 IRC support channel: #opnfv-functest
285 .. _opnfvmain: http://www.opnfv.org
286 .. _opnfvfunctest: https://wiki.opnfv.org/opnfv_functional_testing