1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
2 .. http://creativecommons.org/licenses/by/4.0
5 Preparing the Docker container
6 ------------------------------
8 Pull the Functest Docker image from the Docker hub::
10 docker pull opnfv/functest:brahmaputra.1.0
13 Check that the image is available::
17 Run the docker container giving the environment variables:
19 * **INSTALLER_TYPE** : possible values are **apex**, **compass**, **fuel** or **joid**.
20 * **INSTALLER_IP** : IP of the installer node/VM.
22 Functest may need to know the IP of the installer to retrieve automatically the
23 credentials from the installer node/VM or even from the actual controllers.
25 The minimum command to create the Functest Docker container can be described as
28 docker run -it -e "INSTALLER_IP=10.20.0.2" -e "INSTALLER_TYPE=fuel" opnfv/functest:brahmaputra.1.0 /bin/bash
30 Optionally, it is possible to precise the container name through the option
33 docker run --name "CONTAINER_NAME" -it -e "INSTALLER_IP=10.20.0.2" -e "INSTALLER_TYPE=fuel" opnfv/functest:brahmaputra.1.0 /bin/bash
35 It is also possible to to indicate the path of the OpenStack credentials using **-v**::
37 docker run -it -e "INSTALLER_IP=10.20.0.2" -e "INSTALLER_TYPE=fuel" -v <path_to_your_local_creds_file>:/home/opnfv/functest/conf/openstack.creds opnfv/functest:brahmaputra.1.0 /bin/bash
39 The local file will be mounted in the container under
40 */home/opnfv/functest/conf/openstack.creds*
42 If the intention is to run Functest against any of the supported OPNFV scenarios,
43 it is recommended to include also the environment variable **DEPLOY_SCENARIO**,
46 docker run -it -e "INSTALLER_IP=10.20.0.2" -e "INSTALLER_TYPE=fuel" -e "DEPLOY_SCENARIO=os-odl_l2-nofeature-ha" opnfv/functest:brahmaputra.1.0 /bin/bash
48 Inside the container, the following directory structure should be in place::
68 Basically the container includes:
70 * Functest directory to store the configuration (the OpenStack creds are stored
71 in /home/opngb/functest/conf/openstack.creds), the data (cirros image needed for
72 some tests), results (some temporary result logs may be stored here)
73 * Repositories: the functest repository will be used to prepare the
74 environment and run the tests. Other repositories are used for the installation
75 of the needed tooling (e.g. rally) and/or the retrieval of feature projects
76 scenarios (e.g. promise)
78 The structure under the Functest repository can be described as follows::
86 | `-- traffic-profile-guidelines.rst
91 | |-- requirements.pip
107 |-- config_functest.py
108 |-- config_functest.yaml
109 `-- functest_utils.py
111 We may distinguish 4 different folders:
113 * **commons**: it is a folder dedicated to store traffic profile or any test
114 inputs that could be reused by any test project
115 * **docker**: this folder includes the scripts that will be used to setup the
116 environment and run the tests
117 * **docs**: this folder includes the user and installation/configuration guide
118 * **testcases**: this folder includes the scripts required by Functest internal
119 test cases and other feature projects test cases.
121 After the *run* command, a new prompt appears which means that we are inside the
122 container and ready to move to the next step.
125 Useful Docker commands
126 ----------------------
128 When typing **exit** in the container prompt, this will cause
129 exiting the container and probably stopping it. When stopping a running Docker container
130 all the changes will be lost, there is a keyboard shortcut to
131 quit the container without stopping it: CTRL+P+Q.
132 To reconnect to the running container **DO NOT** use the *run* command again
133 (since it will create a new container), use *exec* instead::
136 <copy the container ID>
137 docker exec -ti <CONTAINER_ID> /bin/bash
141 docker exec -ti $(docker ps|grep functest|awk '{print $1}') /bin/bash
143 There are other useful Docker commands that might be needed to manage possible
144 issues with the containers.
146 List the running containers::
150 List all the containers including the stopped ones::
154 It is useful sometimes to remove a container if there are some problems::
156 docker rm <CONTAINER_ID>
158 Use the *-f* option if the container is still running, it will force to destroy it::
160 docker -f rm <CONTAINER_ID>
162 The Docker image is called **opnfv/functest** and it is stored in the public
163 Docker registry under the OPNFV account: dockerhub_.
164 The are many different tags that have been created automatically by the CI
165 mechanisms, but the one that this document refers to is **brahmaputra.1.0**.
166 Pulling other tags might cause some problems while running the tests.
168 Check the Docker documentation dockerdocs_ for more information.
171 Preparing the Functest environment
172 ----------------------------------
174 Once the docker container is up and running, execute the following command in the
177 ${repos_dir}/functest/docker/prepare_env.sh
179 NOTE: **${repos_dir}** is a default environment variable inside the docker
180 container, which points to */home/opnfv/repos/*
182 This script will make sure that the requirements to run the tests are met and will
183 install the needed libraries and tools by all Functest test cases. It must be run
184 only once every time the docker is started from sratch.
187 Focus on the OpenStack credentials
188 ----------------------------------
190 The OpenStack credentials are needed to run the tests against the VIM.
191 There are 3 ways to provide them to Functest:
193 * using the -v option when running the Docker container
194 * create an empty file in /home/opnfv/functest/conf/openstack.creds and paste
195 the credentials in it.
196 * automatically retrieved using the following script::
197 $repos_dir/releng/utils/fetch_os_creds.sh
199 Once the credentials are there, they shall be sourced before running the tests::
201 source /home/opnfv/functest/conf/openstack.creds
203 or simply using the environment variable **creds**::
207 After this, try to run any OpenStack command to see if you get any output,
212 This will return a list of the actual users in the OpenStack deployment. In any
213 other case, check that the credentials are sourced::
217 This command must show a set of environment variables starting with *OS_*, for example::
219 OS_REGION_NAME=RegionOne
220 OS_DEFAULT_DOMAIN=default
221 OS_PROJECT_NAME=admin
223 OS_AUTH_STRATEGY=keystone
224 OS_AUTH_URL=http://172.30.10.3:5000/v2.0
227 OS_ENDPOINT_TYPE=internalURL
230 If still the OpenStack command does not show anything or complains about
231 connectivity issues, it could be due to an incorrect url given to the OS_AUTH_URL
232 environment variable. Check the deployment settings.
237 In case you need to provide different configuration parameters to Functest (e.g.
238 commit IDs or branches for the repositories, ...) copy the **config_functest.yaml**
239 from the repository to your current directory and run the container with a volume::
241 wget https://git.opnfv.org/cgit/functest/plain/testcases/config_functest.yaml
243 <modify the file accordingly>
246 "INSTALLER_TYPE=fuel" -e "INSTALLER_IP=10.20.0.2" \
247 opnfv/functest:brahmaputra.1.0 \
248 -v $(pwd)/config_functest.yaml:/home/opnfv/functest/conf/config_functest.yaml \
251 However, this is not recommended since most of the test cases rely on static
252 parameters read from this file, and changing them might cause problems.
258 Functest needs internet access to download some resources for some test cases.
259 For example to install the Rally environment. This might not work properly if
260 the Jumphost is running through a Proxy.
262 If that is the case, make sure the resolv.conf and the needed proxy environment
263 variables are properly set::
265 export http_proxy=<your http proxy settings>
266 export https_proxy=<your https proxy settings>
268 Or refer to the official Docker documentation for Proxy_ settings.
270 Before running **prepare_env.sh** make sure you can ping http and https sites
271 inside the container. For example::
274 Connection to google.com 80 port [tcp/http] succeeded!
277 Connection to google.com 443 port [tcp/https] succeeded!
281 .. _dockerdocs: https://docs.docker.com/
282 .. _dockerhub: https://hub.docker.com/r/opnfv/functest/
283 .. _Proxy: https://docs.docker.com/engine/admin/systemd/#http-proxy