docs/configguide/index.rst

   1 ***********************************************
   2 OPNFV FUNCTEST configuration/installation guide
   3 ***********************************************
   4
   5 .. toctree::
   6    :numbered:
   7    :maxdepth: 2
   8
   9 ============
  10 Introduction
  11 ============
  12
  13 ** DOCUMENT IS IN PROGRESS FOR BRAHMAPUTRA **
  14
  15 This document describes how to install and configure Functest in OPNFV.
  16
  17 =============
  18 Prerequisites
  19 =============
  20
  21 The installation of the OPNFV solution is out of scope of this document but can be found in XXX.
  22 In the rest of the document the OPNFV solution would be considered as the System Under Test (SUT).
  23
  24 Several prerequisites are needed for functest:
  25  1) docker must be installed on the Jumphost
  26  2) a connectivity from the jumphost to the SUT management network is needed
  27  3) an external network must be configured
  28
  29 Docker installation
  30 ===================
  31
  32 .. _Ubuntu: https://docs.docker.com/installation/ubuntulinux/
  33 .. _RHEL: https://docs.docker.com/installation/rhel/
  34
  35 Log on your jumphost then install docker (e.g. for Ubuntu)::
  36
  37  curl -sSL https://get.docker.com/ | sh
  38
  39 Add your user to docker group to be able to run commands without sudo::
  40
  41  sudo usermod -aG docker <your_user>
  42
  43
  44 References:
  45   * Ubuntu_
  46   * RHEL_
  47
  48 Connectivy to OPNFV management network
  49 ======================================
  50
  51 Some of the Functest tools need to have access to the OpenStack management network of the controllers `[1]`_.
  52
  53 For this reason and besides the public network, you need to configure an interface on the management network as well in your jumphost (or wherever you want to deploy the Functest docker to run the tests).
  54
  55 Example::
  56
  57  The OPNFV Fuel installation uses VLAN tagged 300 and subnet 192.168.1.0/24 as Openstack Management network.
  58  Supposing that eth1 is the physical interface with access to that subnet:
  59  $ ip link add name eth1.300 link eth1 type vlan id 300
  60  $ ip link set eth1.300 up
  61  $ ip addr add 192.168.1.66/24 dev eth1.300
  62
  63
  64 External network on SUT
  65 =======================
  66
  67 Some of the tests on VIM need an external network. You may perform functest without an external network but some of the tests will fail.
  68 A default floating ip pool must be configured in nova.conf.
  69
  70
  71
  72 =======================
  73 High level architecture
  74 =======================
  75
  76 The high level architecture of Functest within OPNFV can be described as follow::
  77
  78  CIMC/Lights+out management                         Admin     Private   Public   Storage
  79                                                      PXE
  80                                                                            +
  81  +                                                     +     IP_PRIV/24    |        |
  82  |                                                     |         +         +        |
  83  |                                                     |         |    IP_PUB/24     |
  84  |     +--------------------------+                    |         |         +        |
  85  |     |                          |                    |         |         |        |
  86  +-----+       Jumphost           |                    |         |         |        |
  87  |     |                          +--------------------+         |         |        |
  88  |     |                          |                    |         |         |        |
  89  |     |   +------------------+   |                    |         |         |        |
  90  |     |   |                  |   |                    |         |         |        |
  91  |     |   | Tools            |   +------------------------------+         |        |
  92  |     |   | - Rally          |   |                    |         |         |        |
  93  |     |   | - Robot          |   |                    |         |         |        |
  94  |     |   | - TestON         |   |                    |         |         |        |
  95  |     |   |                  |   |                    |         |         |        |
  96  |     |   | Testcases        |   |                    |         |         |        |
  97  |     |   | - VIM            |   |                    |         |         |        |
  98  |     |   |  -- vPing        |   |                    |         |         |        |
  99  |     |   |  -- Tempest      |   |                    |         |         |        |
 100  |     |   |  -- Rally        |   |                    |         |         |        |
 101  |     |   | - Controller     |   |                    |         |         |        |
 102  |     |   |  -- odl          |   |                    |         |         |        |
 103  |     |   |  -- onos         |   |                    |         |         |        |
 104  |     |   |  -- opencontrail |   |                    |         |         |        |
 105  |     |   |                  |   |                    |         |         |        |
 106  |     |   | Features         |   |                    |         |         |        |
 107  |     |   | - vIMS           |   |                    |         |         |        |
 108  |     |   |                  |   |                    |         |         |        |
 109  |     |   +------------------+   |                    |         |         |        |
 110  |     |                          +----------------------------------------+        |
 111  |     |    Functest Docker       |                    |         |         |        |
 112  |     |                          +-------------------------------------------------+
 113  |     |                          |                    |         |         |        |
 114  |     +--------------------------+                    |         |         |        |
 115  |                                                     |         |         |        |
 116  |    +----------------+                               |         |         |        |
 117  |    |             1  |                               |         |         |        |
 118  +----+ +--------------+-+                             |         |         |        |
 119  |    | |             2  |                             |         |         |        |
 120  |    | | +--------------+-+                           |         |         |        |
 121  |    | | |             3  |                           |         |         |        |
 122  |    | | | +--------------+-+                         |         |         |        |
 123  |    | | | |             4  |                         |         |         |        |
 124  |    +-+ | | +--------------+-+                       |         |         |        |
 125  |      | | | |             5  +-----------------------+         |         |        |
 126  |      +-+ | |  nodes for     |                       |         |         |        |
 127  |        | | |  deploying     +---------------------------------+         |        |
 128  |        +-+ |  opnfv         |                       |         |         |        |
 129  |          | |     SUT        +-------------------------------------------+        |
 130  |          +-+                |                       |         |         |        |
 131  |            |                +----------------------------------------------------+
 132  |            +----------------+                       |         |         |        |
 133  |                                                     |         |         |        |
 134  |                                                     +         +         +        +
 135
 136 All the components needed by Functest are in the docker file.
 137 Thanks to docker, there is no more library issues.
 138
 139 This docker file will:
 140   * prepare the environment for functional testing
 141   * retrieve SUT credentials
 142   * perform the tests
 143   * push the results into the OPNFV test result database
 144
 145 This docker file can be integrated into CI or deployed independantly of the CI.
 146 A description of the Brahmaputra testcases can be retrieved in the Functest user guide `[2]`_
 147
 148 Please note that the Functest container has been designed for OPNFV, however, it would be possible to adapt it to any VIM+controller environment as most of the testcases are upstream testcases.
 149
 150 ===================
 151 Manual Installation
 152 ===================
 153
 154 Pull the Functest Docker image from the hub::
 155
 156  $ docker pull opnfv/functest
 157
 158 Check that the image is available::
 159
 160  $ docker images
 161
 162 Run the docker container giving the environment variables
 163  - INSTALLER_TYPE. Possible values are "apex", "compass", "fuel", "joid" or "foreman" (Arno).
 164  - INSTALLER_IP. each installer has its installation strategy. Functest may need to know the IP of the installer to retrieve the credentials (e.g. usually "10.20.0.2" for fuel, not neede for joid, "172.30.10.73" foreman...)
 165
 166 The minimum command to create the Functest docker file can be described as follow::
 167
 168  docker run -it -e "INSTALLER_IP=10.20.0.2" -e "INSTALLER_TYPE=fuel" opnfv/functest:latest_stable /bin/bash
 169
 170 Optionnaly, it is possible to precise the container name through the option --name::
 171
 172  docker run --name "CONTAINER_NAME" -it -e "INSTALLER_IP=10.20.0.2" -e "INSTALLER_TYPE=fuel" opnfv/functest:latest_stable /bin/bash
 173
 174 It is also possible to to indicate the path of the OpenStack creds using -v::
 175
 176  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:latest_stable /bin/bash
 177
 178 Your local file will be paste within the container under /home/opnfv/functest/conf/openstack.creds and used by the different test suites.
 179
 180 Once run you shall be inside the docker container and ready to run Functest.
 181
 182 Inside the container, you must have the following arborescence::
 183
 184   `-- home
 185       `-- opnfv
 186         |-- functest
 187         |   |-- conf
 188         |   |-- data
 189         |   `-- results
 190         `-- repos
 191             |-- bgpvpn
 192             |-- functest
 193             |-- odl_integration
 194             |-- rally
 195             |-- releng
 196             `-- vims-test
 197
 198
 199 Basically the container includes:
 200
 201   * Functest directory to store the configuration (the OpenStack creds are paste in /home/opngb/functest/conf), the data (images neede for test for offline testing), results (some temporary artifacts may be stored here)
 202   * Repositories: the functest repository will be used to prepare the environement, run the tests. Other repositories are used for the installation of the tooling (e.g. rally) and/or the retrieval of feature projects scenarios (e.g. bgpvpn)
 203
 204 The arborescence under the functest repo can be described as follow::
 205
 206   .
 207     |-- INFO
 208     |-- LICENSE
 209     |-- commons
 210     |   |-- ims
 211     |   |-- mobile
 212     |   `-- traffic-profile-guidelines.rst
 213     |-- docker
 214     |   |-- Dockerfile
 215     |   |-- common.sh
 216     |   |-- prepare_env.sh
 217     |   |-- requirements.pip
 218     |   `-- run_tests.sh
 219     |-- docs
 220     |   |-- configguide
 221     |   |-- functest.rst
 222     |   |-- images
 223     |   `-- userguide
 224     `-- testcases
 225         |-- Controllers
 226         |-- VIM
 227         |-- __init__.py
 228         |-- config_functest.py
 229         |-- config_functest.yaml
 230         |-- functest_utils.py
 231         |-- functest_utils.pyc
 232         |-- vIMS
 233         `-- vPing
 234
 235 We may distinguish 4 different folders:
 236
 237   * commons: it is a folder dedicated to store traffic profile or any test inputs that could be reused by any test project
 238   * docker: this folder includes the scripts that will be used to setup the environment and run the tests
 239   * docs: this folder includes the user and installation/configuration guide
 240   * testcases: this folder includes the scripts required by Functest internal test cases
 241
 242
 243 Firstly run the script to install functest environment::
 244
 245  $ ${repos_dir}/functest/docker/prepare_env.sh
 246
 247 NOTE: ${repos_dir} is a default environment variable inside the docker container, which points to /home/opnfv/repos
 248
 249 Run the script to start the tests::
 250
 251  $ ${repos_dir}/functest/docker/run_tests.sh
 252
 253 NOTE: This will run ALL the tests by default, see `[2]`_ for details
 254
 255 Focus on the OpenStack credentials
 256 ==================================
 257
 258 The OpenStack creds are needed to test the VIM. They can be retrieved in several ways:
 259   * using the -v option when creating
 260   * sourcing them manually once connected on the docker, once log perform a source <openstack_creds>
 261   * automatically retrieved via a script (CI)
 262
 263 If not source you will get an error during the test environnement preparation.
 264
 265 Additional Options
 266 ==================
 267
 268 In case you need to provide different configuration parameters to Functest (e.g. commit IDs or branches for the repositories, …) copy the config_functest.yaml from the repository to your current directory and run docker with a volume::
 269
 270  $ wget https://git.opnfv.org/cgit/functest/plain/testcases/config_functest.yaml
 271  $ cmd1 = "/home/opnfv/repos/functest/docker/prepare_env.sh"
 272  $ cmd2 = "/home/opnfv/repos/functest/docker/run_tests.sh"
 273  $ docker run -t -e "INSTALLER_TYPE=fuel" -e "INSTALLER_IP=10.20.0.2" opnfv/functest \
 274    -v $(pwd)/config_functest.yaml:/home/opnfv/functest/conf/config_functest.yaml \
 275    "${cmd1} && ${cmd2}"
 276
 277 =================
 278 Integration in CI
 279 =================
 280 In CI we use the docker file and execute commande within the container from Jenkins.
 281
 282 Docker creation in set-functest-env builder `[3]`_::
 283
 284     envs="INSTALLER_TYPE=${INSTALLER_TYPE} -e INSTALLER_IP=${INSTALLER_IP} -e NODE_NAME=${NODE_NAME}"
 285     [...]
 286     docker pull opnfv/functest:latest_stable
 287     cmd="docker run -id -e $envs ${labconfig} ${sshkey} ${res_volume} opnfv/functest:latest_stable /bin/bash"
 288     echo "Functest: Running docker run command: ${cmd}"
 289     ${cmd}
 290     docker ps -a
 291     sleep 5
 292     container_id=$(docker ps | grep 'opnfv/functest:latest_stable' | awk '{print $1}' | head -1)
 293     echo "Container ID=${container_id}"
 294     if [ -z ${container_id} ]; then
 295         echo "Cannot find opnfv/functest container ID ${container_id}. Please check if it is existing."
 296         docker ps -a
 297         exit 1
 298     fi
 299     echo "Starting the container: docker start ${container_id}"
 300     docker start ${container_id}
 301     sleep 5
 302     docker ps
 303     if [ $(docker ps | grep 'opnfv/functest:latest_stable' | wc -l) == 0 ]; then
 304         echo "The container opnfv/functest with ID=${container_id} has not been properly started. Exiting..."
 305         exit 1
 306     fi
 307     cmd="${FUNCTEST_REPO_DIR}/docker/prepare_env.sh"
 308     echo "Executing command inside the docker: ${cmd}"
 309     docker exec ${container_id} ${cmd}
 310
 311
 312 Test execution in functest-all builder `[3]`_::
 313
 314   echo "Functest: run $FUNCTEST_SUITE_NAME"
 315   cmd="${FUNCTEST_REPO_DIR}/docker/run_tests.sh --test $FUNCTEST_SUITE_NAME ${flag}"
 316   container_id=$(docker ps -a | grep opnfv/functest | awk '{print $1}' | head -1)
 317   docker exec $container_id $cmd
 318
 319 Docker clean in functest-cleanup builder `[3]`_::
 320
 321     echo "Cleaning up docker containers/images..."
 322     # Remove previous running containers if exist
 323     if [[ ! -z $(docker ps -a | grep opnfv/functest) ]]; then
 324     echo "Removing existing opnfv/functest containers..."
 325     docker ps | grep opnfv/functest | awk '{print $1}' | xargs docker stop
 326     docker ps -a | grep opnfv/functest | awk '{print $1}' | xargs docker rm
 327     fi
 328
 329     # Remove existing images if exist
 330     if [[ ! -z $(docker images | grep opnfv/functest) ]]; then
 331     echo "Docker images to remove:"
 332     docker images | head -1 && docker images | grep opnfv/functest
 333     image_tags=($(docker images | grep opnfv/functest | awk '{print $2}'))
 334     for tag in "${image_tags[@]}"; do
 335         echo "Removing docker image opnfv/functest:$tag..."
 336         docker rmi opnfv/functest:$tag
 337     done
 338     fi
 339
 340
 341 =============
 342 Configuration
 343 =============
 344
 345 Everything is preconfigured in the docker file. So except the credentials, there is no specific configuration needed. it is possible to customize the list of tests, see `[2]` for details.
 346
 347 ======
 348 Errors
 349 ======
 350
 351
 352
 353
 354
 355 ==========
 356 References
 357 ==========
 358 .. _`[1]`: https://ask.openstack.org/en/question/68144/keystone-unable-to-use-the-public-endpoint/
 359 .. _`[2]`: url functest user guide
 360 .. _`[3]`: https://git.opnfv.org/cgit/releng/tree/jjb/functest/functest-ci-jobs.yml
 361
 362
 363 OPNFV main site: opnfvmain_.
 364
 365 OPNFV functional test page: opnfvfunctest_.
 366
 367 IRC support chan: #opnfv-testperf
 368
 369 .. _opnfvmain: http://www.opnfv.org
 370 .. _opnfvfunctest: https://wiki.opnfv.org/opnfv_functional_testing
 371 .. _`OpenRC`: http://docs.openstack.org/user-guide/common/cli_set_environment_variables_using_openstack_rc.html
 372 .. _`Rally installation procedure`: https://rally.readthedocs.org/en/latest/tutorial/step_0_installation.html
 373 .. _`config_test.py` : https://git.opnfv.org/cgit/functest/tree/testcases/config_functest.py
 374 .. _`config_functest.yaml` : https://git.opnfv.org/cgit/functest/tree/testcases/config_functest.yaml