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 If you need to connect to a server that is TLS-enabled (the auth URL begins with ‘https’)
238 and it uses a certificate from a private CA or a self-signed certificate you will
239 need to specify the path to an appropriate CA certificate to use to validate the
240 server certificate with the environment variable OS_CACERT::
243 /etc/ssl/certs/ca.crt
245 However, this certificate does not exist in the container by default. It has to
246 be copied manually from the OpenStack deployment. This can be done in 2 ways:
248 #. Create manually that file and copy the contents from the OpenStack controller.
250 #. (recommended) Add the file using a Docker volume when starting the container::
252 -v <path_to_your_cert_file>:/etc/ssl/certs/ca.cert
255 You might need to export OS_CACERT environment variable inside the container::
257 export OS_CACERT=/etc/ssl/certs/ca.crt
260 Certificate verification can be turned off using OS_INSECURE=true.
261 For example, Fuel uses self-signed cacerts by default, so an pre step would be::
263 export OS_INSECURE=true
269 In case you need to provide different configuration parameters to Functest (e.g.
270 commit IDs or branches for the repositories, ...) copy the **config_functest.yaml**
271 from the repository to your current directory and run the container with a volume::
273 wget https://git.opnfv.org/cgit/functest/plain/testcases/config_functest.yaml
275 <modify the file accordingly>
278 "INSTALLER_TYPE=fuel" -e "INSTALLER_IP=10.20.0.2" \
279 opnfv/functest:brahmaputra.1.0 \
280 -v $(pwd)/config_functest.yaml:/home/opnfv/repos/functest/ci/config_functest.yaml \
283 However, this is not recommended since most of the test cases rely on static
284 parameters read from this file, and changing them might cause problems.
290 Functest needs internet access to download some resources for some test cases.
291 For example to install the Rally environment. This might not work properly if
292 the Jumphost is running through a Proxy.
294 If that is the case, make sure the resolv.conf and the needed proxy environment
295 variables are properly set::
297 export http_proxy=<your http proxy settings>
298 export https_proxy=<your https proxy settings>
300 Or refer to the official Docker documentation for Proxy_ settings.
302 Before running **prepare_env.sh** make sure you can ping http and https sites
303 inside the container. For example::
306 Connection to google.com 80 port [tcp/http] succeeded!
309 Connection to google.com 443 port [tcp/https] succeeded!
313 .. _dockerdocs: https://docs.docker.com/
314 .. _dockerhub: https://hub.docker.com/r/opnfv/functest/
315 .. _Proxy: https://docs.docker.com/engine/admin/systemd/#http-proxy