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