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