docs/configguide/configguide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4
   5 Preparing the Docker container
   6 ------------------------------
   7
   8 Pull the Functest Docker image from the Docker hub::
   9
  10   docker pull opnfv/functest:brahmaputra.1.0
  11
  12
  13 Check that the image is available::
  14
  15   docker images
  16
  17 Run the docker container giving the environment variables:
  18
  19  * **INSTALLER_TYPE** : possible values are **apex**, **compass**, **fuel** or **joid**.
  20  * **INSTALLER_IP** : IP of the installer node/VM.
  21
  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.
  24
  25 The minimum command to create the Functest Docker container can be described as
  26 follows::
  27
  28   docker run -it -e "INSTALLER_IP=10.20.0.2" -e "INSTALLER_TYPE=fuel" opnfv/functest:brahmaputra.1.0 /bin/bash
  29
  30 Optionally, it is possible to precise the container name through the option
  31 **--name**::
  32
  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
  34
  35 It is also possible to to indicate the path of the OpenStack credentials using **-v**::
  36
  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
  38
  39 The local file will be mounted in the container under
  40 */home/opnfv/functest/conf/openstack.creds*
  41
  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**,
  44 for example::
  45
  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
  47
  48 Inside the container, the following directory structure should be in place::
  49
  50   `-- home
  51       `-- opnfv
  52         |-- functest
  53         |   |-- conf
  54         |   |-- data
  55         |   `-- results
  56         `-- repos
  57             |-- bgpvpn
  58             |-- doctor
  59             |-- functest
  60             |-- odl_integration
  61             |-- onos
  62             |-- promise
  63             |-- rally
  64             |-- releng
  65             `-- vims-test
  66
  67
  68 Basically the container includes:
  69
  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)
  77
  78 The structure under the Functest repository can be described as follows::
  79
  80   .
  81     |-- INFO
  82     |-- LICENSE
  83     |-- commons
  84     |   |-- ims
  85     |   |-- mobile
  86     |   `-- traffic-profile-guidelines.rst
  87     |-- docker
  88     |   |-- Dockerfile
  89     |   |-- common.sh
  90     |   |-- prepare_env.sh
  91     |   |-- requirements.pip
  92     |   `-- run_tests.sh
  93     |-- docs
  94     |   |-- configguide
  95     |   |-- devguide
  96     |   |-- images
  97     |   |-- results
  98     |   `-- userguide
  99     `-- testcases
 100         |-- Controllers
 101         |-- features
 102         |-- tests
 103         |-- VIM
 104         |-- vIMS
 105         |-- vPing
 106         |-- __init__.py
 107         |-- config_functest.py
 108         |-- config_functest.yaml
 109         `-- functest_utils.py
 110
 111 We may distinguish 4 different folders:
 112
 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.
 120
 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.
 123
 124
 125 Useful Docker commands
 126 ----------------------
 127
 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::
 134
 135   docker ps
 136   <copy the container ID>
 137   docker exec -ti <CONTAINER_ID> /bin/bash
 138
 139 or simply::
 140
 141   docker exec -ti $(docker ps|grep functest|awk '{print $1}') /bin/bash
 142
 143 There are other useful Docker commands that might be needed to manage possible
 144 issues with the containers.
 145
 146 List the running containers::
 147
 148    docker ps
 149
 150 List all the containers including the stopped ones::
 151
 152   docker ps -a
 153
 154 It is useful sometimes to remove a container if there are some problems::
 155
 156   docker rm <CONTAINER_ID>
 157
 158 Use the *-f* option if the container is still running, it will force to destroy it::
 159
 160   docker -f rm <CONTAINER_ID>
 161
 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.
 167
 168 Check the Docker documentation dockerdocs_ for more information.
 169
 170
 171 Preparing the Functest environment
 172 ----------------------------------
 173
 174 Once the docker container is up and running, execute the following command in the
 175 prompt::
 176
 177     ${repos_dir}/functest/docker/prepare_env.sh
 178
 179 NOTE: **${repos_dir}** is a default environment variable inside the docker
 180 container, which points to */home/opnfv/repos/*
 181
 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.
 185
 186
 187 Focus on the OpenStack credentials
 188 ----------------------------------
 189
 190 The OpenStack credentials are needed to run the tests against the VIM.
 191 There are 3 ways to provide them to Functest:
 192
 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
 198
 199 Once the credentials are there, they shall be sourced before running the tests::
 200
 201     source /home/opnfv/functest/conf/openstack.creds
 202
 203 or simply using the environment variable **creds**::
 204
 205     . $creds
 206
 207 After this, try to run any OpenStack command to see if you get any output,
 208 for instance::
 209
 210     openstack user list
 211
 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::
 214
 215     env|grep OS_
 216
 217 This command must show a set of environment variables starting with *OS_*, for example::
 218
 219     OS_REGION_NAME=RegionOne
 220     OS_DEFAULT_DOMAIN=default
 221     OS_PROJECT_NAME=admin
 222     OS_PASSWORD=admin
 223     OS_AUTH_STRATEGY=keystone
 224     OS_AUTH_URL=http://172.30.10.3:5000/v2.0
 225     OS_USERNAME=admin
 226     OS_TENANT_NAME=admin
 227     OS_ENDPOINT_TYPE=internalURL
 228     OS_NO_CACHE=true
 229
 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.
 233
 234 Additional Options
 235 ------------------
 236
 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::
 240
 241     wget https://git.opnfv.org/cgit/functest/plain/testcases/config_functest.yaml
 242
 243     <modify the file accordingly>
 244
 245     docker run -ti -e \
 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 \
 249     /bin/bash\
 250
 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.
 253
 254
 255 Proxy support
 256 -------------
 257
 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.
 261
 262 If that is the case, make sure the resolv.conf and the needed proxy environment
 263 variables are properly set::
 264
 265     export http_proxy=<your http proxy settings>
 266     export https_proxy=<your https proxy settings>
 267
 268 Or refer to the official Docker documentation for Proxy_ settings.
 269
 270 Before running **prepare_env.sh** make sure you can ping http and https sites
 271 inside the container. For example::
 272
 273     nc -v google.com 80
 274     Connection to google.com 80 port [tcp/http] succeeded!
 275
 276     nc -v google.com 443
 277     Connection to google.com 443 port [tcp/https] succeeded!
 278
 279
 280
 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