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
  15 This document describes how to install and configure Functest in OPNFV.
  16
  17 High level architecture
  18 -----------------------
  19
  20 The high level architecture of Functest within OPNFV can be described as follows::
  21
  22  CIMC/Lights+out management                 Admin     Private   Public   Storage
  23                                              PXE
  24                                                                    +
  25  +                                             +     IP_PRIV/24    |        |
  26  |                                             |         +         +        |
  27  |                                             |         |    IP_PUB/24     |
  28  |     +----------------------------+          |         |         +        |
  29  |     |                            |          |         |         |        |
  30  +-----+       Jumphost             |          |         |         |        |
  31  |     |                            +----------+         |         |        |
  32  |     |                            |          |         |         |        |
  33  |     |   +--------------------+   |          |         |         |        |
  34  |     |   |                    |   |          |         |         |        |
  35  |     |   | Tools              |   +--------------------+         |        |
  36  |     |   | - Rally            |   |          |         |         |        |
  37  |     |   | - Robot            |   |          |         |         |        |
  38  |     |   | - TestON           |   |          |         |         |        |
  39  |     |   |                    |   |          |         |         |        |
  40  |     |   | Testcases          |   |          |         |         |        |
  41  |     |   | - VIM              |   |          |         |         |        |
  42  |     |   |  -- vPing          |   |          |         |         |        |
  43  |     |   |  -- vPing_userdata |   |          |         |         |        |
  44  |     |   |  -- Tempest        |   |          |         |         |        |
  45  |     |   |  -- Rally          |   |          |         |         |        |
  46  |     |   | - Controller       |   |          |         |         |        |
  47  |     |   |  -- odl            |   |          |         |         |        |
  48  |     |   |  -- onos           |   |          |         |         |        |
  49  |     |   |  -- opencontrail   |   |          |         |         |        |
  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  |          | |     SUT        +-----------------------------------+        |
  75  |          +-+                |               |         |         |        |
  76  |            |                +--------------------------------------------+
  77  |            +----------------+               |         |         |        |
  78  |                                             |         |         |        |
  79  |                                             +         +         +        +
  80
  81 All the libraries and dependencies needed by all the Functest tools are
  82 pre-installed in the Docker image.
  83 This allows running Functest on any platform on any Operating System.
  84
  85 The automated mechanisms inside the Functest Docker container will:
  86
  87   * retrieve OpenStack credentials
  88   * prepare the environment according to the SUT
  89   * perform the appropriate tests
  90   * push the results into the OPNFV test result database
  91
  92
  93 This Docker image can be integrated into CI or deployed independently.
  94
  95 Please note that the Functest container has been designed for OPNFV, however, it
  96 would be possible to adapt it to any VIM+controller environment since most of the
  97 test cases are integrated from upstream communities.
  98
  99 The test cases are described in the Functest User Guide `[2]`_
 100
 101
 102 Prerequisites
 103 =============
 104
 105 The OPNFV deployment is out of the scope of this document but it can be found in
 106 `[4]`_. The OPNFV platform is considered as the System Under Test (SUT) in this
 107 document.
 108
 109 Several prerequisites are needed for Functest:
 110
 111     #. A Jumphost to run Functest on
 112     #. Docker daemon shall be installed on the Jumphost
 113     #. A public/external network created on the SUT
 114     #. Connectivity from the Jumphost to the SUT public/external network
 115     #. Connectivity from the Jumphost to the SUT management network
 116
 117 NOTE: “Jumphost” refers to any server which meets the previous requirements.
 118 Normally it is the same server from where the OPNFV deployment has been
 119 triggered previously.
 120
 121 Docker installation
 122 -------------------
 123
 124 .. _Ubuntu: https://docs.docker.com/installation/ubuntulinux/
 125 .. _RHEL: https://docs.docker.com/installation/rhel/
 126
 127 Log on your Jumphost and install docker (e.g. for Ubuntu)::
 128
 129  curl -sSL https://get.docker.com/ | sh
 130
 131 Add your user to docker group to be able to run commands without sudo::
 132
 133  sudo usermod -aG docker <your_user>
 134
 135
 136 References:
 137
 138   * Ubuntu_
 139   * RHEL_
 140
 141 External network on SUT
 142 -----------------------
 143
 144 Some of the tests against the VIM (Virtual Infrastructure Manager) need an
 145 existing public network to succeed. This is needed, for example, to create
 146 floating IPs to access instances from the public network (i.e. Docker container).
 147
 148 By default, the four OPNFV installers provide a fresh installation with
 149 an external network created along with a router. Make sure that subnet
 150 is reachable from the Jumphost
 151
 152
 153 Connectivity to OPNFV management network
 154 ----------------------------------------
 155
 156 Some of the Functest tools need to have access to the OpenStack management
 157 network of the controllers `[1]`_.
 158
 159 For this reason, an interface shall be configured in the Jumphost in the
 160 OpenStack management network range.
 161
 162 For example, if the management network is on VLAN 300 and subnet 192.168.1.0/24
 163 and assuming that eth1 is the physical interface with access to that subnet::
 164
 165     ip link add name eth1.300 link eth1 type vlan id 300
 166     ip link set eth1.300 up
 167     ip addr add 192.168.1.66/24 dev eth1.300
 168
 169 This is just an example about how to configure an interface with vlan, but it might
 170 differ depending on the deployment settings on each installer. Check the
 171 corresponding installer instructions for more info.
 172
 173
 174 Installation and configuration
 175 ==============================
 176
 177 .. include:: ./configguide.rst
 178
 179
 180 Integration in CI
 181 =================
 182
 183 In CI we use the Docker image and execute the appropriate commands within the
 184 container from Jenkins.
 185
 186 Docker creation in set-functest-env builder `[3]`_::
 187
 188     envs="INSTALLER_TYPE=${INSTALLER_TYPE} -e INSTALLER_IP=${INSTALLER_IP} -e NODE_NAME=${NODE_NAME}"
 189     [...]
 190     docker pull opnfv/functest:latest_stable
 191     cmd="docker run -id -e $envs ${labconfig} ${sshkey} ${res_volume} opnfv/functest:latest_stable /bin/bash"
 192     echo "Functest: Running docker run command: ${cmd}"
 193     ${cmd}
 194     docker ps -a
 195     sleep 5
 196     container_id=$(docker ps | grep 'opnfv/functest:latest_stable' | awk '{print $1}' | head -1)
 197     echo "Container ID=${container_id}"
 198     if [ -z ${container_id} ]; then
 199         echo "Cannot find opnfv/functest container ID ${container_id}. Please check if it is existing."
 200         docker ps -a
 201         exit 1
 202     fi
 203     echo "Starting the container: docker start ${container_id}"
 204     docker start ${container_id}
 205     sleep 5
 206     docker ps
 207     if [ $(docker ps | grep 'opnfv/functest:latest_stable' | wc -l) == 0 ]; then
 208         echo "The container opnfv/functest with ID=${container_id} has not been properly started. Exiting..."
 209         exit 1
 210     fi
 211     cmd="${FUNCTEST_REPO_DIR}/docker/prepare_env.sh"
 212     echo "Executing command inside the docker: ${cmd}"
 213     docker exec ${container_id} ${cmd}
 214
 215
 216 Test execution in functest-all builder `[3]`_::
 217
 218   echo "Functest: run $FUNCTEST_SUITE_NAME"
 219   cmd="${FUNCTEST_REPO_DIR}/docker/run_tests.sh --test $FUNCTEST_SUITE_NAME ${flag}"
 220   container_id=$(docker ps -a | grep opnfv/functest | awk '{print $1}' | head -1)
 221   docker exec $container_id $cmd
 222
 223 Docker clean in functest-cleanup builder `[3]`_::
 224
 225     echo "Cleaning up docker containers/images..."
 226     # Remove previous running containers if exist
 227     if [[ ! -z $(docker ps -a | grep opnfv/functest) ]]; then
 228     echo "Removing existing opnfv/functest containers..."
 229     docker ps | grep opnfv/functest | awk '{print $1}' | xargs docker stop
 230     docker ps -a | grep opnfv/functest | awk '{print $1}' | xargs docker rm
 231     fi
 232
 233     # Remove existing images if exist
 234     if [[ ! -z $(docker images | grep opnfv/functest) ]]; then
 235     echo "Docker images to remove:"
 236     docker images | head -1 && docker images | grep opnfv/functest
 237     image_tags=($(docker images | grep opnfv/functest | awk '{print $2}'))
 238     for tag in "${image_tags[@]}"; do
 239         echo "Removing docker image opnfv/functest:$tag..."
 240         docker rmi opnfv/functest:$tag
 241     done
 242     fi
 243
 244
 245
 246 References
 247 ==========
 248 .. _`[1]`: https://ask.openstack.org/en/question/68144/keystone-unable-to-use-the-public-endpoint/
 249 .. _`[2]`: http://artifacts.opnfv.org/functest/docs/userguide/index.html
 250 .. _`[3]`: https://git.opnfv.org/cgit/releng/tree/jjb/functest/functest-ci-jobs.yml
 251 .. _`[4]`: http://artifacts.opnfv.org/opnfvdocs/brahmaputra/docs/configguide/index.html
 252
 253
 254 OPNFV main site: opnfvmain_.
 255
 256 OPNFV functional test page: opnfvfunctest_.
 257
 258 IRC support channel: #opnfv-testperf
 259
 260 .. _opnfvmain: http://www.opnfv.org
 261 .. _opnfvfunctest: https://wiki.opnfv.org/opnfv_functional_testing
 262 .. _`OpenRC`: http://docs.openstack.org/user-guide/common/cli_set_environment_variables_using_openstack_rc.html
 263 .. _`Rally installation procedure`: https://rally.readthedocs.org/en/latest/tutorial/step_0_installation.html
 264 .. _`config_test.py` : https://git.opnfv.org/cgit/functest/tree/testcases/config_functest.py
 265 .. _`config_functest.yaml` : https://git.opnfv.org/cgit/functest/tree/testcases/config_functest.yaml