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