docs/configguide/index.rst

   1 ===============================================
   2 OPNFV FUNCTEST configuration/installation guide
   3 ===============================================
   4
   5 .. toctree::
   6    :numbered:
   7    :maxdepth: 2
   8
   9 Introduction
  10 ============
  11
  12 ** DOCUMENT IS IN PROGRESS FOR BRAHMAPUTRA **
  13
  14 This document describes how to install and configure Functest in OPNFV.
  15
  16 Prerequisites
  17 =============
  18
  19 The OPNFV deployment is out of the scope of this document but it can be found in
  20 XXX. The OPNFV platform is considered as the System Under Test (SUT) in this
  21 document.
  22
  23 Several prerequisites are needed for functest:
  24
  25     #. A Jumphost to run Functest on
  26     #. Docker daemon shall be installed on the Jumphost
  27     #. A public/external network created on the SUT
  28     #. Connectivity from the Jumphost to the SUT public/external network
  29     #. Connectivity from the Jumphost to the SUT management network
  30
  31 NOTE: “Jumphost” refers to any server which meets the previous requirements.
  32 Normally it is the same server from where the OPNFV deployment has been
  33 triggered.
  34
  35 Docker installation
  36 -------------------
  37
  38 .. _Ubuntu: https://docs.docker.com/installation/ubuntulinux/
  39 .. _RHEL: https://docs.docker.com/installation/rhel/
  40
  41 Log on your jumphost then install docker (e.g. for Ubuntu)::
  42
  43  curl -sSL https://get.docker.com/ | sh
  44
  45 Add your user to docker group to be able to run commands without sudo::
  46
  47  sudo usermod -aG docker <your_user>
  48
  49
  50 References:
  51
  52   * Ubuntu_
  53   * RHEL_
  54
  55 Connectivity to OPNFV management network
  56 ----------------------------------------
  57
  58 Some of the Functest tools need to have access to the OpenStack management
  59 network of the controllers `[1]`_.
  60
  61 For this reason, an interface shall be configured in the Jumphost in the
  62 OpenStack management network range.
  63
  64 Example::
  65
  66  The OPNFV Fuel installation uses VLAN tagged 300 and subnet 192.168.1.0/24 as
  67  Openstack Management network.
  68  .
  69  Supposing that eth1 is the physical interface with access to that subnet:
  70  $ ip link add name eth1.300 link eth1 type vlan id 300
  71  $ ip link set eth1.300 up
  72  $ ip addr add 192.168.1.66/24 dev eth1.300
  73
  74
  75 External network on SUT
  76 -----------------------
  77
  78 Some of the tests against the VIM (Virtual Infrastructure Manager) need an
  79 existing public network to succeed. This is needed, for example, to create
  80 floating IPs to access instances from the public network (i.e. Jumphost).
  81
  82 By default, any of the four OPNFV installers provide a fresh installation with
  83 an external network created along with a router.
  84
  85
  86
  87 High level architecture
  88 =======================
  89
  90 The high level architecture of Functest within OPNFV can be described as follow::
  91
  92  CIMC/Lights+out management                 Admin     Private   Public   Storage
  93                                              PXE
  94                                                                    +
  95  +                                             +     IP_PRIV/24    |        |
  96  |                                             |         +         +        |
  97  |                                             |         |    IP_PUB/24     |
  98  |     +----------------------------+          |         |         +        |
  99  |     |                            |          |         |         |        |
 100  +-----+       Jumphost             |          |         |         |        |
 101  |     |                            +----------+         |         |        |
 102  |     |                            |          |         |         |        |
 103  |     |   +--------------------+   |          |         |         |        |
 104  |     |   |                    |   |          |         |         |        |
 105  |     |   | Tools              |   +--------------------+         |        |
 106  |     |   | - Rally            |   |          |         |         |        |
 107  |     |   | - Robot            |   |          |         |         |        |
 108  |     |   | - TestON           |   |          |         |         |        |
 109  |     |   |                    |   |          |         |         |        |
 110  |     |   | Testcases          |   |          |         |         |        |
 111  |     |   | - VIM              |   |          |         |         |        |
 112  |     |   |  -- vPing          |   |          |         |         |        |
 113  |     |   |  -- vPing_userdata |   |          |         |         |        |
 114  |     |   |  -- Tempest        |   |          |         |         |        |
 115  |     |   |  -- Rally          |   |          |         |         |        |
 116  |     |   | - Controller       |   |          |         |         |        |
 117  |     |   |  -- odl            |   |          |         |         |        |
 118  |     |   |  -- onos           |   |          |         |         |        |
 119  |     |   |  -- opencontrail   |   |          |         |         |        |
 120  |     |   |                    |   |          |         |         |        |
 121  |     |   | Features           |   |          |         |         |        |
 122  |     |   | - vIMS             |   |          |         |         |        |
 123  |     |   |                    |   |          |         |         |        |
 124  |     |   +--------------------+   |          |         |         |        |
 125  |     |                            +------------------------------+        |
 126  |     |    Functest Docker         |          |         |         |        |
 127  |     |                            +---------------------------------------+
 128  |     |                            |          |         |         |        |
 129  |     +----------------------------+          |         |         |        |
 130  |                                             |         |         |        |
 131  |    +----------------+                       |         |         |        |
 132  |    |             1  |                       |         |         |        |
 133  +----+ +--------------+-+                     |         |         |        |
 134  |    | |             2  |                     |         |         |        |
 135  |    | | +--------------+-+                   |         |         |        |
 136  |    | | |             3  |                   |         |         |        |
 137  |    | | | +--------------+-+                 |         |         |        |
 138  |    | | | |             4  |                 |         |         |        |
 139  |    +-+ | | +--------------+-+               |         |         |        |
 140  |      | | | |             5  +---------------+         |         |        |
 141  |      +-+ | |  nodes for     |               |         |         |        |
 142  |        | | |  deploying     +-------------------------+         |        |
 143  |        +-+ |  opnfv         |               |         |         |        |
 144  |          | |     SUT        +-----------------------------------+        |
 145  |          +-+                |               |         |         |        |
 146  |            |                +--------------------------------------------+
 147  |            +----------------+               |         |         |        |
 148  |                                             |         |         |        |
 149  |                                             +         +         +        +
 150
 151 All the libraries and dependencies needed by all the Functest tools are
 152 pre-installed in the Docker image.
 153 This allows running Functest on any platform with any Operating System.
 154
 155 The Docker image will:
 156
 157   * retrieve OpenStack credentials
 158   * prepare the environment according to the SUT
 159   * perform the appropriate tests
 160   * push the results into the OPNFV test result database
 161
 162
 163
 164 This Docker image can be integrated into CI or deployed **independently** of the CI.
 165 A description of the Brahmaputra testcases can be retrieved in the Functest user
 166 guide `[2]`_
 167
 168 Please note that the Functest container has been designed for OPNFV, however, it
 169 would be possible to adapt it to any VIM+controller environment as most of the
 170 testcases are upstream testcases.
 171
 172 .. include:: ./configguide.rst
 173
 174 NOTE: This will run ALL the tests by default, see `[2]`_ for details
 175
 176 Focus on the OpenStack credentials
 177 ----------------------------------
 178
 179 The OpenStack credentials are needed to test the VIM. There are 3 ways to
 180 provide them to Functest:
 181
 182   * using the -v option when running the Docker container
 183   * create an empty file in /home/opnfv/functest/conf/openstack.creds and paste
 184     the needed info in it.
 185   * automatically retrieved using the following script::
 186          $repos_dir/releng/utils/fetch_os_creds.sh
 187
 188 Once the credentials are there, they shall be sourced before running the tests::
 189
 190     source /home/opnfv/functest/conf/openstack.creds
 191
 192 Additional Options
 193 ------------------
 194
 195 In case you need to provide different configuration parameters to Functest (e.g.
 196  commit IDs or branches for the repositories, ...) copy the config_functest.yaml
 197  from the repository to your current directory and run docker with a volume::
 198
 199     $ wget https://git.opnfv.org/cgit/functest/plain/testcases/config_functest.yaml
 200     $ cmd1 = "/home/opnfv/repos/functest/docker/prepare_env.sh"
 201     $ cmd2 = "/home/opnfv/repos/functest/docker/run_tests.sh"
 202     $ docker run -t -e "INSTALLER_TYPE=fuel" -e "INSTALLER_IP=10.20.0.2" opnfv/functest \
 203         -v $(pwd)/config_functest.yaml:/home/opnfv/functest/conf/config_functest.yaml \
 204         "${cmd1} && ${cmd2}"
 205
 206
 207 Integration in CI
 208 =================
 209
 210 In CI we use the docker file and execute commande within the container from
 211 Jenkins.
 212
 213 Docker creation in set-functest-env builder `[3]`_::
 214
 215     envs="INSTALLER_TYPE=${INSTALLER_TYPE} -e INSTALLER_IP=${INSTALLER_IP} -e NODE_NAME=${NODE_NAME}"
 216     [...]
 217     docker pull opnfv/functest:latest_stable
 218     cmd="docker run -id -e $envs ${labconfig} ${sshkey} ${res_volume} opnfv/functest:latest_stable /bin/bash"
 219     echo "Functest: Running docker run command: ${cmd}"
 220     ${cmd}
 221     docker ps -a
 222     sleep 5
 223     container_id=$(docker ps | grep 'opnfv/functest:latest_stable' | awk '{print $1}' | head -1)
 224     echo "Container ID=${container_id}"
 225     if [ -z ${container_id} ]; then
 226         echo "Cannot find opnfv/functest container ID ${container_id}. Please check if it is existing."
 227         docker ps -a
 228         exit 1
 229     fi
 230     echo "Starting the container: docker start ${container_id}"
 231     docker start ${container_id}
 232     sleep 5
 233     docker ps
 234     if [ $(docker ps | grep 'opnfv/functest:latest_stable' | wc -l) == 0 ]; then
 235         echo "The container opnfv/functest with ID=${container_id} has not been properly started. Exiting..."
 236         exit 1
 237     fi
 238     cmd="${FUNCTEST_REPO_DIR}/docker/prepare_env.sh"
 239     echo "Executing command inside the docker: ${cmd}"
 240     docker exec ${container_id} ${cmd}
 241
 242
 243 Test execution in functest-all builder `[3]`_::
 244
 245   echo "Functest: run $FUNCTEST_SUITE_NAME"
 246   cmd="${FUNCTEST_REPO_DIR}/docker/run_tests.sh --test $FUNCTEST_SUITE_NAME ${flag}"
 247   container_id=$(docker ps -a | grep opnfv/functest | awk '{print $1}' | head -1)
 248   docker exec $container_id $cmd
 249
 250 Docker clean in functest-cleanup builder `[3]`_::
 251
 252     echo "Cleaning up docker containers/images..."
 253     # Remove previous running containers if exist
 254     if [[ ! -z $(docker ps -a | grep opnfv/functest) ]]; then
 255     echo "Removing existing opnfv/functest containers..."
 256     docker ps | grep opnfv/functest | awk '{print $1}' | xargs docker stop
 257     docker ps -a | grep opnfv/functest | awk '{print $1}' | xargs docker rm
 258     fi
 259
 260     # Remove existing images if exist
 261     if [[ ! -z $(docker images | grep opnfv/functest) ]]; then
 262     echo "Docker images to remove:"
 263     docker images | head -1 && docker images | grep opnfv/functest
 264     image_tags=($(docker images | grep opnfv/functest | awk '{print $2}'))
 265     for tag in "${image_tags[@]}"; do
 266         echo "Removing docker image opnfv/functest:$tag..."
 267         docker rmi opnfv/functest:$tag
 268     done
 269     fi
 270
 271
 272 Configuration
 273 =============
 274
 275 Everything is preconfigured in the docker file.
 276 It is however possible to customize the list of tests, see `[2]` for details.
 277
 278 Errors
 279 ======
 280
 281
 282
 283
 284
 285 References
 286 ==========
 287 .. _`[1]`: https://ask.openstack.org/en/question/68144/keystone-unable-to-use-the-public-endpoint/
 288 .. _`[2]`: url functest user guide
 289 .. _`[3]`: https://git.opnfv.org/cgit/releng/tree/jjb/functest/functest-ci-jobs.yml
 290
 291
 292 OPNFV main site: opnfvmain_.
 293
 294 OPNFV functional test page: opnfvfunctest_.
 295
 296 IRC support channel: #opnfv-testperf
 297
 298 .. _opnfvmain: http://www.opnfv.org
 299 .. _opnfvfunctest: https://wiki.opnfv.org/opnfv_functional_testing
 300 .. _`OpenRC`: http://docs.openstack.org/user-guide/common/cli_set_environment_variables_using_openstack_rc.html
 301 .. _`Rally installation procedure`: https://rally.readthedocs.org/en/latest/tutorial/step_0_installation.html
 302 .. _`config_test.py` : https://git.opnfv.org/cgit/functest/tree/testcases/config_functest.py
 303 .. _`config_functest.yaml` : https://git.opnfv.org/cgit/functest/tree/testcases/config_functest.yaml