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