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 step.
17 High level architecture
18 -----------------------
20 The high level architecture of Functest within OPNFV can be described as
23 CIMC/Lights+out management Admin Private Public Storage
29 | +----------------------------+ | | + |
31 +-----+ Jumphost | | | | |
32 | | +----------+ | | |
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 | | | | | |
50 | | | -- opencontrail | | | | | |
52 | | | Features | | | | | |
53 | | | - vIMS | | | | | |
55 | | +--------------------+ | | | | |
56 | | +------------------------------+ |
57 | | Functest Docker | | | | |
58 | | +---------------------------------------+
60 | +----------------------------+ | | | |
62 | +----------------+ | | | |
64 +----+ +--------------+-+ | | | |
66 | | | +--------------+-+ | | | |
68 | | | | +--------------+-+ | | | |
70 | +-+ | | +--------------+-+ | | | |
71 | | | | | 5 +---------------+ | | |
72 | +-+ | | nodes for | | | | |
73 | | | | deploying +-------------------------+ | |
74 | +-+ | OPNFV | | | | |
75 | | | +-----------------------------------+ |
77 | | +--------------------------------------------+
78 | +----------------+ | | | |
81 SUT = System Under Test
83 All the libraries and dependencies needed by all of the Functest tools are
84 pre-installed into the Docker image. This allows running Functest on any
85 platform on any Operating System.
87 The automated mechanisms inside the Functest Docker container will:
89 * retrieve OpenStack credentials
90 * prepare the environment according to the SUT
91 * perform the appropriate functional tests
92 * push the test results into the OPNFV test result database
94 This Docker image can be integrated into CI or deployed independently.
96 Please note that the Functest Docker container has been designed for OPNFV,
97 however, it would be possible to adapt it to any VIM+controller environment,
98 since most of the test cases are integrated from upstream communities.
100 The test cases are described in the Functest User Guide `[2]`_
105 The OPNFV deployment is out of the scope of this document but it can be found
106 in `[4]`_. The OPNFV platform is considered as the System Under Test (SUT) in
109 Several prerequisites are needed for Functest:
111 #. A Jumphost to run Functest on
112 #. A Docker daemon shall be installed on the Jumphost
113 #. A public/external network created on the SUT
114 #. An admin/management network created on the SUT
115 #. Connectivity from the Jumphost to the SUT public/external network
116 #. Connectivity from the Jumphost to the SUT admin/management network
118 NOTE: **Jumphost** refers to any server which meets the previous requirements.
119 Normally it is the same server from where the OPNFV deployment has been
120 triggered previously.
124 .. _Ubuntu: https://docs.docker.com/installation/ubuntulinux/
125 .. _RHEL: https://docs.docker.com/installation/rhel/
126 .. _CentOS: https://docs.docker.com/engine/installation/linux/centos/
128 *Tip:* If your Jumphost is operating behind a company http proxy and/or
129 Firewall, please consult first the section `Proxy Support`_, towards the end
130 of this document. The section details some tips/tricks which *may* be of help
131 in a proxified environment.
133 Log on to your Jumphost and install the Docker Engine (e.g. for Ubuntu)::
135 curl -sSL https://get.docker.com/ | sh
137 Add your user to docker group to be able to run commands without sudo::
139 sudo usermod -aG docker <your_user>
141 A reconnect is needed. There are 2 ways for this:
142 #. Re-login to your account
145 If your Jumphost is based on Red Hat Enterprise Linux, or CentOS 7 linux,
146 please consult the references below.
148 References - Installing Docker Engine on different Linux Operating Systems:
154 Public/External network on SUT
155 ------------------------------
156 Some of the tests against the VIM (Virtual Infrastructure Manager) need
157 connectivity through an existing public/external network in order to succeed.
158 This is needed, for example, to create floating IPs to access VM instances
159 through the public/external network (i.e. from the Docker container).
161 By default, the four OPNFV installers provide a fresh installation with a
162 public/external network created along with a router. Make sure that the
163 public/external subnet is reachable from the Jumphost.
165 *Hint:* For the given OPNFV Installer in use, the IP sub-net address used for
166 the public/external network is usually a planning item and should thus be known.
167 Consult the OPNFV Configuration guide `[4]`_, and ensure you can reach each
168 node in the SUT, from the Jumphost using the 'ping' command using the
169 respective IP address on the public/external network for each node in the SUT.
170 (The details of how to determine the needed IP addresses for each node in the
171 SUT may vary according to the used installer and are therefore ommitted here.)
173 Connectivity to OPNFV admin/management network
174 ----------------------------------------------
175 Some of the Functest tools need to have access to the OpenStack admin/management
176 network of the controllers `[1]`_.
178 For this reason, an interface shall be configured in the Jumphost in the OpenStack admin/management network range.
180 For example, if the admin/management network is using VLAN 300 and subnet 192.168.1.0/24 and assuming that eth1 is the
181 physical interface with access to that subnet::
183 ip link add name eth1.300 link eth1 type vlan id 300
184 ip link set eth1.300 up
185 ip addr add 192.168.1.66/24 dev eth1.300
187 This is just an example about how to configure an interface with vlan, but it might differ depending on the deployment
188 settings on each installer. Check the corresponding installer instructions for more precise instructions.
191 Installation and configuration
192 ==============================
194 .. include:: ./configguide.rst
198 In CI we use the Docker image and execute the appropriate commands within the
199 container from Jenkins.
201 Docker creation in set-functest-env builder `[3]`_::
203 envs="INSTALLER_TYPE=${INSTALLER_TYPE} -e INSTALLER_IP=${INSTALLER_IP} -e NODE_NAME=${NODE_NAME}"
205 docker pull opnfv/functest:latest_stable
206 cmd="docker run -id -e $envs ${labconfig} ${sshkey} ${res_volume} opnfv/functest:latest_stable /bin/bash"
207 echo "Functest: Running docker run command: ${cmd}"
211 container_id=$(docker ps | grep 'opnfv/functest:latest_stable' | awk '{print $1}' | head -1)
212 echo "Container ID=${container_id}"
213 if [ -z ${container_id} ]; then
214 echo "Cannot find opnfv/functest container ID ${container_id}. Please check if it is existing."
218 echo "Starting the container: docker start ${container_id}"
219 docker start ${container_id}
222 if [ $(docker ps | grep 'opnfv/functest:latest_stable' | wc -l) == 0 ]; then
223 echo "The container opnfv/functest with ID=${container_id} has not been properly started. Exiting..."
226 cmd="${FUNCTEST_REPO_DIR}/docker/prepare_env.sh"
227 echo "Executing command inside the docker: ${cmd}"
228 docker exec ${container_id} ${cmd}
231 Test execution in functest-all builder `[3]`_::
233 echo "Functest: run $FUNCTEST_SUITE_NAME"
234 cmd="${FUNCTEST_REPO_DIR}/docker/run_tests.sh --test $FUNCTEST_SUITE_NAME ${flag}"
235 container_id=$(docker ps -a | grep opnfv/functest | awk '{print $1}' | head -1)
236 docker exec $container_id $cmd
238 Docker clean in functest-cleanup builder `[3]`_::
240 echo "Cleaning up docker containers/images..."
241 # Remove previous running containers if exist
242 if [[ ! -z $(docker ps -a | grep opnfv/functest) ]]; then
243 echo "Removing existing opnfv/functest containers..."
244 docker ps | grep opnfv/functest | awk '{print $1}' | xargs docker stop
245 docker ps -a | grep opnfv/functest | awk '{print $1}' | xargs docker rm
248 # Remove existing images if exist
249 if [[ ! -z $(docker images | grep opnfv/functest) ]]; then
250 echo "Docker images to remove:"
251 docker images | head -1 && docker images | grep opnfv/functest
252 image_tags=($(docker images | grep opnfv/functest | awk '{print $2}'))
253 for tag in "${image_tags[@]}"; do
254 echo "Removing docker image opnfv/functest:$tag..."
255 docker rmi opnfv/functest:$tag
262 .. _`[1]`: https://ask.openstack.org/en/question/68144/keystone-unable-to-use-the-public-endpoint/
263 .. _`[2]`: http://artifacts.opnfv.org/functest/docs/userguide/index.html
264 .. _`[3]`: https://git.opnfv.org/cgit/releng/tree/jjb/functest/functest-ci-jobs.yml
265 .. _`[4]`: http://artifacts.opnfv.org/opnfvdocs/brahmaputra/docs/configguide/index.html
268 OPNFV main site: opnfvmain_.
270 OPNFV functional test page: opnfvfunctest_.
272 IRC support channel: #opnfv-testperf
274 .. _opnfvmain: http://www.opnfv.org
275 .. _opnfvfunctest: https://wiki.opnfv.org/opnfv_functional_testing