docs/testing/user/configguide/index.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 OPNFV FUNCTEST Configuration Guide
   6 ==================================
   7
   8 .. toctree::
   9    :numbered:
  10    :maxdepth: 2
  11
  12 Version history
  13 ===============
  14
  15 +------------+----------+------------------+----------------------------------+
  16 | **Date**   | **Ver.** | **Author**       | **Comment**                      |
  17 |            |          |                  |                                  |
  18 +------------+----------+------------------+----------------------------------+
  19 | 2016-08-17 | 1.0.0    | Juha Haapavirta  | Colorado release                 |
  20 |            |          | Column Gaynor    |                                  |
  21 +------------+----------+------------------+----------------------------------+
  22 | 2017-01-19 | 1.0.1    | Morgan Richomme  | Adaptations for Danube           |
  23 |            |          |                  | * update testcase list           |
  24 |            |          |                  | * update docker command          |
  25 +------------+----------+------------------+----------------------------------+
  26
  27 Introduction
  28 ============
  29 This document describes how to install and configure Functest in OPNFV.
  30 The Functest CLI is used during the Functest environment preparation
  31 phase. The given example commands should work in both virtual and bare
  32 metal cases alike.
  33
  34 High level architecture
  35 -----------------------
  36
  37 The high level architecture of Functest within OPNFV can be described as
  38 follows::
  39
  40  CIMC/Lights+out management               Admin  Mgmt/API  Public  Storage Private
  41                                            PXE
  42  +                                           +       +        +       +       +
  43  |                                           |       |        |       |       |
  44  |     +----------------------------+        |       |        |       |       |
  45  |     |                            |        |       |        |       |       |
  46  +-----+       Jumphost             |        |       |        |       |       |
  47  |     |                            +--------+       |        |       |       |
  48  |     |                            |        |       |        |       |       |
  49  |     |   +--------------------+   |        |       |        |       |       |
  50  |     |   |                    |   |        |       |        |       |       |
  51  |     |   | Tools              |   +----------------+        |       |       |
  52  |     |   | - Rally            |   |        |       |        |       |       |
  53  |     |   | - Robot            |   |        |       |        |       |       |
  54  |     |   | - TestON           |   |        |       |        |       |       |
  55  |     |   | - RefStack         |   |        |       |        |       |       |
  56  |     |   |                    |   |-------------------------+       |       |
  57  |     |   | Testcases          |   |        |       |        |       |       |
  58  |     |   | - VIM              |   |        |       |        |       |       |
  59  |     |   |                    |   |        |       |        |       |       |
  60  |     |   | - SDN Controller   |   |        |       |        |       |       |
  61  |     |   |                    |   |        |       |        |       |       |
  62  |     |   | - Features         |   |        |       |        |       |       |
  63  |     |   |                    |   |        |       |        |       |       |
  64  |     |   | - VNF              |   |        |       |        |       |       |
  65  |     |   |                    |   |        |       |        |       |       |
  66  |     |   +--------------------+   |        |       |        |       |       |
  67  |     |     Functest Docker        +        |       |        |       |       |
  68  |     |                            |        |       |        |       |       |
  69  |     |                            |        |       |        |       |       |
  70  |     |                            |        |       |        |       |       |
  71  |     +----------------------------+        |       |        |       |       |
  72  |                                           |       |        |       |       |
  73  |    +----------------+                     |       |        |       |       |
  74  |    |             1  |                     |       |        |       |       |
  75  +----+ +--------------+-+                   |       |        |       |       |
  76  |    | |             2  |                   |       |        |       |       |
  77  |    | | +--------------+-+                 |       |        |       |       |
  78  |    | | |             3  |                 |       |        |       |       |
  79  |    | | | +--------------+-+               |       |        |       |       |
  80  |    | | | |             4  |               |       |        |       |       |
  81  |    +-+ | | +--------------+-+             |       |        |       |       |
  82  |      | | | |             5  +-------------+       |        |       |       |
  83  |      +-+ | |  nodes for     |             |       |        |       |       |
  84  |        | | |  deploying     +---------------------+        |       |       |
  85  |        +-+ |  OPNFV         |             |       |        |       |       |
  86  |          | |                +------------------------------+       |       |
  87  |          +-+     SUT        |             |       |        |       |       |
  88  |            |                +--------------------------------------+       |
  89  |            |                |             |       |        |       |       |
  90  |            |                +----------------------------------------------+
  91  |            +----------------+             |       |        |       |       |
  92  |                                           |       |        |       |       |
  93  +                                           +       +        +       +       +
  94               SUT = System Under Test
  95
  96 All the libraries and dependencies needed by all of the Functest tools
  97 are pre-installed into the Docker image. This allows running Functest
  98 on any platform on any Operating System.
  99
 100 The automated mechanisms inside the Functest Docker container will:
 101
 102   * Retrieve OpenStack credentials
 103   * Prepare the environment according to the System Under Test (SUT)
 104   * Perform the appropriate functional tests
 105   * Push the test results into the OPNFV test result database
 106
 107 This Docker image can be integrated into CI or deployed independently.
 108
 109 Please note that the Functest Docker container has been designed for OPNFV,
 110 however, it would be possible to adapt it to any OpenStack based VIM +
 111 controller environment, since most of the test cases are integrated from
 112 upstream communities.
 113
 114 The functional test cases are described in the Functest User Guide `[2]`_
 115
 116
 117 Prerequisites
 118 =============
 119 The OPNFV deployment is out of the scope of this document but it can be
 120 found in http://docs.opnfv.org.
 121 The OPNFV platform is considered as the SUT in this document.
 122
 123 Several prerequisites are needed for Functest:
 124
 125     #. A Jumphost to run Functest on
 126     #. A Docker daemon shall be installed on the Jumphost
 127     #. A public/external network created on the SUT
 128     #. An admin/management network created on the SUT
 129     #. Connectivity from the Jumphost to the SUT public/external network
 130     #. Connectivity from the Jumphost to the SUT admin/management network
 131
 132 WARNING: Connectivity from Jumphost is essential and it is of paramount
 133 importance to make sure it is working before even considering to install
 134 and run Functest. Make also sure you understand how your networking is
 135 designed to work.
 136
 137 NOTE: **Jumphost** refers to any server which meets the previous
 138 requirements. Normally it is the same server from where the OPNFV
 139 deployment has been triggered previously.
 140
 141 NOTE: If your Jumphost is operating behind a company http proxy and/or
 142 firewall, please consult first the section `Proxy Support`_, towards
 143 the end of this document. The section details some tips/tricks which
 144 *may* be of help in a proxified environment.
 145
 146 Docker installation
 147 -------------------
 148 Docker installation and configuration is only needed to be done once
 149 through the life cycle of Jumphost.
 150
 151 If your Jumphost is based on Ubuntu, SUSE, RHEL or CentOS linux, please
 152 consult the references below for more detailed instructions. The
 153 commands below are offered as a short reference.
 154
 155 *Tip:* For running docker containers behind the proxy, you need first
 156 some extra configuration which is described in section
 157 `Docker Installation on CentOS behind http proxy`_. You should follow
 158 that section before installing the docker engine.
 159
 160 Docker installation needs to be done as root user. You may use other
 161 userid's to create and run the actual containers later if so desired.
 162 Log on to your Jumphost as root user and install the Docker Engine
 163 (e.g. for CentOS family)::
 164
 165  curl -sSL https://get.docker.com/ | sh
 166  systemctl start docker
 167
 168  *Tip:* If you are working through proxy, please set the https_proxy
 169  environment variable first before executing the curl command.
 170
 171 Add your user to docker group to be able to run commands without sudo::
 172
 173  sudo usermod -aG docker <your_user>
 174
 175 A reconnection is needed. There are 2 ways for this:
 176     #. Re-login to your account
 177     #. su - <username>
 178
 179 References - Installing Docker Engine on different Linux Operating Systems:
 180   * Ubuntu_
 181   * RHEL_
 182   * CentOS_
 183   * SUSE_
 184
 185 .. _Ubuntu: https://docs.docker.com/engine/installation/linux/ubuntulinux/
 186 .. _RHEL:   https://docs.docker.com/engine/installation/linux/rhel/
 187 .. _CentOS: https://docs.docker.com/engine/installation/linux/centos/
 188 .. _SUSE: https://docs.docker.com/engine/installation/linux/suse/
 189
 190 Public/External network on SUT
 191 ------------------------------
 192 Some of the tests against the VIM (Virtual Infrastructure Manager) need
 193 connectivity through an existing public/external network in order to
 194 succeed. This is needed, for example, to create floating IPs to access
 195 VM instances through the public/external network (i.e. from the Docker
 196 container).
 197
 198 By default, the four OPNFV installers provide a fresh installation with
 199 a public/external network created along with a router. Make sure that
 200 the public/external subnet is reachable from the Jumphost.
 201
 202 *Hint:* For the given OPNFV Installer in use, the IP sub-net address
 203 used for the public/external network is usually a planning item and
 204 should thus be known. Consult the OPNFV Configuration guide `[4]`_, and
 205 ensure you can reach each node in the SUT, from the Jumphost using the
 206 'ping' command using the respective IP address on the public/external
 207 network for each node in the SUT. The details of how to determine the
 208 needed IP addresses for each node in the SUT may vary according to the
 209 used installer and are therefore ommitted here.
 210
 211 Connectivity to Admin/Management network on SUT
 212 -----------------------------------------------
 213 Some of the Functest tools need to have access to the OpenStack
 214 admin/management network of the controllers `[1]`_.
 215
 216 For this reason, check the connectivity from the Jumphost to all the
 217 controllers in cluster in the OpenStack admin/management network range.
 218
 219 Installation and configuration
 220 ==============================
 221
 222 .. include:: ./configguide.rst
 223
 224 Integration in CI
 225 =================
 226 In CI we use the Docker image and execute the appropriate commands within the
 227 container from Jenkins.
 228
 229 Docker creation in set-functest-env builder `[3]`_::
 230
 231     envs="-e INSTALLER_TYPE=${INSTALLER_TYPE} -e INSTALLER_IP=${INSTALLER_IP} -e NODE_NAME=${NODE_NAME}"
 232     [...]
 233     docker pull opnfv/functest:$DOCKER_TAG >/dev/null
 234     cmd="sudo docker run -id ${envs} ${volumes} ${custom_params} ${TESTCASE_OPTIONS} opnfv/functest:${DOCKER_TAG} /bin/bash"
 235     echo "Functest: Running docker run command: ${cmd}"
 236     ${cmd} >${redirect}
 237     sleep 5
 238     container_id=$(docker ps | grep "opnfv/functest:${DOCKER_TAG}" | awk '{print $1}' | head -1)
 239     echo "Container ID=${container_id}"
 240     if [ -z ${container_id} ]; then
 241         echo "Cannot find opnfv/functest container ID ${container_id}. Please check if it is existing."
 242         docker ps -a
 243         exit 1
 244     fi
 245     echo "Starting the container: docker start ${container_id}"
 246     docker start ${container_id}
 247     sleep 5
 248     docker ps >${redirect}
 249     if [ $(docker ps | grep "opnfv/functest:${DOCKER_TAG}" | wc -l) == 0 ]; then
 250         echo "The container opnfv/functest with ID=${container_id} has not been properly started. Exiting..."
 251         exit 1
 252     fi
 253
 254     cmd="python ${FUNCTEST_REPO_DIR}/functest/ci/prepare_env.py start"
 255     echo "Executing command inside the docker: ${cmd}"
 256     docker exec ${container_id} ${cmd}
 257
 258
 259 Test execution in functest-all builder `[3]`_::
 260
 261     branch=${GIT_BRANCH##*/}
 262     echo "Functest: run $FUNCTEST_SUITE_NAME on branch ${branch}"
 263     cmd="functest testcase run $FUNCTEST_SUITE_NAME"
 264     fi
 265     container_id=$(docker ps -a | grep opnfv/functest | awk '{print $1}' | head -1)
 266     docker exec $container_id $cmd
 267     ret_value=$?
 268     exit $ret_value
 269
 270 Docker clean in functest-cleanup builder `[3]`_ calling docker rm and docker rmi
 271
 272
 273 References
 274 ==========
 275 .. _`[1]`: https://ask.openstack.org/en/question/68144/keystone-unable-to-use-the-public-endpoint/
 276 .. _`[2]`: http://artifacts.opnfv.org/functest/docs/userguide/index.html
 277 .. _`[3]`: https://git.opnfv.org/cgit/releng/tree/jjb/functest/functest-ci-jobs.yml
 278 .. _`[4]`: http://artifacts.opnfv.org/functest/danube/docs/configguide/index.html
 279
 280
 281 `OPNFV main site`_
 282
 283 `Functest page`_
 284
 285 IRC support channel: #opnfv-functest
 286
 287 .. _`OPNFV main site`: http://www.opnfv.org
 288 .. _`Functest page`: https://wiki.opnfv.org/functest