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 A reconnect is needed. There are 2 ways for this:
 136     #. Re-login to your account
 137     #. su - <username>
 138
 139 References:
 140
 141   * Ubuntu_
 142   * RHEL_
 143
 144 External network on SUT
 145 -----------------------
 146
 147 Some of the tests against the VIM (Virtual Infrastructure Manager) need an
 148 existing public network to succeed. This is needed, for example, to create
 149 floating IPs to access instances from the public network (i.e. Docker container).
 150
 151 By default, the four OPNFV installers provide a fresh installation with
 152 an external network created along with a router. Make sure that subnet
 153 is reachable from the Jumphost
 154
 155
 156 Connectivity to OPNFV management network
 157 ----------------------------------------
 158
 159 Some of the Functest tools need to have access to the OpenStack management
 160 network of the controllers `[1]`_.
 161
 162 For this reason, an interface shall be configured in the Jumphost in the
 163 OpenStack management network range.
 164
 165 For example, if the management network is on VLAN 300 and subnet 192.168.1.0/24
 166 and assuming that eth1 is the physical interface with access to that subnet::
 167
 168     ip link add name eth1.300 link eth1 type vlan id 300
 169     ip link set eth1.300 up
 170     ip addr add 192.168.1.66/24 dev eth1.300
 171
 172 This is just an example about how to configure an interface with vlan, but it might
 173 differ depending on the deployment settings on each installer. Check the
 174 corresponding installer instructions for more info.
 175
 176
 177 Installation and configuration
 178 ==============================
 179
 180 .. include:: ./configguide.rst
 181
 182
 183 Integration in CI
 184 =================
 185
 186 In CI we use the Docker image and execute the appropriate commands within the
 187 container from Jenkins.
 188
 189 Docker creation in set-functest-env builder `[3]`_::
 190
 191     envs="INSTALLER_TYPE=${INSTALLER_TYPE} -e INSTALLER_IP=${INSTALLER_IP} -e NODE_NAME=${NODE_NAME}"
 192     [...]
 193     docker pull opnfv/functest:latest_stable
 194     cmd="docker run -id -e $envs ${labconfig} ${sshkey} ${res_volume} opnfv/functest:latest_stable /bin/bash"
 195     echo "Functest: Running docker run command: ${cmd}"
 196     ${cmd}
 197     docker ps -a
 198     sleep 5
 199     container_id=$(docker ps | grep 'opnfv/functest:latest_stable' | awk '{print $1}' | head -1)
 200     echo "Container ID=${container_id}"
 201     if [ -z ${container_id} ]; then
 202         echo "Cannot find opnfv/functest container ID ${container_id}. Please check if it is existing."
 203         docker ps -a
 204         exit 1
 205     fi
 206     echo "Starting the container: docker start ${container_id}"
 207     docker start ${container_id}
 208     sleep 5
 209     docker ps
 210     if [ $(docker ps | grep 'opnfv/functest:latest_stable' | wc -l) == 0 ]; then
 211         echo "The container opnfv/functest with ID=${container_id} has not been properly started. Exiting..."
 212         exit 1
 213     fi
 214     cmd="${FUNCTEST_REPO_DIR}/docker/prepare_env.sh"
 215     echo "Executing command inside the docker: ${cmd}"
 216     docker exec ${container_id} ${cmd}
 217
 218
 219 Test execution in functest-all builder `[3]`_::
 220
 221   echo "Functest: run $FUNCTEST_SUITE_NAME"
 222   cmd="${FUNCTEST_REPO_DIR}/docker/run_tests.sh --test $FUNCTEST_SUITE_NAME ${flag}"
 223   container_id=$(docker ps -a | grep opnfv/functest | awk '{print $1}' | head -1)
 224   docker exec $container_id $cmd
 225
 226 Docker clean in functest-cleanup builder `[3]`_::
 227
 228     echo "Cleaning up docker containers/images..."
 229     # Remove previous running containers if exist
 230     if [[ ! -z $(docker ps -a | grep opnfv/functest) ]]; then
 231     echo "Removing existing opnfv/functest containers..."
 232     docker ps | grep opnfv/functest | awk '{print $1}' | xargs docker stop
 233     docker ps -a | grep opnfv/functest | awk '{print $1}' | xargs docker rm
 234     fi
 235
 236     # Remove existing images if exist
 237     if [[ ! -z $(docker images | grep opnfv/functest) ]]; then
 238     echo "Docker images to remove:"
 239     docker images | head -1 && docker images | grep opnfv/functest
 240     image_tags=($(docker images | grep opnfv/functest | awk '{print $2}'))
 241     for tag in "${image_tags[@]}"; do
 242         echo "Removing docker image opnfv/functest:$tag..."
 243         docker rmi opnfv/functest:$tag
 244     done
 245     fi
 246
 247
 248
 249 References
 250 ==========
 251 .. _`[1]`: https://ask.openstack.org/en/question/68144/keystone-unable-to-use-the-public-endpoint/
 252 .. _`[2]`: http://artifacts.opnfv.org/functest/docs/userguide/index.html
 253 .. _`[3]`: https://git.opnfv.org/cgit/releng/tree/jjb/functest/functest-ci-jobs.yml
 254 .. _`[4]`: http://artifacts.opnfv.org/opnfvdocs/brahmaputra/docs/configguide/index.html
 255
 256
 257 OPNFV main site: opnfvmain_.
 258
 259 OPNFV functional test page: opnfvfunctest_.
 260
 261 IRC support channel: #opnfv-testperf
 262
 263 .. _opnfvmain: http://www.opnfv.org
 264 .. _opnfvfunctest: https://wiki.opnfv.org/opnfv_functional_testing
 265 .. _`OpenRC`: http://docs.openstack.org/user-guide/common/cli_set_environment_variables_using_openstack_rc.html
 266 .. _`Rally installation procedure`: https://rally.readthedocs.org/en/latest/tutorial/step_0_installation.html
 267 .. _`config_test.py` : https://git.opnfv.org/cgit/functest/tree/testcases/config_functest.py
 268 .. _`config_functest.yaml` : https://git.opnfv.org/cgit/functest/tree/testcases/config_functest.yaml