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