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