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 An 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  |             | Establish 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  * Basic Restconf test cases
 242    * Connect to Restconf URL
 243    * Check the HTTP code status
 244
 245  * Neutron Reachability test cases
 246    * Get the complete list of neutron resources (networks, subnets, ports)
 247
 248  * Neutron Network test cases
 249    * Check OpenStack networks
 250    * Check OpenDaylight networks
 251    * Create a new network via OpenStack and check the HTTP status code returned by Neutron
 252    * Check that the network has also been successfully created in OpenDaylight
 253
 254  * Neutron Subnet test cases
 255    * Check OpenStack subnets
 256    * Check OpenDaylight subnets
 257    * Create a new subnet via OpenStack and check the HTTP status code returned by Neutron
 258    * Check that the subnet has also been successfully created in OpenDaylight
 259
 260  * Neutron Port test cases
 261    * Check OpenStack Neutron for known ports
 262    * Check OpenDaylight ports
 263    * Create a new port via OpenStack and check the HTTP status code returned by Neutron
 264    * Check that the new port has also been successfully created in OpenDaylight
 265
 266  * Delete operations
 267    * Delete the port previously created via OpenStack
 268    * Check that the port has been also succesfully deleted in OpenDaylight
 269    * Delete previously subnet created via OpenStack
 270    * Check that the subnet has also been successfully deleted in OpenDaylight
 271    * Delete the network created via OpenStack
 272    * Check that the network has also been succesfully deleted in OpenDaylight
 273
 274 Note: the checks in OpenDaylight are based on the returned HTTP status
 275 code returned by OpenDaylight.
 276
 277
 278 ONOS
 279 ^^^^
 280
 281 TestON Framework is used to test the ONOS SDN controller functions.
 282 The test cases deal with L2 and L3 functions.
 283 The ONOS test suite can be run on any ONOS compliant scenario.
 284
 285 The test cases are described as follows:
 286
 287  * onosfunctest: The main executable file contains the initialization of
 288    the docker environment and functions called by FUNCvirNetNB and
 289    FUNCvirNetNBL3
 290
 291  * FUNCvirNetNB
 292
 293    * Create Network: Post Network data and check it in ONOS
 294    * Update Network: Update the Network and compare it in ONOS
 295    * Delete Network: Delete the Network and check if it's NULL in ONOS or
 296      not
 297    * Create Subnet: Post Subnet data and check it in ONOS
 298    * Update Subnet: Update the Subnet and compare it in ONOS
 299    * Delete Subnet: Delete the Subnet and check if it's NULL in ONOS or not
 300    * Create Port: Post Port data and check it in ONOS
 301    * Update Port: Update the Port and compare it in ONOS
 302    * Delete Port: Delete the Port and check if it's NULL in ONOS or not
 303
 304  * FUNCvirNetNBL3
 305
 306    * Create Router: Post data for create Router and check it in ONOS
 307    * Update Router: Update the Router and compare it in ONOS
 308    * Delete Router: Delete the Router data and check it in ONOS
 309    * Create RouterInterface: Post Router Interface data to an existing Router
 310      and check it in ONOS
 311    * Delete RouterInterface: Delete the RouterInterface and check the Router
 312    * Create FloatingIp: Post data for create FloatingIp and check it in ONOS
 313    * Update FloatingIp: Update the FloatingIp and compare it in ONOS
 314    * Delete FloatingIp: Delete the FloatingIp and check that it is 'NULL' in
 315      ONOS
 316    * Create External Gateway: Post data to create an External Gateway for an
 317      existing Router and check it in ONOS
 318    * Update External Gateway: Update the External Gateway and compare the change
 319    * Delete External Gateway: Delete the External Gateway and check that it is
 320      'NULL' in ONOS
 321
 322
 323 Features
 324 --------
 325
 326 Most of the features have been developped by feature projects.
 327 Security_scan has been initiated in Functest repository but should soon
 328 be declared in its own repository as well.
 329
 330 Please refer to the dedicated feature user guides for details:
 331
 332  * bgpvpn: http://artifacts.opnfv.org/sdnvpn/colorado/docs/userguide/index.html
 333  * copper: http://artifacts.opnfv.org/copper/colorado/docs/userguide/index.html
 334  * doctor: http://artifacts.opnfv.org/doctor/colorado/userguide/index.html
 335  * domino: http://artifacts.opnfv.org/domino/docs/userguide-single/index.html
 336  * moon: http://artifacts.opnfv.org/moon/docs/userguide/index.html
 337  * multisites: http://artifacts.opnfv.org/multisite/docs/userguide/index.html
 338  * onos-sfc: http://artifacts.opnfv.org/onosfw/colorado/userguide/index.html
 339  * odl-sfc: http://artifacts.opnfv.org/sfc/colorado/userguide/index.html
 340  * promise: http://artifacts.opnfv.org/promise/colorado/docs/userguide/index.html
 341
 342 security_scan
 343 ^^^^^^^^^^^^^
 344
 345 Security Scanning, is a project to insure security compliance and vulnerability
 346 checks, as part of an automated CI / CD platform delivery process.
 347
 348 The project makes use of the existing SCAP format[6] to perform deep scanning of
 349 NFVi nodes, to insure they are hardened and free of known CVE reported vulnerabilities.
 350
 351 The SCAP content itself, is then consumed and run using an upstream opensource tool
 352 known as OpenSCAP[7].
 353
 354 The OPNFV Security Group have developed the code that will called by the OPNFV Jenkins
 355 build platform, to perform a complete scan. Resulting reports are then copied to the
 356 OPNFV functest dashboard.
 357
 358 The current work flow is as follows:
 359
 360   * Jenkins Build Initiated
 361   * security_scan.py script is called, and a config file is passed to the script as
 362     an argument.
 363   * The IP addresses of each NFVi node (compute / control) are gathered
 364   * A scan profile is matched to the node type.
 365   * The OpenSCAP application is remotely installed onto each target node gathered
 366     on step 3, using upstream packaging (rpm and .deb).
 367   * A scan is made against each node gathered within step 3.
 368   * HTML Reports are downloaded for rendering on a dashboard.
 369   * If the config file value 'clean' is set to 'True' then the application installed in
 370     step 5 is removed, and all reports created at step 6 are deleted.
 371
 372 At present, only the Apex installer is supported, with support for other installers due
 373 within D-release.
 374
 375
 376
 377 VNF
 378 ---
 379
 380
 381 vIMS
 382 ^^^^
 383 The IP Multimedia Subsystem or IP Multimedia Core Network Subsystem (IMS) is an
 384 architectural framework for delivering IP multimedia services.
 385
 386 vIMS has been integrated in Functest to demonstrate the capability to deploy a
 387 relatively complex NFV scenario on the OPNFV platform. The deployment of a complete
 388 functional VNF allows the test of most of the
 389 essential functions needed for a NFV platform.
 390
 391 The goal of this test suite consists of:
 392
 393  * deploy a VNF orchestrator (Cloudify)
 394  * deploy a Clearwater vIMS (IP Multimedia Subsystem) VNF from this
 395    orchestrator based on a TOSCA blueprint defined in `[5]`_
 396  * run suite of signaling tests on top of this VNF
 397
 398 The Clearwater architecture is described as follows:
 399
 400 .. figure:: ../images/clearwater-architecture.png
 401    :align: center
 402    :alt: vIMS architecture
 403
 404
 405 parser
 406 ^^^^^^
 407
 408 See parser user guide for details: `[12]`_
 409
 410
 411 .. include:: ./runfunctest.rst
 412
 413
 414 Test results
 415 ============
 416
 417 Manual testing
 418 --------------
 419
 420 In manual mode test results are displayed in the console and result files
 421 are put in /home/opnfv/functest/results.
 422
 423 Automated testing
 424 --------------
 425
 426 In automated mode, test results are displayed in jenkins logs, a summary is provided
 427 at the end of the job and can be described as follow::
 428
 429  +==================================================================================================================================================+
 430  |                                                                FUNCTEST REPORT                                                                   |
 431  +==================================================================================================================================================+
 432  |                                                                                                                                                  |
 433  |  Deployment description:                                                                                                                         |
 434  |    INSTALLER: fuel                                                                                                                               |
 435  |    SCENARIO:  os-odl_l2-nofeature-ha                                                                                                             |
 436  |    BUILD TAG: jenkins-functest-fuel-baremetal-daily-master-324                                                                                   |
 437  |    CI LOOP:   daily                                                                                                                              |
 438  |                                                                                                                                                  |
 439  +=========================+===============+============+===============+===========================================================================+
 440  | TEST CASE               | TIER          | DURATION   | RESULT        | URL                                                                       |
 441  +=========================+===============+============+===============+===========================================================================+
 442  | healthcheck             | healthcheck   | 03:07      | PASS          |                                                                           |
 443  +-------------------------+---------------+------------+---------------+---------------------------------------------------------------------------+
 444  | vping_ssh               | smoke         | 00:56      | PASS          | http://testresults.opnfv.org/test/api/v1/results/57ac13d79377c54b278bd4c1 |
 445  +-------------------------+---------------+------------+---------------+---------------------------------------------------------------------------+
 446  | vping_userdata          | smoke         | 00:41      | PASS          | http://testresults.opnfv.org/test/api/v1/results/57ac14019377c54b278bd4c2 |
 447  +-------------------------+---------------+------------+---------------+---------------------------------------------------------------------------+
 448  | tempest_smoke_serial    | smoke         | 16:05      | FAIL          | http://testresults.opnfv.org/test/api/v1/results/57ac17ca9377c54b278bd4c3 |
 449  +-------------------------+---------------+------------+---------------+---------------------------------------------------------------------------+
 450  | rally_sanity            | smoke         | 12:19      | PASS          | http://testresults.opnfv.org/test/api/v1/results/57ac1aad9377c54b278bd4cd |
 451  +-------------------------+---------------+------------+---------------+---------------------------------------------------------------------------+
 452  | odl                     | sdn_suites    | 00:24      | PASS          | http://testresults.opnfv.org/test/api/v1/results/57ac1ad09377c54b278bd4ce |
 453  +-------------------------+---------------+------------+---------------+---------------------------------------------------------------------------+
 454  | promise                 | features      | 00:41      | PASS          | http://testresults.opnfv.org/test/api/v1/results/57ac1ae59377c54b278bd4cf |
 455  +-------------------------+---------------+------------+---------------+---------------------------------------------------------------------------+
 456
 457 Results are automatically pushed to the test results database, some additional
 458 result files are pushed to OPNFV artifact web sites.
 459
 460 Based on the results stored in the result database, a `Functest reporting`_
 461 portal is also automatically updated. This portal provides information on:
 462
 463  * The overall status per scenario and per installer
 464  * Tempest: Tempest test case including reported errors per scenario and installer
 465  * vIMS: vIMS details per scenario and installer
 466
 467 .. figure:: ../images/functest-reporting-status.png
 468    :align: center
 469    :alt: Functest reporting portal Fuel status page
 470
 471
 472 Test Dashboard
 473 ==============
 474
 475 Based on results collected in CI, a test dashboard is dynamically generated.
 476
 477
 478 .. include:: ./troubleshooting.rst
 479
 480
 481 References
 482 ==========
 483
 484 .. _`[1]`: http://artifacts.opnfv.org/functest/colorado/docs/configguide/#
 485 .. _`[2]`: http://docs.openstack.org/developer/tempest/overview.html
 486 .. _`[3]`: https://rally.readthedocs.org/en/latest/index.html
 487 .. _`[4]`: http://events.linuxfoundation.org/sites/events/files/slides/Functest%20in%20Depth_0.pdf
 488 .. _`[5]`: https://github.com/Orange-OpenSource/opnfv-cloudify-clearwater/blob/master/openstack-blueprint.yaml
 489 .. _`[6]`: https://scap.nist.gov/
 490 .. _`[7]`: https://github.com/OpenSCAP/openscap
 491 .. _`[9]`: https://git.opnfv.org/cgit/functest/tree/testcases/VIM/OpenStack/CI/libraries/os_defaults.yaml
 492 .. _`[11]`: http://robotframework.org/
 493 .. _`[12]`: http://artifacts.opnfv.org/parser/colorado/docs/userguide/index.html
 494
 495 OPNFV main site: opnfvmain_.
 496
 497 OPNFV functional test page: opnfvfunctest_.
 498
 499 IRC support chan: #opnfv-testperf
 500
 501 .. _opnfvmain: http://www.opnfv.org
 502 .. _opnfvfunctest: https://wiki.opnfv.org/opnfv_functional_testing
 503 .. _`OpenRC`: http://docs.openstack.org/user-guide/common/cli_set_environment_variables_using_openstack_rc.html
 504 .. _`Rally installation procedure`: https://rally.readthedocs.org/en/latest/tutorial/step_0_installation.html
 505 .. _`config_test.py` : https://git.opnfv.org/cgit/functest/tree/testcases/config_functest.py
 506 .. _`config_functest.yaml` : https://git.opnfv.org/cgit/functest/tree/testcases/config_functest.yaml
 507 .. _`Functest reporting`: http://testresults.opnfv.org/reporting/functest/release/colorado/index-status-fuel.html