docs/userguide/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 user guide
   6 =========================
   7
   8 .. toctree::
   9    :maxdepth: 2
  10
  11
  12 Introduction
  13 ============
  14
  15 The goal of this document is to describe the OPNFV Functest test cases and to
  16 provide a procedure to execute them. In the OPNFV Colorado system release,
  17 a Functest CLI utility is introduced for easier execution of test procedures.
  18
  19 A overview presentation has been created for the first OPNFV Summit `[4]`_.
  20
  21 This document is a continuation of the OPNFV Functest Configuration Guide `[1]`_.
  22
  23 **IMPORTANT**: It is assumed here that the Functest Docker container is already
  24 properly deployed and that all instructions described in this guide are to be
  25 performed from *inside* the deployed Functest Docker container.
  26
  27 .. include:: ./introduction.rst
  28
  29 The different test cases are described in the remaining sections of this document.
  30
  31 VIM (Virtualized Infrastructure Manager)
  32 ----------------------------------------
  33
  34 Healthcheck
  35 ^^^^^^^^^^^
  36 In Colorado release a new Tier 'healthcheck' with one testcase 'healthcheck'
  37 is introduced. The healthcheck testcase verifies that some basic IP connectivity
  38 and  essential operations of OpenStack functionality over the command line are
  39 working correctly.
  40
  41 In particular, the following verifications are performed:
  42
  43   * DHCP agent functionality for IP address allocation
  44   * Openstack Authentication management functionality via the Keystone API
  45   * OpenStack Image management functionality via the Glance API
  46   * OpenStack Block Storage management functionality via the Cinder API
  47   * OpenStack Networking management functionality via the Neutron API
  48   * Openstack Compute management functionality via the NOVA API
  49
  50 Self-obviously, successful completion of the 'healthcheck' testcase is a
  51 necessary pre-requisite for the execution of all other test Tiers.
  52
  53
  54 vPing_ssh
  55 ^^^^^^^^^
  56
  57 Given the script **ping.sh**::
  58
  59     #!/bin/sh
  60     while true; do
  61         ping -c 1 $1 2>&1 >/dev/null
  62         RES=$?
  63         if [ "Z$RES" = "Z0" ] ; then
  64             echo 'vPing OK'
  65             break
  66         else
  67             echo 'vPing KO'
  68         fi
  69     sleep 1
  70     done
  71
  72
  73 The goal of this test is to establish an SSH connection using a floating IP
  74 on the Public/External network and verify that 2 instances can talk over a Private
  75 Tenant network::
  76
  77  vPing_ssh test case
  78  +-------------+                    +-------------+
  79  |             |                    |             |
  80  |             | Boot VM1 with IP1  |             |
  81  |             +------------------->|             |
  82  |   Tester    |                    |   System    |
  83  |             | Boot VM2           |    Under    |
  84  |             +------------------->|     Test    |
  85  |             |                    |             |
  86  |             | Create floating IP |             |
  87  |             +------------------->|             |
  88  |             |                    |             |
  89  |             | Assign floating IP |             |
  90  |             | to VM2             |             |
  91  |             +------------------->|             |
  92  |             |                    |             |
  93  |             | Stablish SSH       |             |
  94  |             | connection to VM2  |             |
  95  |             | through floating IP|             |
  96  |             +------------------->|             |
  97  |             |                    |             |
  98  |             | SCP ping.sh to VM2 |             |
  99  |             +------------------->|             |
 100  |             |                    |             |
 101  |             | VM2 executes       |             |
 102  |             | ping.sh to VM1     |             |
 103  |             +------------------->|             |
 104  |             |                    |             |
 105  |             |    If ping:        |             |
 106  |             |      exit OK       |             |
 107  |             |    else (timeout): |             |
 108  |             |      exit Failed   |             |
 109  |             |                    |             |
 110  +-------------+                    +-------------+
 111
 112 This test can be considered as an "Hello World" example.
 113 It is the first basic use case which **must** work on any deployment.
 114
 115 vPing_userdata
 116 ^^^^^^^^^^^^^^
 117
 118 This test case is similar to vPing_ssh but without the use of Floating IPs
 119 and the Public/External network to transfer the ping script.
 120 Instead, it uses Nova metadata service to pass it to the instance at booting time.
 121 As vPing_ssh, it checks that 2 instances can talk to
 122 each other on a Private Tenant network::
 123
 124  vPing_userdata test case
 125  +-------------+                    +-------------+
 126  |             |                    |             |
 127  |             | Boot VM1 with IP1  |             |
 128  |             +------------------->|             |
 129  |             |                    |             |
 130  |             | Boot VM2 with      |             |
 131  |             | ping.sh as userdata|             |
 132  |             | with IP1 as $1.    |             |
 133  |             +------------------->|             |
 134  |   Tester    |                    |   System    |
 135  |             | VM2 exeutes ping.sh|    Under    |
 136  |             | (ping IP1)         |     Test    |
 137  |             +------------------->|             |
 138  |             |                    |             |
 139  |             | Monitor nova       |             |
 140  |             |  console-log VM 2  |             |
 141  |             |    If ping:        |             |
 142  |             |      exit OK       |             |
 143  |             |    else (timeout)  |             |
 144  |             |      exit Failed   |             |
 145  |             |                    |             |
 146  +-------------+                    +-------------+
 147
 148 When the second VM boots it will execute the script passed as userdata
 149 automatically. The ping will be detected by periodically capturing the output
 150 in the console-log of the second VM.
 151
 152
 153 Tempest
 154 ^^^^^^^
 155
 156 Tempest `[2]`_ is the reference OpenStack Integration test suite.
 157 It is a set of integration tests to be run against a live OpenStack cluster.
 158 Tempest has suites of tests for:
 159
 160   * OpenStack API validation
 161   * Scenarios
 162   * Other specific tests useful in validating an OpenStack deployment
 163
 164 Functest uses Rally `[3]`_ to run the Tempest suite.
 165 Rally generates automatically the Tempest configuration file **tempest.conf**.
 166 Before running the actual test cases,
 167 Functest creates the needed resources (user, tenant) and
 168 updates the appropriate parameters into the configuration file.
 169
 170 When the Tempest suite is executed, each test duration is measured and the full
 171 console output is stored to a *log* file for further analysis.
 172
 173 The Tempest testcases are distributed accross two
 174 Tiers:
 175
 176   * Smoke Tier - Test Case 'tempest_smoke_serial'
 177   * Openstack Tier - Test case 'tempest_full_parallel'
 178
 179 NOTE: Test case 'tempest_smoke_serial' executes a defined set of tempest smoke
 180 tests with a single thread (i.e. serial mode). Test case 'tempest_full_parallel'
 181 executes all defined Tempest tests using several concurrent threads
 182 (i.e. parallel mode). The number of threads activated corresponds to the number
 183 of available logical CPUs.
 184
 185 The goal of the Tempest test suite is to check the basic functionalities of the
 186 different OpenStack components on an OPNFV fresh installation, using the
 187 corresponding REST API interfaces.
 188
 189
 190 Rally bench test suites
 191 ^^^^^^^^^^^^^^^^^^^^^^^
 192
 193 Rally `[3]`_ is a benchmarking tool that answers the question:
 194
 195 *How does OpenStack work at scale?*
 196
 197 The goal of this test suite is to benchmark all the different OpenStack modules and
 198 get significant figures that could help to define Telco Cloud KPIs.
 199
 200 The OPNFV Rally scenarios are based on the collection of the actual Rally scenarios:
 201
 202  * authenticate
 203  * cinder
 204  * glance
 205  * heat
 206  * keystone
 207  * neutron
 208  * nova
 209  * quotas
 210  * requests
 211
 212 A basic SLA (stop test on errors) has been implemented.
 213
 214 The Rally testcases are distributed accross two Tiers:
 215
 216   * Smoke Tier - Test Case 'rally_sanity'
 217   * Openstack Tier - Test case 'rally_full'
 218
 219 NOTE: Test case 'rally_sanity' executes a limited number of Rally smoke test
 220 cases. Test case 'rally_full' executes the full defined set of Rally tests.
 221
 222
 223 SDN Controllers
 224 ---------------
 225
 226 There are currently 2 available controllers:
 227
 228  * OpenDaylight (ODL)
 229  * ONOS
 230
 231 OpenDaylight
 232 ^^^^^^^^^^^^
 233
 234 The OpenDaylight (ODL) test suite consists of a set of basic tests inherited
 235 from the ODL project using the Robot `[11]`_ framework.
 236 The suite verifies creation and deletion of networks, subnets and ports with
 237 OpenDaylight and Neutron.
 238
 239 The list of tests can be described as follows:
 240
 241  * Restconf.basic: Get the controller modules via Restconf
 242  * Neutron.Networks
 243
 244    * Check OpenStack Networks :: Checking OpenStack Neutron for known networks
 245    * Check OpenDaylight Networks :: Checking OpenDaylight Neutron API
 246    * Create Network :: Create new network in OpenStack
 247    * Check Network :: Check Network created in OpenDaylight
 248    * Neutron.Networks :: Checking Network created in OpenStack are pushed
 249
 250  * Neutron.Subnets
 251
 252    * Check OpenStack Subnets :: Checking OpenStack Neutron for known Subnets
 253    * Check OpenDaylight subnets :: Checking OpenDaylight Neutron API
 254    * Create New subnet :: Create new subnet in OpenStack
 255    * Check New subnet :: Check new subnet created in OpenDaylight
 256    * Neutron.Subnets :: Checking Subnets created in OpenStack are pushed
 257
 258  * Neutron.Ports
 259
 260    * Check OpenStack ports :: Checking OpenStack Neutron for known ports
 261    * Check OpenDaylight ports :: Checking OpenDaylight Neutron API
 262    * Create New Port :: Create new port in OpenStack
 263    * Check New Port :: Check new subnet created in OpenDaylight
 264    * Neutron.Ports :: Checking Port created in OpenStack are pushed
 265
 266  * Delete Ports
 267
 268    * Delete previously created subnet in OpenStack
 269    * Check subnet deleted in OpenDaylight
 270    * Check subnet deleted in OpenStack
 271
 272  * Delete network
 273
 274    * Delete previously created network in OpenStack
 275    * Check network deleted in OpenDaylight
 276    * Check network deleted in OpenStack
 277
 278
 279 ONOS
 280 ^^^^
 281
 282 TestON Framework is used to test the ONOS SDN controller functions.
 283 The test cases deal with L2 and L3 functions.
 284 The ONOS test suite can be run on any ONOS compliant scenario.
 285
 286 The test cases are described as follows:
 287
 288  * onosfunctest: The main executable file contains the initialization of
 289    the docker environment and functions called by FUNCvirNetNB and
 290    FUNCvirNetNBL3
 291
 292  * FUNCvirNetNB
 293
 294    * Create Network: Post Network data and check it in ONOS
 295    * Update Network: Update the Network and compare it in ONOS
 296    * Delete Network: Delete the Network and check if it's NULL in ONOS or
 297      not
 298    * Create Subnet: Post Subnet data and check it in ONOS
 299    * Update Subnet: Update the Subnet and compare it in ONOS
 300    * Delete Subnet: Delete the Subnet and check if it's NULL in ONOS or not
 301    * Create Port: Post Port data and check it in ONOS
 302    * Update Port: Update the Port and compare it in ONOS
 303    * Delete Port: Delete the Port and check if it's NULL in ONOS or not
 304
 305  * FUNCvirNetNBL3
 306
 307    * Create Router: Post data for create Router and check it in ONOS
 308    * Update Router: Update the Router and compare it in ONOS
 309    * Delete Router: Delete the Router data and check it in ONOS
 310    * Create RouterInterface: Post Router Interface data to an existing Router
 311      and check it in ONOS
 312    * Delete RouterInterface: Delete the RouterInterface and check the Router
 313    * Create FloatingIp: Post data for create FloatingIp and check it in ONOS
 314    * Update FloatingIp: Update the FloatingIp and compare it in ONOS
 315    * Delete FloatingIp: Delete the FloatingIp and check that it is 'NULL' in
 316      ONOS
 317    * Create External Gateway: Post data to create an External Gateway for an
 318      existing Router and check it in ONOS
 319    * Update External Gateway: Update the External Gateway and compare the change
 320    * Delete External Gateway: Delete the External Gateway and check that it is
 321      'NULL' in ONOS
 322
 323 Open Contrail
 324 ^^^^^^^^^^^^^
 325 **TODO:**
 326
 327
 328
 329 Features
 330 --------
 331
 332 Doctor
 333 ^^^^^^
 334
 335 **TODO:**
 336
 337
 338
 339 Promise
 340 ^^^^^^^
 341
 342 Promise provides a basic set of test cases as part of the deliverable.
 343
 344 The available 33 test cases can be grouped into 7 test suites:
 345
 346     #. Add a new OpenStack provider into resource pool: Registers
 347        OpenStack into a new resource pool and adds more capacity associated
 348        with this pool.
 349
 350     #. Allocation without reservation: Creates a new server in OpenStack
 351        and adds a new allocation record in Promise shim-layer.
 352
 353     #. Allocation using reservation for immediate use: Creates a resource
 354        reservation record with no start/end time and immediately creates a new
 355        server in OpenStack and add a new allocation record in Promise
 356        shim-layer.
 357
 358     #. Reservation for future use: Creates a resource reservation record
 359        for a future start time, queries, modifies and cancels the newly created
 360        reservation.
 361
 362     #. Capacity planning: Decreases and increases the available capacity
 363        from a provider in the future and queries the available collections and
 364        utilizations.
 365
 366     #. Reservation with conflict: Tries to create reservations for
 367        immediate and future use with conflict.
 368
 369     #. Cleanup test allocations: Destroys all allocations in OpenStack.
 370
 371
 372 bgpvpn
 373 ^^^^^^
 374 Many telecom network functions are relying on layer-3 infrastructure services,
 375 within a VNF between components, or towards existing external networks.
 376 In many cases, these external networks are implemented in MPLS/BGP technology in
 377 existing service provider wide-area-networks (WAN). This proven technology
 378 provides a good mechanism for inter-operation of a NFV Infrastructure (NFVI)
 379 and WAN.
 380
 381 The SDNVPN project defined a 'bgpvpn' test suite.
 382 This 'bgpvpn' test suite deals with 2 Tempest cases dedicated to the test of
 383 the OpenStack 'bgpvpn' API:
 384
 385   * test_create_bgpvpn
 386   * test_create_bgpvpn_as_non_admin_fail
 387
 388 security_scan
 389 ^^^^^^^^^^^^^
 390
 391 **TODO:**
 392
 393
 394
 395 VNF
 396 ---
 397
 398
 399 vIMS
 400 ^^^^
 401 The IP Multimedia Subsystem or IP Multimedia Core Network Subsystem (IMS) is an
 402 architectural framework for delivering IP multimedia services.
 403
 404 vIMS has been integrated in Functest to demonstrate the capability to deploy a
 405 relatively complex NFV scenario on the OPNFV platform. The deployment of a complete
 406 functional VNF allows the test of most of the
 407 essential functions needed for a NFV platform.
 408
 409 The goal of this test suite consists of:
 410
 411  * deploy a VNF orchestrator (Cloudify)
 412  * deploy a Clearwater vIMS (IP Multimedia Subsystem) VNF from this
 413    orchestrator based on a TOSCA blueprint defined in `[5]`_
 414  * run suite of signaling tests on top of this VNF
 415
 416 The Clearwater architecture is described as follows:
 417
 418 .. figure:: ../images/clearwater-architecture.png
 419    :align: center
 420    :alt: vIMS architecture
 421
 422
 423 .. include:: ./runfunctest.rst
 424
 425
 426 Test results
 427 ============
 428
 429 Note that the results are documented per scenario basis. Although most of the test
 430 cases might show the same output, some of them are not supported by
 431 certain scenarios. Please select the appropriate scenario and compare the results
 432 to that referenced in the documentation.
 433
 434
 435 Test Dashboard
 436 ==============
 437
 438 Based on results collected in CI, a test dashboard is dynamically generated.
 439
 440
 441 .. include:: ./troubleshooting.rst
 442
 443
 444 References
 445 ==========
 446
 447 .. _`[1]`: http://artifacts.opnfv.org/functest/docs/configguide/#
 448 .. _`[2]`: http://docs.openstack.org/developer/tempest/overview.html
 449 .. _`[3]`: https://rally.readthedocs.org/en/latest/index.html
 450 .. _`[4]`: http://events.linuxfoundation.org/sites/events/files/slides/Functest%20in%20Depth_0.pdf
 451 .. _`[5]`: https://github.com/Orange-OpenSource/opnfv-cloudify-clearwater/blob/master/openstack-blueprint.yaml
 452 .. _`[9]`: https://git.opnfv.org/cgit/functest/tree/testcases/VIM/OpenStack/CI/libraries/os_defaults.yaml
 453 .. _`[11]`: http://robotframework.org/
 454
 455 OPNFV main site: opnfvmain_.
 456
 457 OPNFV functional test page: opnfvfunctest_.
 458
 459 IRC support chan: #opnfv-testperf
 460
 461 .. _opnfvmain: http://www.opnfv.org
 462 .. _opnfvfunctest: https://wiki.opnfv.org/opnfv_functional_testing
 463 .. _`OpenRC`: http://docs.openstack.org/user-guide/common/cli_set_environment_variables_using_openstack_rc.html
 464 .. _`Rally installation procedure`: https://rally.readthedocs.org/en/latest/tutorial/step_0_installation.html
 465 .. _`config_test.py` : https://git.opnfv.org/cgit/functest/tree/testcases/config_functest.py
 466 .. _`config_functest.yaml` : https://git.opnfv.org/cgit/functest/tree/testcases/config_functest.yaml