docs/testing/user/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 Version history
  12 ===============
  13 +------------+----------+------------------+----------------------------------+
  14 | **Date**   | **Ver.** | **Author**       | **Comment**                      |
  15 |            |          |                  |                                  |
  16 +------------+----------+------------------+----------------------------------+
  17 | 2016-08-17 | 1.0.0    | Juha Haapavirta  | Colorado release                 |
  18 |            |          | Column Gaynor    |                                  |
  19 +------------+----------+------------------+----------------------------------+
  20 | 2017-01-23 | 1.0.1    | Morgan Richomme  | Adaptations for Danube           |
  21 |            |          |                  |                                  |
  22 |            |          |                  |                                  |
  23 +------------+----------+------------------+----------------------------------+
  24
  25
  26 Introduction
  27 ============
  28
  29 The goal of this document is to describe the OPNFV Functest test cases and to
  30 provide a procedure to execute them. In the OPNFV Danube system release,
  31 a Functest CLI utility is introduced for easier execution of test procedures.
  32
  33 **IMPORTANT**: It is assumed here that the Functest Docker container is already
  34 properly deployed and that all instructions described in this guide are to be
  35 performed from *inside* the deployed Functest Docker container.
  36
  37 .. include:: ./introduction.rst
  38
  39 The different test cases are described in the remaining sections of this document.
  40
  41 VIM (Virtualized Infrastructure Manager)
  42 ----------------------------------------
  43
  44 Healthcheck
  45 ^^^^^^^^^^^
  46 In Colorado release a new Tier 'healthcheck' with one testcase 'healthcheck'
  47 was introduced. The healthcheck testcase verifies that some basic IP connectivity
  48 and  essential operations of OpenStack functionality over the command line are
  49 working correctly.
  50
  51 In particular, the following verifications are performed:
  52
  53   * DHCP agent functionality for IP address allocation
  54   * Openstack Authentication management functionality via the Keystone API
  55   * OpenStack Image management functionality via the Glance API
  56   * OpenStack Block Storage management functionality via the Cinder API
  57   * OpenStack Networking management functionality via the Neutron API
  58   * Openstack Compute management functionality via the NOVA API
  59
  60 Self-obviously, successful completion of the 'healthcheck' testcase is a
  61 necessary pre-requisite for the execution of all other test Tiers.
  62
  63
  64 vPing_ssh
  65 ^^^^^^^^^
  66
  67 Given the script **ping.sh**::
  68
  69     #!/bin/sh
  70     while true; do
  71         ping -c 1 $1 2>&1 >/dev/null
  72         RES=$?
  73         if [ "Z$RES" = "Z0" ] ; then
  74             echo 'vPing OK'
  75             break
  76         else
  77             echo 'vPing KO'
  78         fi
  79     sleep 1
  80     done
  81
  82
  83 The goal of this test is to establish an SSH connection using a floating IP
  84 on the Public/External network and verify that 2 instances can talk over a Private
  85 Tenant network::
  86
  87  vPing_ssh test case
  88  +-------------+                    +-------------+
  89  |             |                    |             |
  90  |             | Boot VM1 with IP1  |             |
  91  |             +------------------->|             |
  92  |   Tester    |                    |   System    |
  93  |             | Boot VM2           |    Under    |
  94  |             +------------------->|     Test    |
  95  |             |                    |             |
  96  |             | Create floating IP |             |
  97  |             +------------------->|             |
  98  |             |                    |             |
  99  |             | Assign floating IP |             |
 100  |             | to VM2             |             |
 101  |             +------------------->|             |
 102  |             |                    |             |
 103  |             | Establish SSH      |             |
 104  |             | connection to VM2  |             |
 105  |             | through floating IP|             |
 106  |             +------------------->|             |
 107  |             |                    |             |
 108  |             | SCP ping.sh to VM2 |             |
 109  |             +------------------->|             |
 110  |             |                    |             |
 111  |             | VM2 executes       |             |
 112  |             | ping.sh to VM1     |             |
 113  |             +------------------->|             |
 114  |             |                    |             |
 115  |             |    If ping:        |             |
 116  |             |      exit OK       |             |
 117  |             |    else (timeout): |             |
 118  |             |      exit Failed   |             |
 119  |             |                    |             |
 120  +-------------+                    +-------------+
 121
 122 This test can be considered as an "Hello World" example.
 123 It is the first basic use case which **must** work on any deployment.
 124
 125 vPing_userdata
 126 ^^^^^^^^^^^^^^
 127
 128 This test case is similar to vPing_ssh but without the use of Floating IPs
 129 and the Public/External network to transfer the ping script.
 130 Instead, it uses Nova metadata service to pass it to the instance at booting time.
 131 As vPing_ssh, it checks that 2 instances can talk to
 132 each other on a Private Tenant network::
 133
 134  vPing_userdata test case
 135  +-------------+                    +-------------+
 136  |             |                    |             |
 137  |             | Boot VM1 with IP1  |             |
 138  |             +------------------->|             |
 139  |             |                    |             |
 140  |             | Boot VM2 with      |             |
 141  |             | ping.sh as userdata|             |
 142  |             | with IP1 as $1.    |             |
 143  |             +------------------->|             |
 144  |   Tester    |                    |   System    |
 145  |             | VM2 exeutes ping.sh|    Under    |
 146  |             | (ping IP1)         |     Test    |
 147  |             +------------------->|             |
 148  |             |                    |             |
 149  |             | Monitor nova       |             |
 150  |             |  console-log VM 2  |             |
 151  |             |    If ping:        |             |
 152  |             |      exit OK       |             |
 153  |             |    else (timeout)  |             |
 154  |             |      exit Failed   |             |
 155  |             |                    |             |
 156  +-------------+                    +-------------+
 157
 158 When the second VM boots it will execute the script passed as userdata
 159 automatically. The ping will be detected by periodically capturing the output
 160 in the console-log of the second VM.
 161
 162
 163 Tempest
 164 ^^^^^^^
 165
 166 Tempest `[2]`_ is the reference OpenStack Integration test suite.
 167 It is a set of integration tests to be run against a live OpenStack cluster.
 168 Tempest has suites of tests for:
 169
 170   * OpenStack API validation
 171   * Scenarios
 172   * Other specific tests useful in validating an OpenStack deployment
 173
 174 Functest uses Rally `[3]`_ to run the Tempest suite.
 175 Rally generates automatically the Tempest configuration file **tempest.conf**.
 176 Before running the actual test cases,
 177 Functest creates the needed resources (user, tenant) and
 178 updates the appropriate parameters into the configuration file.
 179
 180 When the Tempest suite is executed, each test duration is measured and the full
 181 console output is stored to a *log* file for further analysis.
 182
 183 The Tempest testcases are distributed accross two
 184 Tiers:
 185
 186   * Smoke Tier - Test Case 'tempest_smoke_serial'
 187   * Components Tier - Test case 'tempest_full_parallel'
 188
 189 NOTE: Test case 'tempest_smoke_serial' executes a defined set of tempest smoke
 190 tests with a single thread (i.e. serial mode). Test case 'tempest_full_parallel'
 191 executes all defined Tempest tests using several concurrent threads
 192 (i.e. parallel mode). The number of threads activated corresponds to the number
 193 of available logical CPUs.
 194
 195 The goal of the Tempest test suite is to check the basic functionalities of the
 196 different OpenStack components on an OPNFV fresh installation, using the
 197 corresponding REST API interfaces.
 198
 199
 200 Rally bench test suites
 201 ^^^^^^^^^^^^^^^^^^^^^^^
 202
 203 Rally `[3]`_ is a benchmarking tool that answers the question:
 204
 205 *How does OpenStack work at scale?*
 206
 207 The goal of this test suite is to benchmark all the different OpenStack modules and
 208 get significant figures that could help to define Telco Cloud KPIs.
 209
 210 The OPNFV Rally scenarios are based on the collection of the actual Rally scenarios:
 211
 212  * authenticate
 213  * cinder
 214  * glance
 215  * heat
 216  * keystone
 217  * neutron
 218  * nova
 219  * quotas
 220  * requests
 221
 222 A basic SLA (stop test on errors) has been implemented.
 223
 224 The Rally testcases are distributed accross two Tiers:
 225
 226   * Smoke Tier - Test Case 'rally_sanity'
 227   * Components Tier - Test case 'rally_full'
 228
 229 NOTE: Test case 'rally_sanity' executes a limited number of Rally smoke test
 230 cases. Test case 'rally_full' executes the full defined set of Rally tests.
 231
 232 SNAPS
 233 -----
 234
 235 SNAPS stands for "SNA/NFV Application development Platform and Stack".
 236 This project seeks to develop baseline OpenStack NFV installations. It has been
 237 developed by Steven Pisarski and provided an object oriented library to perform
 238 functional and performance tests. It has been declined in several test suites in
 239 Functest, 2 are part of healthcheck tier, one belongs to smoke tier.
 240
 241 connection check
 242 ^^^^^^^^^^^^^^^^
 243 Connection_check consists in 9 test cases (test duration < 5s) checking the
 244 connectivity with Glance, Keystone, Neutron, Nova and the external network.
 245
 246 api_check
 247 ^^^^^^^^^
 248 This test case verifies the retrieval of OpenStack clients: Keystone, Glance,
 249 Neutron and Nova and may perform some simple queries. When the config value of
 250 snaps.use_keystone is True, functest must have access to the cloud's private
 251 network.
 252 This suite consists in 49 tests (test duration< 2 minutes)
 253
 254 snaps_smoke
 255 ^^^^^^^^^^^
 256 This test case contains tests that setup and destroy environments with VMs with
 257 and without Floating IPs with a newly created user and project. Set the config
 258 value snaps.use_floating_ips (True|False) to toggle this functionality. When
 259 the config value of snaps.use_keystone is True, functest must have access
 260 the cloud's private network.
 261 This suite consists in 38 tests (test duration < 10 minutes)
 262
 263 More information on SNAPS can be found in  `[13]`_
 264
 265
 266 SDN Controllers
 267 ---------------
 268
 269 There are currently 2 available controllers:
 270
 271  * OpenDaylight (ODL)
 272  * ONOS
 273
 274 OpenDaylight
 275 ^^^^^^^^^^^^
 276
 277 The OpenDaylight (ODL) test suite consists of a set of basic tests inherited
 278 from the ODL project using the Robot `[11]`_ framework.
 279 The suite verifies creation and deletion of networks, subnets and ports with
 280 OpenDaylight and Neutron.
 281
 282 The list of tests can be described as follows:
 283
 284  * Basic Restconf test cases
 285    * Connect to Restconf URL
 286    * Check the HTTP code status
 287
 288  * Neutron Reachability test cases
 289    * Get the complete list of neutron resources (networks, subnets, ports)
 290
 291  * Neutron Network test cases
 292    * Check OpenStack networks
 293    * Check OpenDaylight networks
 294    * Create a new network via OpenStack and check the HTTP status code returned by Neutron
 295    * Check that the network has also been successfully created in OpenDaylight
 296
 297  * Neutron Subnet test cases
 298    * Check OpenStack subnets
 299    * Check OpenDaylight subnets
 300    * Create a new subnet via OpenStack and check the HTTP status code returned by Neutron
 301    * Check that the subnet has also been successfully created in OpenDaylight
 302
 303  * Neutron Port test cases
 304    * Check OpenStack Neutron for known ports
 305    * Check OpenDaylight ports
 306    * Create a new port via OpenStack and check the HTTP status code returned by Neutron
 307    * Check that the new port has also been successfully created in OpenDaylight
 308
 309  * Delete operations
 310    * Delete the port previously created via OpenStack
 311    * Check that the port has been also succesfully deleted in OpenDaylight
 312    * Delete previously subnet created via OpenStack
 313    * Check that the subnet has also been successfully deleted in OpenDaylight
 314    * Delete the network created via OpenStack
 315    * Check that the network has also been succesfully deleted in OpenDaylight
 316
 317 Note: the checks in OpenDaylight are based on the returned HTTP status
 318 code returned by OpenDaylight.
 319
 320
 321 ONOS
 322 ^^^^
 323
 324 TestON Framework is used to test the ONOS SDN controller functions.
 325 The test cases deal with L2 and L3 functions.
 326 The ONOS test suite can be run on any ONOS compliant scenario.
 327
 328 The test cases are described as follows:
 329
 330  * onosfunctest: The main executable file contains the initialization of
 331    the docker environment and functions called by FUNCvirNetNB and
 332    FUNCvirNetNBL3
 333
 334  * FUNCvirNetNB
 335
 336    * Create Network: Post Network data and check it in ONOS
 337    * Update Network: Update the Network and compare it in ONOS
 338    * Delete Network: Delete the Network and check if it's NULL in ONOS or
 339      not
 340    * Create Subnet: Post Subnet data and check it in ONOS
 341    * Update Subnet: Update the Subnet and compare it in ONOS
 342    * Delete Subnet: Delete the Subnet and check if it's NULL in ONOS or not
 343    * Create Port: Post Port data and check it in ONOS
 344    * Update Port: Update the Port and compare it in ONOS
 345    * Delete Port: Delete the Port and check if it's NULL in ONOS or not
 346
 347  * FUNCvirNetNBL3
 348
 349    * Create Router: Post data for create Router and check it in ONOS
 350    * Update Router: Update the Router and compare it in ONOS
 351    * Delete Router: Delete the Router data and check it in ONOS
 352    * Create RouterInterface: Post Router Interface data to an existing Router
 353      and check it in ONOS
 354    * Delete RouterInterface: Delete the RouterInterface and check the Router
 355    * Create FloatingIp: Post data for create FloatingIp and check it in ONOS
 356    * Update FloatingIp: Update the FloatingIp and compare it in ONOS
 357    * Delete FloatingIp: Delete the FloatingIp and check that it is 'NULL' in
 358      ONOS
 359    * Create External Gateway: Post data to create an External Gateway for an
 360      existing Router and check it in ONOS
 361    * Update External Gateway: Update the External Gateway and compare the change
 362    * Delete External Gateway: Delete the External Gateway and check that it is
 363      'NULL' in ONOS
 364
 365
 366 Features
 367 --------
 368
 369 Please refer to the dedicated feature user guides for details:
 370
 371  * bgpvpn: http://artifacts.opnfv.org/sdnvpn/danube/docs/userguide/index.html
 372  * copper: http://artifacts.opnfv.org/copper/danube/docs/userguide/index.html
 373  * doctor: http://artifacts.opnfv.org/doctor/danube/userguide/index.html
 374  * domino: http://artifacts.opnfv.org/domino/docs/userguide-single/index.html
 375  * multisites: http://artifacts.opnfv.org/multisite/docs/userguide/index.html
 376  * onos-sfc: http://artifacts.opnfv.org/onosfw/danube/userguide/index.html
 377  * odl-sfc: http://artifacts.opnfv.org/sfc/danube/userguide/index.html
 378  * promise: http://artifacts.opnfv.org/danube/colorado/docs/userguide/index.html
 379  * security_scan: http://artifacts.opnfv.org/security_scan/colorado/docs/userguide/index.html
 380  * TODO
 381
 382 security_scan
 383 ^^^^^^^^^^^^^
 384
 385 Security Scanning, is a project to insure security compliance and vulnerability
 386 checks, as part of an automated CI / CD platform delivery process.
 387
 388 The project makes use of the existing SCAP format `[6]`_ to perform deep
 389 scanning of NFVI nodes, to insure they are hardened and free of known CVE
 390 reported vulnerabilities.
 391
 392 The SCAP content itself, is then consumed and run using an upstream opensource tool
 393 known as OpenSCAP `[7]`_.
 394
 395 The OPNFV Security Group have developed the code that will called by the OPNFV Jenkins
 396 build platform, to perform a complete scan. Resulting reports are then copied to the
 397 OPNFV functest dashboard.
 398
 399 The current work flow is as follows:
 400
 401   * Jenkins Build Initiated
 402   * security_scan.py script is called, and a config file is passed to the script as
 403     an argument.
 404   * The IP addresses of each NFVi node (compute / control) are gathered
 405   * A scan profile is matched to the node type.
 406   * The OpenSCAP application is remotely installed onto each target node gathered
 407     on step 3, using upstream packaging (rpm and .deb).
 408   * A scan is made against each node gathered within step 3.
 409   * HTML Reports are downloaded for rendering on a dashboard.
 410   * If the config file value 'clean' is set to 'True' then the application installed in
 411     step 5 is removed, and all reports created at step 6 are deleted.
 412
 413 Security scan is supported by Apex, TODO....
 414
 415
 416
 417 VNF
 418 ---
 419
 420
 421 vIMS
 422 ^^^^
 423 The IP Multimedia Subsystem or IP Multimedia Core Network Subsystem (IMS) is an
 424 architectural framework for delivering IP multimedia services.
 425
 426 vIMS has been integrated in Functest to demonstrate the capability to deploy a
 427 relatively complex NFV scenario on the OPNFV platform. The deployment of a complete
 428 functional VNF allows the test of most of the essential functions needed for a
 429 NFV platform.
 430
 431 The goal of this test suite consists of:
 432
 433  * deploy a VNF orchestrator (Cloudify)
 434  * deploy a Clearwater vIMS (IP Multimedia Subsystem) VNF from this
 435    orchestrator based on a TOSCA blueprint defined in `[5]`_
 436  * run suite of signaling tests on top of this VNF
 437
 438 The Clearwater architecture is described as follows:
 439
 440 .. figure:: ../images/clearwater-architecture.png
 441    :align: center
 442    :alt: vIMS architecture
 443
 444
 445 parser
 446 ^^^^^^
 447
 448 See parser user guide for details: `[12]`_
 449
 450
 451 .. include:: ./runfunctest.rst
 452
 453
 454 Test results
 455 ============
 456
 457 Manual testing
 458 --------------
 459
 460 In manual mode test results are displayed in the console and result files
 461 are put in /home/opnfv/functest/results.
 462
 463 Automated testing
 464 --------------
 465
 466 In automated mode, test results are displayed in jenkins logs, a summary is provided
 467 at the end of the job and can be described as follow::
 468
 469  +==================================================================================================================================================+
 470  |                                                                FUNCTEST REPORT                                                                   |
 471  +==================================================================================================================================================+
 472  |                                                                                                                                                  |
 473  |  Deployment description:                                                                                                                         |
 474  |    INSTALLER: fuel                                                                                                                               |
 475  |    SCENARIO:  os-odl_l2-nofeature-ha                                                                                                             |
 476  |    BUILD TAG: jenkins-functest-fuel-baremetal-daily-master-324                                                                                   |
 477  |    CI LOOP:   daily                                                                                                                              |
 478  |                                                                                                                                                  |
 479  +=========================+===============+============+===============+===========================================================================+
 480  | TEST CASE               | TIER          | DURATION   | RESULT        | URL                                                                       |
 481  +=========================+===============+============+===============+===========================================================================+
 482  | healthcheck             | healthcheck   | 03:07      | PASS          |                                                                           |
 483  +-------------------------+---------------+------------+---------------+---------------------------------------------------------------------------+
 484  | vping_ssh               | smoke         | 00:56      | PASS          | http://testresults.opnfv.org/test/api/v1/results/57ac13d79377c54b278bd4c1 |
 485  +-------------------------+---------------+------------+---------------+---------------------------------------------------------------------------+
 486  | vping_userdata          | smoke         | 00:41      | PASS          | http://testresults.opnfv.org/test/api/v1/results/57ac14019377c54b278bd4c2 |
 487  +-------------------------+---------------+------------+---------------+---------------------------------------------------------------------------+
 488  | tempest_smoke_serial    | smoke         | 16:05      | FAIL          | http://testresults.opnfv.org/test/api/v1/results/57ac17ca9377c54b278bd4c3 |
 489  +-------------------------+---------------+------------+---------------+---------------------------------------------------------------------------+
 490  | rally_sanity            | smoke         | 12:19      | PASS          | http://testresults.opnfv.org/test/api/v1/results/57ac1aad9377c54b278bd4cd |
 491  +-------------------------+---------------+------------+---------------+---------------------------------------------------------------------------+
 492  | odl                     | sdn_suites    | 00:24      | PASS          | http://testresults.opnfv.org/test/api/v1/results/57ac1ad09377c54b278bd4ce |
 493  +-------------------------+---------------+------------+---------------+---------------------------------------------------------------------------+
 494  | promise                 | features      | 00:41      | PASS          | http://testresults.opnfv.org/test/api/v1/results/57ac1ae59377c54b278bd4cf |
 495  +-------------------------+---------------+------------+---------------+---------------------------------------------------------------------------+
 496
 497 Results are automatically pushed to the test results database, some additional
 498 result files are pushed to OPNFV artifact web sites.
 499
 500 Based on the results stored in the result database, a `Functest reporting`_
 501 portal is also automatically updated. This portal provides information on:
 502
 503  * The overall status per scenario and per installer
 504  * Tempest: Tempest test case including reported errors per scenario and installer
 505  * vIMS: vIMS details per scenario and installer
 506
 507 .. figure:: ../images/functest-reporting-status.png
 508    :align: center
 509    :alt: Functest reporting portal Fuel status page
 510
 511
 512 Test Dashboard
 513 ==============
 514
 515 Based on results collected in CI, a test dashboard is dynamically generated.
 516
 517
 518 .. include:: ./troubleshooting.rst
 519
 520
 521 References
 522 ==========
 523
 524 .. _`[1]`: http://artifacts.opnfv.org/functest/colorado/docs/configguide/#
 525 .. _`[2]`: http://docs.openstack.org/developer/tempest/overview.html
 526 .. _`[3]`: https://rally.readthedocs.org/en/latest/index.html
 527 .. _`[4]`: http://events.linuxfoundation.org/sites/events/files/slides/Functest%20in%20Depth_0.pdf
 528 .. _`[5]`: https://github.com/Orange-OpenSource/opnfv-cloudify-clearwater/blob/master/openstack-blueprint.yaml
 529 .. _`[6]`: https://scap.nist.gov/
 530 .. _`[7]`: https://github.com/OpenSCAP/openscap
 531 .. _`[9]`: https://git.opnfv.org/cgit/functest/tree/testcases/VIM/OpenStack/CI/libraries/os_defaults.yaml
 532 .. _`[11]`: http://robotframework.org/
 533 .. _`[12]`: http://artifacts.opnfv.org/parser/colorado/docs/userguide/index.html
 534 .. _`[13]`: TODO URL doc SNAPS
 535
 536 OPNFV main site: opnfvmain_.
 537
 538 OPNFV functional test page: opnfvfunctest_.
 539
 540 IRC support chan: #opnfv-testperf
 541
 542 .. _opnfvmain: http://www.opnfv.org
 543 .. _opnfvfunctest: https://wiki.opnfv.org/opnfv_functional_testing
 544 .. _`OpenRC`: http://docs.openstack.org/user-guide/common/cli_set_environment_variables_using_openstack_rc.html
 545 .. _`Rally installation procedure`: https://rally.readthedocs.org/en/latest/tutorial/step_0_installation.html
 546 .. _`config_test.py` : https://git.opnfv.org/cgit/functest/tree/testcases/config_functest.py
 547 .. _`config_functest.yaml` : https://git.opnfv.org/cgit/functest/tree/testcases/config_functest.yaml
 548 .. _`Functest reporting`: http://testresults.opnfv.org/reporting/functest/release/colorado/index-status-fuel.html