diff options
Diffstat (limited to 'docs')
29 files changed, 1314 insertions, 612 deletions
diff --git a/docs/release/release-notes/release-notes.rst b/docs/release/release-notes/release-notes.rst index 4b3f12bcf..914daa3a4 100644 --- a/docs/release/release-notes/release-notes.rst +++ b/docs/release/release-notes/release-notes.rst @@ -33,6 +33,9 @@ Version History | November 9, 2018 | 7.0.0 | Yardstick for Gambia release | | | | | +-------------------+-----------+---------------------------------+ +| December 14, 2018 | 7.1.0 | Yardstick for Gambia release | +| | | | ++-------------------+-----------+---------------------------------+ Important Notes @@ -111,19 +114,19 @@ Release Data | **Project** | Yardstick | | | | +--------------------------------+-----------------------+ -| **Repo/tag** | yardstick/opnfv-7.0.0 | +| **Repo/tag** | yardstick/opnfv-7.1.0 | | | | +--------------------------------+-----------------------+ -| **Yardstick Docker image tag** | opnfv-7.0.0 | +| **Yardstick Docker image tag** | opnfv-7.1.0 | | | | +--------------------------------+-----------------------+ -| **Release designation** | Gambia 7.0 | +| **Release designation** | Gambia 7.1 | | | | +--------------------------------+-----------------------+ -| **Release date** | November 9, 2018 | +| **Release date** | December 14, 2018 | | | | +--------------------------------+-----------------------+ -| **Purpose of the delivery** | OPNFV Gambia 7.0.0 | +| **Purpose of the delivery** | OPNFV Gambia 7.1.0 | | | | +--------------------------------+-----------------------+ @@ -269,7 +272,7 @@ List of Scenarios New Test cases -------------- -.. note:: Yardstick Gambia 7.0.0 adds no new test cases. +.. note:: Yardstick Gambia 7.1.0 adds no new test cases. * Generic NFVI test cases @@ -326,7 +329,7 @@ Feature additions Scenario Matrix =============== -For Gambia 7.0.0, Yardstick was tested on the following scenarios: +For Gambia 7.1.0, Yardstick was tested on the following scenarios: +-------------------------+------+---------+----------+------+ | Scenario | Apex | Compass | Fuel-arm | Fuel | @@ -370,58 +373,35 @@ Known Issues/Faults Corrected Faults ---------------- -Gambia 7.0.0: +Gambia 7.1.0: +--------------------+--------------------------------------------------------------------------+ | **JIRA REFERENCE** | **DESCRIPTION** | +====================+==========================================================================+ -| YARDSTICK-1137 | Fix CLI argument handling in nsb_setup.sh | -+--------------------+--------------------------------------------------------------------------+ -| YARDSTICK-1220 | Get stats for multiple port simultaneously | -+--------------------+--------------------------------------------------------------------------+ -| YARDSTICK-1260 | Added missing functionality to start VM and access it using SSH keys | -| | in Standalone contexts. | -+--------------------+--------------------------------------------------------------------------+ -| YARDSTICK-1298 | Allows for in-line overriding/modification of traffic profile variables | -| | from the testcase file. | +| YARDSTICK-1241 | Update NSB PROX devguide. | +--------------------+--------------------------------------------------------------------------+ -| YARDSTICK-1368 | Updated existing test cases in Yardstick to minimize changes done | -| | manually to run standalone tests for Trex. | +| YARDSTICK-1458 | NSB NFVi PROX Should report realtime port activity not historical data. | +--------------------+--------------------------------------------------------------------------+ -| YARDSTICK-1389 | Add status filed for RFC2544 TC iterations | +| YARDSTICK-1471 | Add Testcase Prox Standalone SRIOV. | +--------------------+--------------------------------------------------------------------------+ -| YARDSTICK-1395 | Update 'configure_uwsgi' role to work in baremetal/container modes. | +| YARDSTICK-1475 | Adding Testcase for Prox Stanalone OvS-DPDK. | +--------------------+--------------------------------------------------------------------------+ -| YARDSTICK-1402 | Change IP assignment for VM to static for standalone context | +| YARDSTICK-1500 | Adding Testcase for Prox L2FWD PktTouch Stanalone OvS-DPDK. | +--------------------+--------------------------------------------------------------------------+ -| YARDSTICK-1404 | CPU Utilization for VNF and traffic generator are now graphed on Grafana | +| YARDSTICK-1517 | Missing opnfv "os-ovn-nofeature-ha" scenario test suite. | +--------------------+--------------------------------------------------------------------------+ -| YARDSTICK-1411 | Fix Yardstick Docker image ARM build | +| YARDSTICK-l526 | Run testcase 074 result overridden by job status. | +--------------------+--------------------------------------------------------------------------+ -| YARDSTICK-1414 | Update the pinned sampleVNF version to use a commit instead of a branch | +| YARDSTICK-1547 | Adding scale up test case for l3fwd OvS-DPDK. | +--------------------+--------------------------------------------------------------------------+ -| YARDSTICK-1418 | NSB PROX NFVi test now stops after reaching expected precision | +| YARDSTICK-1560 | Fix pip environment. | +--------------------+--------------------------------------------------------------------------+ -| YARDSTICK-1457 | Fix influxdb "field type conflict" error | +| YARDSTICK-1561 | L3FWD Gradana Dashboards Out-of-date and incorrect. | +--------------------+--------------------------------------------------------------------------+ -| YARDSTICK-1458 | Update Grafana to display "real-time" data instead of historical data. | -+--------------------+--------------------------------------------------------------------------+ -| YARDSTICK-1462 | NSB: Add OvS 2.8.1 support in SA context | -+--------------------+--------------------------------------------------------------------------+ -| YARDSTICK-1492 | Make OvS server to listen on TCP | -+--------------------+--------------------------------------------------------------------------+ -| YARDSTICK-1493 | The RX queues number is hard-codded and cannot be changed | -+--------------------+--------------------------------------------------------------------------+ - -Gambia 7.0.0 known restrictions/issues +Gambia 7.1.0 known restrictions/issues ====================================== -+-----------+-----------------------+------------------+ -| Installer | Scenario | Issue | -+===========+=======================+==================+ -| apex | os-ovn-nofeature-ha | YARDSTICK-1517 | -+-----------+-----------------------+------------------+ Useful links ============ diff --git a/docs/testing/developer/devguide/devguide_nsb_prox.rst b/docs/testing/developer/devguide/devguide_nsb_prox.rst index be2b5be61..44a216b75 100755 --- a/docs/testing/developer/devguide/devguide_nsb_prox.rst +++ b/docs/testing/developer/devguide/devguide_nsb_prox.rst @@ -8,6 +8,8 @@ for Telco customers, investigate the impact of new Intel compute, network and storage technologies, characterize performance, and develop optimal system architectures and configurations. +NSB PROX Supports Baremetal, Openstack and standalone configuration. + .. contents:: Prerequisites @@ -162,11 +164,11 @@ A NSB Prox test is composed of the following components :- server descriptions, in the case of baremetal the hardware description location. It also contains the name of the Traffic Generator, the SUT config file and the traffic profile description, all described below. - See nsb-test-description-label_ + See `Test Description File`_ * Traffic Profile file. Example ``prox_binsearch.yaml``. This describes the packet size, tolerated loss, initial line rate to start traffic at, test - interval etc See nsb-traffic-profile-label_ + interval etc See `Traffic Profile File`_ * Traffic Generator Config file. Usually called ``gen_<test>-<ports>.cfg``. @@ -179,7 +181,7 @@ A NSB Prox test is composed of the following components :- under test. Example traffic generator config file ``gen_l2fwd-4.cfg`` - See nsb-traffic-generator-label_ + See `Traffic Generator Config file`_ * SUT Config file. Usually called ``handle_<test>-<ports>.cfg``. @@ -193,7 +195,7 @@ A NSB Prox test is composed of the following components :- the ports to the Traffic Verifier tasks of the Traffic Generator. Example traffic generator config file ``handle_l2fwd-4.cfg`` - See nsb-sut-generator-label_ + See `SUT Config File`_ * NSB PROX Baremetal Configuration file. Usually called ``prox-baremetal-<ports>.yaml`` @@ -202,12 +204,12 @@ A NSB Prox test is composed of the following components :- This is required for baremetal only. This describes hardware, NICs, IP addresses, Network drivers, usernames and passwords. - See baremetal-config-label_ + See `Baremetal Configuration File`_ * Grafana Dashboard. Usually called ``Prox_<context>_<test>-<port>-<DateAndTime>.json`` where - * <context> Is either ``BM`` or ``heat`` + * <context> Is ``BM``,``heat``,``ovs_dpdk`` or ``sriov`` * <test> Is the a one or 2 word description of the test. * <port> is the number of ports used express as ``2Port`` or ``4Port`` * <DateAndTime> is the Date and Time expressed as a string. @@ -217,15 +219,15 @@ A NSB Prox test is composed of the following components :- Other files may be required. These are test specific files and will be covered later. -.. _nsb-test-description-label: -**Test Description File** +Test Description File +--------------------- -Here we will discuss the test description for both -baremetal and openstack. +Here we will discuss the test description for +baremetal, openstack and standalone. -*Test Description File for Baremetal* -------------------------------------- +Test Description File for Baremetal +----------------------------------- This section will introduce the meaning of the Test case description file. We will use ``tc_prox_baremetal_l2fwd-2.yaml`` as an example to @@ -239,7 +241,7 @@ Now let's examine the components of the file in detail 1. ``traffic_profile`` - This specifies the traffic profile for the test. In this case ``prox_binsearch.yaml`` is used. See - nsb-traffic-profile-label_ + `Traffic Profile File`_ 2. ``topology`` - This is either ``prox-tg-topology-1.yaml`` or ``prox-tg-topology-2.yaml`` or ``prox-tg-topology-4.yaml`` @@ -251,10 +253,13 @@ Now let's examine the components of the file in detail 4. ``interface_speed_gbps`` - This is an optional parameter. If not present the system defaults to 10Gbps. This defines the speed of the interfaces. -5. ``prox_path`` - Location of the Prox executable on the traffic +5. ``collectd`` - (Optional) This specifies we want to collect NFVI statistics + like CPU Utilization, + +6. ``prox_path`` - Location of the Prox executable on the traffic generator (Either baremetal or Openstack Virtual Machine) -6. ``prox_config`` - This is the ``SUT Config File``. +7. ``prox_config`` - This is the ``SUT Config File``. In this case it is ``handle_l2fwd-2.cfg`` A number of additional parameters can be added. This example @@ -263,6 +268,14 @@ Now let's examine the components of the file in detail options: interface_speed_gbps: 10 + traffic_config: + tolerated_loss: 0.01 + test_precision: 0.01 + packet_sizes: [64] + duration: 30 + lower_bound: 0.0 + upper_bound: 100.0 + vnf__0: prox_path: /opt/nsb_bin/prox prox_config: ``configs/handle_vpe-4.cfg`` @@ -276,55 +289,60 @@ Now let's examine the components of the file in detail ``configs/vpe_rules.lua`` : ```` prox_generate_parameter: True - ``interface_speed_gbps`` - this specifies the speed of the interface - in Gigabits Per Second. This is used to calculate pps(packets per second). - If the interfaces are of different speeds, then this specifies the speed - of the slowest interface. This parameter is optional. If omitted the - interface speed defaults to 10Gbps. + ``interface_speed_gbps`` - this specifies the speed of the interface + in Gigabits Per Second. This is used to calculate pps(packets per second). + If the interfaces are of different speeds, then this specifies the speed + of the slowest interface. This parameter is optional. If omitted the + interface speed defaults to 10Gbps. - ``prox_files`` - this specified that a number of addition files - need to be provided for the test to run correctly. This files - could provide routing information,hashing information or a - hashing algorithm and ip/mac information. + ``traffic_config`` - This allows the values here to override the values in + in the traffic_profile file. e.g. "prox_binsearch.yaml". Values provided + here override values provided in the "traffic_profile" section of the + traffic_profile file. Some, all or none of the values can be provided here. - ``prox_generate_parameter`` - this specifies that the NSB application - is required to provide information to the nsb Prox in the form - of a file called ``parameters.lua``, which contains information - retrieved from either the hardware or the openstack configuration. + The values describes the packet size, tolerated loss, initial line rate + to start traffic at, test interval etc See `Traffic Profile File`_ -7. ``prox_args`` - this specifies the command line arguments to start - prox. See `prox command line`_. + ``prox_files`` - this specified that a number of addition files + need to be provided for the test to run correctly. This files + could provide routing information,hashing information or a + hashing algorithm and ip/mac information. + + ``prox_generate_parameter`` - this specifies that the NSB application + is required to provide information to the nsb Prox in the form + of a file called ``parameters.lua``, which contains information + retrieved from either the hardware or the openstack configuration. -8. ``prox_config`` - This specifies the Traffic Generator config file. +8. ``prox_args`` - this specifies the command line arguments to start + prox. See `prox command line`_. -9. ``runner`` - This is set to ``ProxDuration`` - This specifies that the - test runs for a set duration. Other runner types are available - but it is recommend to use ``ProxDuration`` +9. ``prox_config`` - This specifies the Traffic Generator config file. - The following parrameters are supported +10. ``runner`` - This is set to ``ProxDuration`` - This specifies that the + test runs for a set duration. Other runner types are available + but it is recommend to use ``ProxDuration``. The following parameters + are supported - ``interval`` - (optional) - This specifies the sampling interval. - Default is 1 sec + ``interval`` - (optional) - This specifies the sampling interval. + Default is 1 sec - ``sampled`` - (optional) - This specifies if sampling information is - required. Default ``no`` + ``sampled`` - (optional) - This specifies if sampling information is + required. Default ``no`` - ``duration`` - This is the length of the test in seconds. Default - is 60 seconds. + ``duration`` - This is the length of the test in seconds. Default + is 60 seconds. - ``confirmation`` - This specifies the number of confirmation retests to - be made before deciding to increase or decrease line speed. Default 0. + ``confirmation`` - This specifies the number of confirmation retests to + be made before deciding to increase or decrease line speed. Default 0. -10. ``context`` - This is ``context`` for a 2 port Baremetal configuration. +11. ``context`` - This is ``context`` for a 2 port Baremetal configuration. If a 4 port configuration was required then file ``prox-baremetal-4.yaml`` would be used. This is the NSB Prox baremetal configuration file. -.. _nsb-traffic-profile-label: - -*Traffic Profile file* ----------------------- +Traffic Profile File +-------------------- This describes the details of the traffic flow. In this case ``prox_binsearch.yaml`` is used. @@ -334,8 +352,9 @@ This describes the details of the traffic flow. In this case :alt: NSB PROX Traffic Profile -1. ``name`` - The name of the traffic profile. This name should match the name - specified in the ``traffic_profile`` field in the Test Description File. +1. ``name`` - The name of the traffic profile. This name should match the + name specified in the ``traffic_profile`` field in the Test + Description File. 2. ``traffic_type`` - This specifies the type of traffic pattern generated, This name matches class name of the traffic generator. See:: @@ -396,19 +415,20 @@ See this prox_vpe.yaml as example:: lower_bound: 0.0 upper_bound: 100.0 -*Test Description File for Openstack* -------------------------------------- +Test Description File for Openstack +----------------------------------- We will use ``tc_prox_heat_context_l2fwd-2.yaml`` as a example to show you how to understand the test description file. -.. image:: images/PROX_Test_HEAT_Script1.png - :width: 800px - :alt: NSB PROX Test Description File - Part 1 + .. image:: images/PROX_Test_HEAT_Script1.png + :width: 800px + :alt: NSB PROX Test Description File - Part 1 -.. image:: images/PROX_Test_HEAT_Script2.png - :width: 800px - :alt: NSB PROX Test Description File - Part 2 + + .. image:: images/PROX_Test_HEAT_Script2.png + :width: 800px + :alt: NSB PROX Test Description File - Part 2 Now lets examine the components of the file in detail @@ -464,10 +484,64 @@ F. ``networks`` - is composed of a management network labeled ``mgmt`` port_security_enabled: False enable_dhcp: 'false' -.. _nsb-traffic-generator-label: +Test Description File for Standalone +------------------------------------ + +We will use ``tc_prox_ovs-dpdk_l2fwd-2.yaml`` as a example to show +you how to understand the test description file. + + .. image:: images/PROX_Test_ovs_dpdk_Script_1.png + :width: 800px + :alt: NSB PROX Test Standalone Description File - Part 1 + + .. image:: images/PROX_Test_ovs_dpdk_Script_2.png + :width: 800px + :alt: NSB PROX Test Standalone Description File - Part 2 + +Now lets examine the components of the file in detail + +Sections 1 to 9 are exactly the same in Baremetal and in Heat. Section +``10`` is replaced with sections A to F. Section 10 was for a baremetal +configuration file. This has no place in a heat configuration. + +A. ``file`` - Pod file for Baremetal Traffic Generator configuration: + IP Address, User/Password & Interfaces + +B. ``type`` - This defines the type of standalone configuration. + Possible values are ``StandaloneOvsDpdk`` or ``StandaloneSriov`` + +C. ``file`` - Pod file for Standalone host configuration: + IP Address, User/Password & Interfaces + +D. ``vm_deploy`` - Deploy a new VM or use an existing VM -*Traffic Generator Config file* -------------------------------- +E. ``ovs_properties`` - OVS Version, DPDK Version and configuration + to use. + +F. ``flavor``- NSB image generated when installing NSB using ansible-playbook:: + + ram- Configurable RAM for SUT VM + extra_specs + hw:cpu_sockets - Configurable number of Sockets for SUT VM + hw:cpu_cores - Configurable number of Cores for SUT VM + hw:cpu_threads- Configurable number of Threads for SUT VM + +G. ``mgmt`` - Management port of the SUT VM. Preconfig needed on TG & SUT host machines. + is the system under test. + + +H. ``xe0`` - Upline Network port + +I. ``xe1`` - Downline Network port + +J. ``uplink_0`` - Uplink Phy port of the NIC on the host. This will be used to create + the Virtual Functions. + +K. ``downlink_0`` - Downlink Phy port of the NIC on the host. This will be used to + create the Virtual Functions. + +Traffic Generator Config file +----------------------------- This section will describe the traffic generator config file. This is the same for both baremetal and heat. See this example @@ -725,10 +799,8 @@ Now let's examine the components of the file in detail to be read from. Note that the SUT workload might cause the position of the timestamp to change (i.e. due to encapsulation). -.. _nsb-sut-generator-label: - -*SUT Config file* -------------------------------- +SUT Config File +--------------- This section will describes the SUT(VNF) config file. This is the same for both baremetal and heat. See this example of ``handle_l2fwd_multiflow-2.cfg`` to @@ -892,10 +964,8 @@ Now let's examine the components of the file in detail :width: 1000px :alt: NSB PROX Config File for BNG_QOS -*Baremetal Configuration file* ------------------------------- - -.. _baremetal-config-label: +Baremetal Configuration File +---------------------------- This is required for baremetal testing. It describes the IP address of the various ports, the Network devices drivers and MAC addresses and the network @@ -933,8 +1003,8 @@ Now let's describe the sections of the file. 9. ``routing_table`` - All parameters should remain unchanged. 10. ``nd_route_tbl`` - All parameters should remain unchanged. -*Grafana Dashboard* -------------------- +Grafana Dashboard +----------------- The grafana dashboard visually displays the results of the tests. The steps required to produce a grafana dashboard are described here. @@ -987,7 +1057,7 @@ In order to run the NSB PROX test. cd /home/opnfv/repos/yardstick/samples/vnf_samples/nsut/prox b. Install prox-baremetal-2.yam and prox-baremetal-4.yaml for that - topology into this directory as per baremetal-config-label_ + topology into this directory as per `Baremetal Configuration File`_ c. Install and configure ``yardstick.conf`` :: @@ -1032,14 +1102,12 @@ Frequently Asked Questions Here is a list of frequently asked questions. -*NSB Prox does not work on Baremetal, How do I resolve this?* -------------------------------------------------------------- +NSB Prox does not work on Baremetal, How do I resolve this? +----------------------------------------------------------- If PROX NSB does not work on baremetal, problem is either in network configuration or test file. -*Solution* - 1. Verify network configuration. Execute existing baremetal test.:: yardstick --debug task start ./tc_prox_baremetal_l2fwd-4.yaml @@ -1079,10 +1147,8 @@ configuration or test file. 2. If existing baremetal works then issue is with your test. Check the traffic generator gen_<test>-<ports>.cfg to ensure it is producing a valid packet. -*How do I debug NSB Prox on Baremetal?* ---------------------------------------- - -*Solution* +How do I debug NSB Prox on Baremetal? +------------------------------------- 1. Execute the test as follows:: @@ -1148,8 +1214,8 @@ configuration or test file. dump_tx 1 0 1 -*NSB Prox works on Baremetal but not in Openstack. How do I resolve this?* --------------------------------------------------------------------------- +NSB Prox works on Baremetal but not in Openstack. How do I resolve this? +------------------------------------------------------------------------ NSB Prox on Baremetal is a lot more forgiving than NSB Prox on Openstack. A badly formed packed may still work with PROX on Baremetal. However on @@ -1157,7 +1223,6 @@ Openstack the packet must be correct and all fields of the header correct. E.g. A packet with an invalid Protocol ID would still work in Baremetal but this packet would be rejected by openstack. -*Solution* 1. Check the validity of the packet. 2. Use a known good packet in your test @@ -1165,10 +1230,8 @@ this packet would be rejected by openstack. retry. -*How do I debug NSB Prox on Openstack?* ---------------------------------------- - -*Solution* +How do I debug NSB Prox on Openstack? +------------------------------------- 1. Execute the test as follows:: @@ -1239,10 +1302,8 @@ this packet would be rejected by openstack. Now continue as baremetal. -*How do I resolve "Quota exceeded for resources"* -------------------------------------------------- - -*Solution* +How do I resolve "Quota exceeded for resources" +----------------------------------------------- This usually occurs due to 2 reasons when executing an openstack test. @@ -1276,10 +1337,8 @@ This usually occurs due to 2 reasons when executing an openstack test. openstack quota set <resource> -*Openstack Cli fails or hangs. How do I resolve this?* ------------------------------------------------------- - -*Solution* +Openstack CLI fails or hangs. How do I resolve this? +---------------------------------------------------- If it fails due to :: @@ -1310,7 +1369,7 @@ Result :: and visible. -If the Openstack ClI appears to hang, then verify the proxys and ``no_proxy`` +If the Openstack CLI appears to hang, then verify the proxys and ``no_proxy`` are set correctly. They should be similar to :: FTP_PROXY="http://<your_proxy>:<port>/" @@ -1328,8 +1387,8 @@ Where 2) 10.237.223.80 = IP Address of Controller node 3) 10.237.222.134 = IP Address of Compute Node -*How to Understand the Grafana output?* ---------------------------------------- +How to Understand the Grafana output? +------------------------------------- .. image:: images/PROX_Grafana_1.png :width: 1000px @@ -1347,50 +1406,75 @@ Where :width: 1000px :alt: NSB PROX Grafana_4 -A. Test Parameters - Test interval, Duartion, Tolerated Loss and Test Precision + .. image:: images/PROX_Grafana_5.png + :width: 1000px + :alt: NSB PROX Grafana_5 + + .. image:: images/PROX_Grafana_6.png + :width: 1000px + :alt: NSB PROX Grafana_6 + +A. Test Parameters - Test interval, Duration, Tolerated Loss and Test Precision B. No. of packets send and received during test -C. Generator Stats - packets sent, received and attempted by Generator +C. Generator Stats - Average Throughput per step (Step Duration is specified by + "Duration" field in A above) D. Packet size -E. No. of packets received by SUT +E. No. of packets sent by the generator per second per interface in millions + of packets per second. + +F. No. of packets recieved by the generator per second per interface in millions + of packets per second. + +G. No. of packets received by the SUT from the generator in millions of packets + per second. -F. No. of packets forwarded by SUT +H. No. of packets sent by the the SUT to the generator in millions of packets + per second. -G. No. of packets sent by the generator per port, for each interval. +I. No. of packets sent by the Generator to the SUT per step per interface + in millions of packets per second. -H. No. of packets received by the generator per port, for each interval. +J. No. of packets received by the Generator from the SUT per step per interface + in millions of packets per second. -I. No. of packets sent and received by the generator and lost by the SUT that +K. No. of packets sent and received by the generator and lost by the SUT that meet the success criteria -J. The change in the Percentage of Line Rate used over a test, The MAX and the +L. The change in the Percentage of Line Rate used over a test, The MAX and the MIN should converge to within the interval specified as the ``test-precision``. -K. Packet size supported during test. If *N/A* appears in any field the +M. Packet size supported during test. If *N/A* appears in any field the result has not been decided. -L. Calculated throughput in MPPS (Million Packets Per second) for this line - rate. +N. The Theretical Maximum no. of packets per second that can be sent for this + packet size. -M. No. of packets sent by the generator in MPPS +O. No. of packets sent by the generator in MPPS -N. No. of packets received by the generator in MPPS +P. No. of packets received by the generator in MPPS -O. No. of packets sent by SUT. +Q. No. of packets sent by SUT. -P. No. of packets received by the SUT +R. No. of packets received by the SUT -Q. Total no. of dropped packets -- Packets sent but not received back by the +S. Total no. of dropped packets -- Packets sent but not received back by the generator, these may be dropped by the SUT or the generator. -R. The tolerated no. of dropped packets. +T. The tolerated no. of dropped packets. -S. Test throughput in Gbps +U. Test throughput in Gbps -T. Latencey per Port +V. Latencey per Port + * Va - Port XE0 + * Vb - Port XE1 + * Vc - Port XE0 + * Vd - Port XE0 -U. CPU Utilization +W. CPU Utilization + * Wa - CPU Utilization of the Generator + * Wb - CPU Utilization of the SUT diff --git a/docs/testing/developer/devguide/images/PROX_Grafana_1.png b/docs/testing/developer/devguide/images/PROX_Grafana_1.png Binary files differindex d272edcf3..144000bb8 100644 --- a/docs/testing/developer/devguide/images/PROX_Grafana_1.png +++ b/docs/testing/developer/devguide/images/PROX_Grafana_1.png diff --git a/docs/testing/developer/devguide/images/PROX_Grafana_2.png b/docs/testing/developer/devguide/images/PROX_Grafana_2.png Binary files differindex 4f7fd4cf5..af1ebb315 100644 --- a/docs/testing/developer/devguide/images/PROX_Grafana_2.png +++ b/docs/testing/developer/devguide/images/PROX_Grafana_2.png diff --git a/docs/testing/developer/devguide/images/PROX_Grafana_3.png b/docs/testing/developer/devguide/images/PROX_Grafana_3.png Binary files differindex 5ae967698..a287670c9 100644 --- a/docs/testing/developer/devguide/images/PROX_Grafana_3.png +++ b/docs/testing/developer/devguide/images/PROX_Grafana_3.png diff --git a/docs/testing/developer/devguide/images/PROX_Grafana_4.png b/docs/testing/developer/devguide/images/PROX_Grafana_4.png Binary files differindex 5353d1c7e..6752dc324 100644 --- a/docs/testing/developer/devguide/images/PROX_Grafana_4.png +++ b/docs/testing/developer/devguide/images/PROX_Grafana_4.png diff --git a/docs/testing/developer/devguide/images/PROX_Grafana_5.png b/docs/testing/developer/devguide/images/PROX_Grafana_5.png Binary files differnew file mode 100644 index 000000000..45746d86b --- /dev/null +++ b/docs/testing/developer/devguide/images/PROX_Grafana_5.png diff --git a/docs/testing/developer/devguide/images/PROX_Grafana_6.png b/docs/testing/developer/devguide/images/PROX_Grafana_6.png Binary files differnew file mode 100644 index 000000000..5bdbcf26a --- /dev/null +++ b/docs/testing/developer/devguide/images/PROX_Grafana_6.png diff --git a/docs/testing/developer/devguide/images/PROX_Test_BM_Script.png b/docs/testing/developer/devguide/images/PROX_Test_BM_Script.png Binary files differindex c09f7bb1b..84e640a20 100644 --- a/docs/testing/developer/devguide/images/PROX_Test_BM_Script.png +++ b/docs/testing/developer/devguide/images/PROX_Test_BM_Script.png diff --git a/docs/testing/developer/devguide/images/PROX_Test_ovs_dpdk_Script_1.png b/docs/testing/developer/devguide/images/PROX_Test_ovs_dpdk_Script_1.png Binary files differnew file mode 100644 index 000000000..73f6f2920 --- /dev/null +++ b/docs/testing/developer/devguide/images/PROX_Test_ovs_dpdk_Script_1.png diff --git a/docs/testing/developer/devguide/images/PROX_Test_ovs_dpdk_Script_2.png b/docs/testing/developer/devguide/images/PROX_Test_ovs_dpdk_Script_2.png Binary files differnew file mode 100644 index 000000000..ad7d22822 --- /dev/null +++ b/docs/testing/developer/devguide/images/PROX_Test_ovs_dpdk_Script_2.png diff --git a/docs/testing/developer/devguide/images/vPE_Diagram.png b/docs/testing/developer/devguide/images/vPE_Diagram.png Binary files differnew file mode 100644 index 000000000..c3985b7d9 --- /dev/null +++ b/docs/testing/developer/devguide/images/vPE_Diagram.png diff --git a/docs/testing/user/userguide/01-introduction.rst b/docs/testing/user/userguide/01-introduction.rst index 5fc2e8d0f..2a3ab4ea7 100755 --- a/docs/testing/user/userguide/01-introduction.rst +++ b/docs/testing/user/userguide/01-introduction.rst @@ -1,7 +1,17 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International -.. License. -.. http://creativecommons.org/licenses/by/4.0 -.. (c) OPNFV, Ericsson AB and others. + License. + http://creativecommons.org/licenses/by/4.0 + (c) OPNFV, Ericsson AB and others. + + Convention for heading levels in Yardstick documentation: + + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ^^^^^^^ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. ============ Introduction @@ -32,7 +42,7 @@ independent. About This Document -=================== +------------------- This document consists of the following chapters: @@ -79,7 +89,7 @@ This document consists of the following chapters: cases. Contact Yardstick -================= +----------------- Feedback? `Contact us`_ diff --git a/docs/testing/user/userguide/02-methodology.rst b/docs/testing/user/userguide/02-methodology.rst index 34d271095..b1eee9781 100644 --- a/docs/testing/user/userguide/02-methodology.rst +++ b/docs/testing/user/userguide/02-methodology.rst @@ -1,20 +1,30 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International -.. License. -.. http://creativecommons.org/licenses/by/4.0 -.. (c) OPNFV, Ericsson AB and others. + License. + http://creativecommons.org/licenses/by/4.0 + (c) OPNFV, Ericsson AB and others. + + Convention for heading levels in Yardstick documentation: + + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ^^^^^^^ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. =========== Methodology =========== Abstract -======== +-------- This chapter describes the methodology implemented by the Yardstick project for verifying the :term:`NFVI` from the perspective of a :term:`VNF`. ETSI-NFV -======== +-------- .. _NFV-TST001: http://www.etsi.org/deliver/etsi_gs/NFV-TST/001_099/001/01.01.01_60/gs_NFV-TST001v010101p.pdf .. _Yardsticktst: https://wiki.opnfv.org/download/attachments/2925202/opnfv_summit_-_bridging_opnfv_and_etsi.pdf?version=1&modificationDate=1458848320000&api=v2 @@ -53,7 +63,7 @@ The methodology includes five steps: .. seealso:: Yardsticktst_ for material on alignment ETSI TST001 and Yardstick. Metrics -======= +------- The metrics, as defined by ETSI GS NFV-TST001, are shown in :ref:`Table1 <table2_1>`, :ref:`Table2 <table2_2>` and diff --git a/docs/testing/user/userguide/03-architecture.rst b/docs/testing/user/userguide/03-architecture.rst index 62250d6a3..94081b0e1 100755 --- a/docs/testing/user/userguide/03-architecture.rst +++ b/docs/testing/user/userguide/03-architecture.rst @@ -1,23 +1,34 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International -.. License. -.. http://creativecommons.org/licenses/by/4.0 -.. (c) 2016 Huawei Technologies Co.,Ltd and others + License. + http://creativecommons.org/licenses/by/4.0 + (c) 2016 Huawei Technologies Co.,Ltd and others + + Convention for heading levels in Yardstick documentation: + + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ^^^^^^^ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. ============ Architecture ============ Abstract -======== -This chapter describes the yardstick framework software architecture. We will -introduce it from Use-Case View, Logical View, Process View and Deployment +-------- + +This chapter describes the Yardstick framework software architecture. We will +introduce it from Use Case View, Logical View, Process View and Deployment View. More technical details will be introduced in this chapter. Overview -======== +-------- Architecture overview ---------------------- +^^^^^^^^^^^^^^^^^^^^^ Yardstick is mainly written in Python, and test configurations are made in YAML. Documentation is written in reStructuredText format, i.e. .rst files. Yardstick is inspired by Rally. Yardstick is intended to run on a @@ -34,7 +45,8 @@ the test result will be shown with grafana. Concept -------- +^^^^^^^ + **Benchmark** - assess the relative performance of something **Benchmark** configuration file - describes a single test case in yaml format @@ -62,7 +74,7 @@ configuration file and evaluated by the runner. Runner types ------------- +^^^^^^^^^^^^ There exists several predefined runner types to choose between when designing a test scenario: @@ -129,7 +141,8 @@ Snippet of an Iteration runner configuration: Use-Case View -============= +------------- + Yardstick Use-Case View shows two kinds of users. One is the Tester who will do testing in cloud, the other is the User who is more concerned with test result and result analyses. @@ -158,7 +171,8 @@ on OPNFV testing dashboard which use MongoDB as backend. :alt: Yardstick Use-Case View Logical View -============ +------------ + Yardstick Logical View describes the most important classes, their organization, and the most important use-case realizations. @@ -195,7 +209,8 @@ finished. :alt: Yardstick framework architecture in Danube Process View (Test execution flow) -================================== +---------------------------------- + Yardstick process view shows how yardstick runs a test case. Below is the sequence graph about the test execution flow using heat context, and each object represents one module in yardstick: @@ -222,7 +237,8 @@ will call "Openstack" to undeploy the heat stack. Once the stack is undepoyed, the whole test ends. Deployment View -=============== +--------------- + Yardstick deployment view shows how the yardstick tool can be deployed into the underlying platform. Generally, yardstick tool is installed on JumpServer(see `07-installation` for detail installation steps), and JumpServer is @@ -235,7 +251,7 @@ result for better showing. :alt: Yardstick Deployment View Yardstick Directory structure -============================= +----------------------------- **yardstick/** - Yardstick main directory. diff --git a/docs/testing/user/userguide/04-installation.rst b/docs/testing/user/userguide/04-installation.rst index 2f8175c25..2dff80ef9 100644 --- a/docs/testing/user/userguide/04-installation.rst +++ b/docs/testing/user/userguide/04-installation.rst @@ -1,7 +1,17 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International -.. License. -.. http://creativecommons.org/licenses/by/4.0 -.. (c) OPNFV, Ericsson AB, Huawei Technologies Co.,Ltd and others. + License. + http://creativecommons.org/licenses/by/4.0 + (c) OPNFV, Ericsson AB, Huawei Technologies Co.,Ltd and others. + + + Convention for heading levels in Yardstick documentation: + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ^^^^^^^ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. .. Convention for heading levels in Yardstick documentation: @@ -18,7 +28,6 @@ Yardstick Installation ====================== - Yardstick supports installation by Docker or directly in Ubuntu. The installation procedure for Docker and direct installation are detailed in the sections below. @@ -139,7 +148,7 @@ in the following sections. Before that, access the Yardstick container:: and then configure Yardstick environments in the Yardstick container. Using the CLI command ``env prepare`` (first way) (**recommended**) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ In the Yardstick container, the Yardstick repository is located in the ``/home/opnfv/repos`` directory. Yardstick provides a CLI to prepare OpenStack @@ -171,10 +180,10 @@ terminal window and execute the following command:: Manually exporting the env variables and initializing OpenStack (second way) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Export OpenStack environment variables -###################################### +'''''''''''''''''''''''''''''''''''''' Before running Yardstick it is necessary to export OpenStack environment variables:: @@ -200,7 +209,7 @@ A sample ``openrc`` file may look like this:: Manual creation of Yardstick flavor and guest images -#################################################### +'''''''''''''''''''''''''''''''''''''''''''''''''''' Before executing Yardstick test cases, make sure that Yardstick flavor and guest image are available in OpenStack. Detailed steps about creating the @@ -257,14 +266,14 @@ image. Add Cirros and Ubuntu images to OpenStack:: Automatic initialization of OpenStack (third way) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ++++++++++++++++++++++++++++++++++++++++++++++++++ Similar to the second way, the first step is also to `Export OpenStack environment variables`_. Then the following steps should be done. Automatic creation of Yardstick flavor and guest images -####################################################### +''''''''''''''''''''''''''''''''''''''''''''''''''''''' Yardstick has a script for automatically creating Yardstick flavor and building Yardstick guest images. This script is mainly used for CI and can be also used @@ -340,7 +349,6 @@ For installing Yardstick directly in Ubuntu, the ``yardstick env`` command is not available. You need to prepare OpenStack environment variables and create Yardstick flavor and guest images manually. - Uninstall Yardstick ^^^^^^^^^^^^^^^^^^^ @@ -613,15 +621,15 @@ Run influxDB:: sudo -EH docker run -d --name influxdb \ -p 8083:8083 -p 8086:8086 --expose 8090 --expose 8099 \ tutum/influxdb - docker exec -it influxdb influx Configure influxDB:: + docker exec -it influxdb influx > CREATE USER root WITH PASSWORD 'root' WITH ALL PRIVILEGES > CREATE DATABASE yardstick; > use yardstick; > show MEASUREMENTS; - > quit + > exit Run Grafana:: @@ -655,11 +663,9 @@ Modify ``yardstick.conf`` to add the ``influxdb`` dispatcher:: Now Yardstick will store results in InfluxDB when you run a testcase. - Deploy InfluxDB and Grafana directly in Ubuntu (**Todo**) --------------------------------------------------------- - Proxy Support ------------- diff --git a/docs/testing/user/userguide/06-yardstick-plugin.rst b/docs/testing/user/userguide/06-yardstick-plugin.rst index bc35e239d..a5d890b14 100644 --- a/docs/testing/user/userguide/06-yardstick-plugin.rst +++ b/docs/testing/user/userguide/06-yardstick-plugin.rst @@ -3,13 +3,23 @@ .. http://creativecommons.org/licenses/by/4.0 .. (c) OPNFV, Ericsson AB, Huawei Technologies Co.,Ltd and others. +.. Convention for heading levels in Yardstick documentation: + + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ^^^^^^^ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. + =================================== Installing a plug-in into Yardstick =================================== Abstract -======== +-------- Yardstick provides a ``plugin`` CLI command to support integration with other OPNFV testing projects. Below is an example invocation of Yardstick plugin @@ -17,7 +27,7 @@ command and Storperf plug-in sample. Installing Storperf into Yardstick -================================== +---------------------------------- Storperf is delivered as a Docker container from https://hub.docker.com/r/opnfv/storperf/tags/. @@ -31,7 +41,7 @@ In this introduction we will install Storperf on Jump Host. Step 0: Environment preparation -------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Running Storperf on Jump Host Requirements: @@ -100,7 +110,7 @@ container. You may need to copy it to the root directory of the Storperf deployed host. Step 1: Plug-in configuration file preparation ----------------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To install a plug-in, first you need to prepare a plug-in configuration file in YAML format and store it in the "plugin" directory. The plugin configration @@ -125,7 +135,7 @@ Here the Storperf will be installed on IP 192.168.23.2 which is the Jump Host in my local environment. Step 2: Plug-in install/remove scripts preparation --------------------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In ``yardstick/resource/scripts`` directory, there are two folders: an ``install`` folder and a ``remove`` folder. You need to store the plug-in @@ -139,15 +149,15 @@ For example, the install and remove scripts for Storperf are both named ``storperf.bash``. Step 3: Install and remove Storperf ------------------------------------ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To install Storperf, simply execute the following command:: # Install Storperf yardstick plugin install plugin/storperf.yaml -Removing Storperf from yardstick -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Removing Storperf from Yardstick +++++++++++++++++++++++++++++++++ To remove Storperf, simply execute the following command:: diff --git a/docs/testing/user/userguide/07-result-store-InfluxDB.rst b/docs/testing/user/userguide/07-result-store-InfluxDB.rst index cde931376..8a9196b1b 100644 --- a/docs/testing/user/userguide/07-result-store-InfluxDB.rst +++ b/docs/testing/user/userguide/07-result-store-InfluxDB.rst @@ -1,14 +1,23 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International -.. License. -.. http://creativecommons.org/licenses/by/4.0 -.. (c) OPNFV, 2016 Huawei Technologies Co.,Ltd and others. + License. + http://creativecommons.org/licenses/by/4.0 + (c) OPNFV, 2016 Huawei Technologies Co.,Ltd and others. + Convention for heading levels in Yardstick documentation: + + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ^^^^^^^ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. ============================================== Store Other Project's Test Results in InfluxDB ============================================== Abstract -======== +-------- .. _Framework: https://wiki.opnfv.org/download/attachments/6827660/wiki.png?version=1&modificationDate=1470298075000&api=v2 @@ -21,7 +30,7 @@ into community's InfluxDB. The framework is shown in Framework_. :alt: Store Other Project's Test Results in InfluxDB Store Storperf Test Results into Community's InfluxDB -===================================================== +----------------------------------------------------- .. _Influxdb: https://git.opnfv.org/cgit/yardstick/tree/yardstick/dispatcher/influxdb.py .. _Mingjiang: mailto:limingjiang@huawei.com diff --git a/docs/testing/user/userguide/08-grafana.rst b/docs/testing/user/userguide/08-grafana.rst index 020a08a65..ebe9f570d 100644 --- a/docs/testing/user/userguide/08-grafana.rst +++ b/docs/testing/user/userguide/08-grafana.rst @@ -3,13 +3,23 @@ .. http://creativecommons.org/licenses/by/4.0 .. (c) 2016 Huawei Technologies Co.,Ltd and others +.. Convention for heading levels in Yardstick documentation: + + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ^^^^^^^ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. + ================= Grafana dashboard ================= Abstract -======== +-------- This chapter describes the Yardstick grafana dashboard. The Yardstick grafana dashboard can be found here: http://testresults.opnfv.org/grafana/ @@ -21,14 +31,14 @@ dashboard can be found here: http://testresults.opnfv.org/grafana/ Public access -============= +------------- Yardstick provids a public account for accessing to the dashboard. The username and password are both set to ‘opnfv’. Testcase dashboard -================== +------------------ For each test case, there is a dedicated dashboard. Shown here is the dashboard of TC002. @@ -56,7 +66,7 @@ zoom out the chart. Administration access -===================== +--------------------- For a user with administration rights it is easy to update and save any dashboard configuration. Saved updates immediately take effect and become live. @@ -72,11 +82,11 @@ This may cause issues like: Any change made by administrator should be careful. -Add a dashboard into yardstick grafana -====================================== +Add a dashboard into Yardstick Grafana +-------------------------------------- Due to security concern, users that using the public opnfv account are not able -to edit the yardstick grafana directly.It takes a few more steps for a +to edit the yardstick grafana directly. It takes a few more steps for a non-yardstick user to add a custom dashboard into yardstick grafana. There are 6 steps to go. diff --git a/docs/testing/user/userguide/09-api.rst b/docs/testing/user/userguide/09-api.rst index 1a896699b..f227878ae 100644 --- a/docs/testing/user/userguide/09-api.rst +++ b/docs/testing/user/userguide/09-api.rst @@ -2,6 +2,15 @@ .. License. .. http://creativecommons.org/licenses/by/4.0 .. (c) OPNFV, Huawei Technologies Co.,Ltd and others. +.. Convention for heading levels in Yardstick documentation: + + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ^^^^^^^ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. ===================== Yardstick Restful API @@ -9,16 +18,16 @@ Yardstick Restful API Abstract -======== +-------- Yardstick support restful API since Danube. Available API -============= +------------- /yardstick/env/action ---------------------- +^^^^^^^^^^^^^^^^^^^^^ Description: This API is used to prepare Yardstick test environment. For Euphrates, it supports: @@ -69,7 +78,7 @@ get the task result. /yardstick/asynctask --------------------- +^^^^^^^^^^^^^^^^^^^^ Description: This API is used to get the status of asynchronous tasks @@ -91,7 +100,7 @@ NOTE:: /yardstick/testcases --------------------- +^^^^^^^^^^^^^^^^^^^^ Description: This API is used to list all released Yardstick test cases. @@ -106,7 +115,7 @@ Example:: /yardstick/testcases/release/action ------------------------------------ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Description: This API is used to run a Yardstick released test case. @@ -130,7 +139,7 @@ result. /yardstick/testcases/samples/action ------------------------------------ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Description: This API is used to run a Yardstick sample test case. @@ -154,7 +163,7 @@ the result. /yardstick/testcases/<testcase_name>/docs ------------------------------------------ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Description: This API is used to the documentation of a certain released test case. @@ -170,7 +179,7 @@ Example:: /yardstick/testsuites/action ----------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Description: This API is used to run a Yardstick test suite. @@ -194,7 +203,7 @@ result. /yardstick/tasks/<task_id>/log ------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Description: This API is used to get the real time log of test case execution. @@ -209,7 +218,7 @@ Example:: /yardstick/results ------------------- +^^^^^^^^^^^^^^^^^^ Description: This API is used to get the test results of tasks. If you call /yardstick/testcases/samples/action API, it will return a task id. You can use @@ -228,7 +237,7 @@ This API will return a list of test case result /api/v2/yardstick/openrcs -------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^ Description: This API provides functionality of handling OpenStack credential file (openrc). For Euphrates, it supports: @@ -282,7 +291,7 @@ Example:: /api/v2/yardstick/openrcs/<openrc_id> -------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Description: This API provides functionality of handling OpenStack credential file (openrc). For Euphrates, it supports: @@ -308,7 +317,7 @@ Example:: /api/v2/yardstick/pods ----------------------- +^^^^^^^^^^^^^^^^^^^^^^ Description: This API provides functionality of handling Yardstick pod file (pod.yaml). For Euphrates, it supports: @@ -334,7 +343,7 @@ Example:: /api/v2/yardstick/pods/<pod_id> -------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Description: This API provides functionality of handling Yardstick pod file (pod.yaml). For Euphrates, it supports: @@ -358,7 +367,7 @@ Example:: /api/v2/yardstick/images ------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^ Description: This API is used to do some work related to Yardstick VM images. For Euphrates, it supports: @@ -383,7 +392,7 @@ Example:: /api/v2/yardstick/images/<image_id> ------------------------------------ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Description: This API is used to do some work related to Yardstick VM images. For Euphrates, it supports: @@ -407,7 +416,7 @@ Example:: /api/v2/yardstick/tasks ------------------------ +^^^^^^^^^^^^^^^^^^^^^^^ Description: This API is used to do some work related to yardstick tasks. For Euphrates, it supports: @@ -433,7 +442,7 @@ Example:: /api/v2/yardstick/tasks/<task_id> ---------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Description: This API is used to do some work related to yardstick tasks. For Euphrates, it supports: @@ -518,7 +527,7 @@ Example:: /api/v2/yardstick/testcases ---------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^ Description: This API is used to do some work related to Yardstick testcases. For Euphrates, it supports: @@ -553,7 +562,7 @@ Example:: /api/v2/yardstick/testcases/<case_name> ---------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Description: This API is used to do some work related to yardstick testcases. For Euphrates, it supports: @@ -579,7 +588,7 @@ Example:: /api/v2/yardstick/testsuites ----------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Description: This API is used to do some work related to yardstick test suites. For Euphrates, it supports: @@ -617,7 +626,7 @@ Example:: /api/v2/yardstick/testsuites ----------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Description: This API is used to do some work related to yardstick test suites. For Euphrates, it supports: @@ -643,7 +652,7 @@ Example:: /api/v2/yardstick/projects --------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^ Description: This API is used to do some work related to Yardstick test projects. For Euphrates, it supports: @@ -678,7 +687,7 @@ Example:: /api/v2/yardstick/projects --------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^ Description: This API is used to do some work related to yardstick test projects. For Euphrates, it supports: @@ -704,7 +713,7 @@ Example:: /api/v2/yardstick/containers ----------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Description: This API is used to do some work related to Docker containers. For Euphrates, it supports: @@ -744,7 +753,7 @@ Example:: /api/v2/yardstick/containers/<container_id> -------------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Description: This API is used to do some work related to Docker containers. For Euphrates, it supports: diff --git a/docs/testing/user/userguide/10-yardstick-user-interface.rst b/docs/testing/user/userguide/10-yardstick-user-interface.rst index 76890b29a..246e1b1df 100644 --- a/docs/testing/user/userguide/10-yardstick-user-interface.rst +++ b/docs/testing/user/userguide/10-yardstick-user-interface.rst @@ -1,20 +1,50 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International +.. License. +.. http://creativecommons.org/licenses/by/4.0 + +.. Convention for heading levels in Yardstick documentation: + + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ^^^^^^^ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. + ======================== Yardstick User Interface ======================== -This interface provides a user to view the test result -in table format and also values pinned on to a graph. +This chapter describes how to generate HTML reports, used to view, store, share +or publish test results in table and graph formats. + +The following layouts are available: +* The compact HTML report layout is suitable for testcases producing a few + metrics over a short period of time. All metrics for all timestamps are + displayed in the data table and on the graph. -Command -======= -:: +* The dynamic HTML report layout consists of a wider data table, a graph, and + a tree that allows selecting the metrics to be displayed. This layout is + suitable for testcases, such as NSB ones, producing a lot of metrics over + a longer period of time. + + +Commands +-------- + +To generate the compact HTML report, run:: yardstick report generate <task-ID> <testcase-filename> +To generate the dynamic HTML report, run:: + + yardstick report generate-nsb <task-ID> <testcase-filename> + Description -=========== +----------- 1. When the command is triggered, the relevant values for the provided task-id and testcase name are retrieved from the @@ -27,8 +57,8 @@ Description The graph is framed with Timestamp on x-axis and output values (differ from testcase to testcase) on y-axis with the help of -`Highcharts`_. +`Chart.js`_. .. _InfluxDB: https://www.influxdata.com/time-series-platform/influxdb/ .. _Jinja2: http://jinja.pocoo.org/docs/2.10/ -.. _Highcharts: https://www.highcharts.com/products/highcharts/ +.. _Chart.js: https://www.chartjs.org/ diff --git a/docs/testing/user/userguide/12-nsb-overview.rst b/docs/testing/user/userguide/12-nsb-overview.rst index 7b0d46804..ec4df1cae 100644 --- a/docs/testing/user/userguide/12-nsb-overview.rst +++ b/docs/testing/user/userguide/12-nsb-overview.rst @@ -3,75 +3,88 @@ .. http://creativecommons.org/licenses/by/4.0 .. (c) OPNFV, 2016-2017 Intel Corporation. +.. Convention for heading levels in Yardstick documentation: + + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ^^^^^^^ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. + =================================== Network Services Benchmarking (NSB) =================================== -Abstract -======== - .. _Yardstick: https://wiki.opnfv.org/display/yardstick +.. _`ETSI GS NFV-TST001`: http://www.etsi.org/deliver/etsi_gs/NFV-TST/001_099/001/01.01.01_60/gs_nfv-tst001v010101p.pdf + +Abstract +-------- This chapter provides an overview of the NSB, a contribution to OPNFV Yardstick_ from Intel. Overview -======== - -The goal of NSB is to Extend Yardstick to perform real world VNFs and NFVi -Characterization and benchmarking with repeatable and deterministic methods. - -The Network Service Benchmarking (NSB) extends the yardstick framework to do -VNF characterization and benchmarking in three different execution -environments - bare metal i.e. native Linux environment, standalone virtual -environment and managed virtualized environment (e.g. Open stack etc.). -It also brings in the capability to interact with external traffic generators -both hardware & software based for triggering and validating the traffic -according to user defined profiles. +-------- + +Network Services Benchmarking (:term:`NSB`) uses the :term:`Yardstick` +framework for performing :term:`VNF` and :term:`NFVI` characterisation in an +:term:`NFV` environment. + +For VNF characterisation, NSB will onboard a VNF, source and sink traffic to it +via traffic generators, and collect a variety of key performance indicators +(:term:`KPI`) during VNF execution. The stream of KPI data is stored in a +database, and it is visualized in a performance-visualization dashboard. + +For NFVI characterisation, a fixed test VNF, called :term:`PROX` is used. +PROX implements a suite of test cases and visualizes the output data of the +test suite. The PROX test cases implement various execution kernels found in +real-world VNFs, and the output of the test cases provides an indication of +the fitness of the infrastructure for running NFV services, in addition to +indicating potential performance optimizations for the NFVI. + +NSB extends the Yardstick framework to do VNF characterization in three +different execution environments - bare metal i.e. native Linux environment, +standalone virtual environment and managed virtualized environment (e.g. +OpenStack). It also brings in the capability to interact with external traffic +generators, both hardware and software based, for triggering and validating the +traffic according to user defined profiles. NSB extension includes: - - Generic data models of Network Services, based on ETSI spec `ETSI GS NFV-TST 001 <http://www.etsi.org/deliver/etsi_gs/NFV-TST/001_099/001/01.01.01_60/gs_nfv-tst001v010101p.pdf>`_ - - - New Standalone context for VNF testing like SRIOV, OVS, OVS-DPDK etc - - - Generic VNF configuration models and metrics implemented with Python - classes - - - Traffic generator features and traffic profiles - - - L1-L3 state-less traffic profiles - - - L4-L7 state-full traffic profiles - - - Tunneling protocol / network overlay support - - - Test case samples +* Generic data models of Network Services, based on ETSI spec + `ETSI GS NFV-TST 001`_ +* Standalone :term:`context` for VNF testing with SRIOV, OVS, OVS-DPDK, etc +* Generic VNF configuration models and metrics implemented with Python + classes +* Traffic generator features and traffic profiles - - Ping + * L1-L3 stateless traffic profiles + * L4-L7 state-full traffic profiles + * Tunneling protocol/network overlay support - - Trex +* Test case samples - - vPE,vCGNAT, vFirewall etc - ipv4 throughput, latency etc + * Ping + * Trex + * vPE, vCGNAT, vFirewall etc - ipv4 throughput, latency etc - - Traffic generators like Trex, ab/nginx, ixia, iperf etc +* Traffic generators i.e. Trex, ab/nginx, ixia, iperf, etc +* KPIs for a given use case: - - KPIs for a given use case: + * System agent support for collecting NFVi KPI. This includes: - - System agent support for collecting NFVi KPI. This includes: + * CPU statistic + * Memory BW + * OVS-DPDK Stats - - CPU statistic - - - Memory BW - - - OVS-DPDK Stats - - - Network KPIs, e.g., inpackets, outpackets, thoughput, latency etc - - - VNF KPIs, e.g., packet_in, packet_drop, packet_fwd etc + * Network KPIs e.g. inpackets, outpackets, thoughput, latency + * VNF KPIs e.g. packet_in, packet_drop, packet_fwd Architecture -============ +------------ The Network Service (NS) defines a set of Virtual Network Functions (VNF) connected together using NFV infrastructure. @@ -83,124 +96,115 @@ performed network functionality. The part of the data model is a set of the configuration parameters, number of connection points used and flavor including core and memory amount. -The ETSI defines a Network Service as a set of configurable VNFs working in -some NFV Infrastructure connecting each other using Virtual Links available -through Connection Points. The ETSI MANO specification defines a set of -management entities called Network Service Descriptors (NSD) and -VNF Descriptors (VNFD) that define real Network Service. The picture below -makes an example how the real Network Operator use-case can map into ETSI -Network service definition - -Network Service framework performs the necessary test steps. It may involve - - - Interacting with traffic generator and providing the inputs on traffic - type / packet structure to generate the required traffic as per the - test case. Traffic profiles will be used for this. - - - Executing the commands required for the test procedure and analyses the - command output for confirming whether the command got executed correctly - or not. E.g. As per the test case, run the traffic for the given - time period / wait for the necessary time delay - - - Verify the test result. - - - Validate the traffic flow from SUT - - - Fetch the table / data from SUT and verify the value as per the test case - - - Upload the logs from SUT onto the Test Harness server - - - Read the KPI's provided by particular VNF +ETSI defines a Network Service as a set of configurable VNFs working in some +NFV Infrastructure connecting each other using Virtual Links available through +Connection Points. The ETSI MANO specification defines a set of management +entities called Network Service Descriptors (NSD) and VNF Descriptors (VNFD) +that define real Network Service. The picture below makes an example how the +real Network Operator use-case can map into ETSI Network service definition. + +Network Service framework performs the necessary test steps. It may involve: + +* Interacting with traffic generator and providing the inputs on traffic + type / packet structure to generate the required traffic as per the + test case. Traffic profiles will be used for this. +* Executing the commands required for the test procedure and analyses the + command output for confirming whether the command got executed correctly + or not e.g. as per the test case, run the traffic for the given + time period and wait for the necessary time delay. +* Verify the test result. +* Validate the traffic flow from SUT. +* Fetch the data from SUT and verify the value as per the test case. +* Upload the logs from SUT onto the Test Harness server +* Retrieve the KPI's provided by particular VNF Components of Network Service ------------------------------ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - * *Models for Network Service benchmarking*: The Network Service benchmarking - requires the proper modelling approach. The NSB provides models using Python - files and defining of NSDs and VNFDs. +* *Models for Network Service benchmarking*: The Network Service benchmarking + requires the proper modelling approach. The NSB provides models using Python + files and defining of NSDs and VNFDs. - The benchmark control application being a part of OPNFV yardstick can call - that python models to instantiate and configure the VNFs. Depending on - infrastructure type (bare-metal or fully virtualized) that calls could be - made directly or using MANO system. +The benchmark control application being a part of OPNFV Yardstick can call +that Python models to instantiate and configure the VNFs. Depending on +infrastructure type (bare-metal or fully virtualized) that calls could be +made directly or using MANO system. - * *Traffic generators in NSB*: Any benchmark application requires a set of - traffic generator and traffic profiles defining the method in which traffic - is generated. +* *Traffic generators in NSB*: Any benchmark application requires a set of + traffic generator and traffic profiles defining the method in which traffic + is generated. - The Network Service benchmarking model extends the Network Service - definition with a set of Traffic Generators (TG) that are treated - same way as other VNFs being a part of benchmarked network service. - Same as other VNFs the traffic generator are instantiated and terminated. +The Network Service benchmarking model extends the Network Service +definition with a set of Traffic Generators (TG) that are treated +same way as other VNFs being a part of benchmarked network service. +Same as other VNFs the traffic generator are instantiated and terminated. - Every traffic generator has own configuration defined as a traffic profile - and a set of KPIs supported. The python models for TG is extended by - specific calls to listen and generate traffic. +Every traffic generator has own configuration defined as a traffic profile +and a set of KPIs supported. The python models for TG is extended by +specific calls to listen and generate traffic. - * *The stateless TREX traffic generator*: The main traffic generator used as - Network Service stimulus is open source TREX tool. +* *The stateless TREX traffic generator*: The main traffic generator used as + Network Service stimulus is open source TREX tool. - The TREX tool can generate any kind of stateless traffic. +The TREX tool can generate any kind of stateless traffic. - .. code-block:: console - - +--------+ +-------+ +--------+ - | | | | | | - | Trex | ---> | VNF | ---> | Trex | - | | | | | | - +--------+ +-------+ +--------+ - - Supported testcases scenarios: +.. code-block:: console - - Correlated UDP traffic using TREX traffic generator and replay VNF. + +--------+ +-------+ +--------+ + | | | | | | + | Trex | ---> | VNF | ---> | Trex | + | | | | | | + +--------+ +-------+ +--------+ - - using different IMIX configuration like pure voice, pure video traffic etc +Supported testcases scenarios: - - using different number IP flows like 1 flow, 1K, 16K, 64K, 256K, 1M flows +* Correlated UDP traffic using TREX traffic generator and replay VNF. - - Using different number of rules configured like 1 rule, 1K, 10K rules + * using different IMIX configuration like pure voice, pure video traffic etc + * using different number IP flows e.g. 1, 1K, 16K, 64K, 256K, 1M flows + * Using different number of rules configured e.g. 1, 1K, 10K rules - For UDP correlated traffic following Key Performance Indicators are collected - for every combination of test case parameters: +For UDP correlated traffic following Key Performance Indicators are collected +for every combination of test case parameters: - - RFC2544 throughput for various loss rate defined (1% is a default) +* RFC2544 throughput for various loss rate defined (1% is a default) Graphical Overview -================== +------------------ -NSB Testing with yardstick framework facilitate performance testing of various +NSB Testing with Yardstick framework facilitate performance testing of various VNFs provided. .. code-block:: console +-----------+ - | | +-----------+ - | vPE | ->|TGen Port 0| - | TestCase | | +-----------+ - | | | - +-----------+ +------------------+ +-------+ | - | | -- API --> | VNF | <---> - +-----------+ | Yardstick | +-------+ | - | Test Case | --> | NSB Testing | | - +-----------+ | | | - | | | | - | +------------------+ | - +-----------+ | +-----------+ - | Traffic | ->|TGen Port 1| - | patterns | +-----------+ + | | +-------------+ + | vPE | -->| TGen Port 0 | + | TestCase | | +-------------+ + | | | + +-----------+ +---------------+ +-------+ | + | | ---> | VNF | <---> + +-----------+ | Yardstick | +-------+ | + | Test Case | --> | NSB Testing | | + +-----------+ | | | + | | | | + | +---------------+ | + +-----------+ | +-------------+ + | Traffic | -->| TGen Port 1 | + | patterns | +-------------+ +-----------+ Figure 1: Network Service - 2 server configuration -VNFs supported for chracterization: ------------------------------------ +VNFs supported for chracterization +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. CGNAPT - Carrier Grade Network Address and port Translation 2. vFW - Virtual Firewall 3. vACL - Access Control List -4. Prox - Packet pROcessing eXecution engine: - - VNF can act as Drop, Basic Forwarding (no touch), - L2 Forwarding (change MAC), GRE encap/decap, Load balance based on - packet fields, Symmetric load balancing - - QinQ encap/decap IPv4/IPv6, ARP, QoS, Routing, Unmpls, Policing, ACL +4. PROX - Packet pROcessing eXecution engine: + * VNF can act as Drop, Basic Forwarding (no touch), + L2 Forwarding (change MAC), GRE encap/decap, Load balance based on + packet fields, Symmetric load balancing + * QinQ encap/decap IPv4/IPv6, ARP, QoS, Routing, Unmpls, Policing, ACL 5. UDP_Replay diff --git a/docs/testing/user/userguide/13-nsb-installation.rst b/docs/testing/user/userguide/13-nsb-installation.rst index 973d56628..71ced43ea 100644 --- a/docs/testing/user/userguide/13-nsb-installation.rst +++ b/docs/testing/user/userguide/13-nsb-installation.rst @@ -8,40 +8,35 @@ ======= Heading 0 (reserved for the title in a document) ------- Heading 1 - ~~~~~~~ Heading 2 + ^^^^^^^ Heading 2 +++++++ Heading 3 ''''''' Heading 4 Avoid deeper levels because they do not render well. -===================================== -Yardstick - NSB Testing -Installation -===================================== + +================ +NSB Installation +================ + +.. _OVS-DPDK: http://docs.openvswitch.org/en/latest/intro/install/dpdk/ +.. _devstack: https://docs.openstack.org/devstack/pike/> Abstract -------- -The Network Service Benchmarking (NSB) extends the yardstick framework to do -VNF characterization and benchmarking in three different execution -environments viz., bare metal i.e. native Linux environment, standalone virtual -environment and managed virtualized environment (e.g. Open stack etc.). -It also brings in the capability to interact with external traffic generators -both hardware & software based for triggering and validating the traffic -according to user defined profiles. - The steps needed to run Yardstick with NSB testing are: * Install Yardstick (NSB Testing). -* Setup/Reference pod.yaml describing Test topology -* Create/Reference the test configuration yaml file. +* Setup/reference ``pod.yaml`` describing Test topology +* Create/reference the test configuration yaml file. * Run the test case. - Prerequisites ------------- -Refer chapter Yardstick Installation for more information on yardstick -prerequisites +Refer to :doc:`04-installation` for more information on Yardstick +prerequisites. Several prerequisites are needed for Yardstick (VNF testing): @@ -57,11 +52,10 @@ Several prerequisites are needed for Yardstick (VNF testing): * intel-cmt-cat Hardware & Software Ingredients -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ SUT requirements: - ======= =================== Item Description ======= =================== @@ -74,7 +68,6 @@ SUT requirements: Boot and BIOS settings: - ============= ================================================= Boot settings default_hugepagesz=1G hugepagesz=1G hugepages=16 hugepagesz=2M hugepages=2048 isolcpus=1-11,22-33 @@ -93,29 +86,25 @@ Boot and BIOS settings: Turbo Boost Disabled ============= ================================================= - - Install Yardstick (NSB Testing) ------------------------------- -Download the source code and install Yardstick from it +Download the source code and check out the latest stable branch:: .. code-block:: console git clone https://gerrit.opnfv.org/gerrit/yardstick - cd yardstick - # Switch to latest stable branch - # git checkout <tag or stable branch> - git checkout stable/euphrates + git checkout stable/gambia Configure the network proxy, either using the environment variables or setting -the global environment file: +the global environment file. + +* Set environment -.. code-block:: ini +.. code-block:: - cat /etc/environment http_proxy='http://proxy.company.com:port' https_proxy='http://proxy.company.com:port' @@ -124,14 +113,11 @@ the global environment file: export http_proxy='http://proxy.company.com:port' export https_proxy='http://proxy.company.com:port' -The last step is to modify the Yardstick installation inventory, used by -Ansible: - -.. code-block:: ini +Modify the Yardstick installation inventory, used by Ansible:: cat ./ansible/install-inventory.ini [jumphost] - localhost ansible_connection=local + localhost ansible_connection=local [yardstick-standalone] yardstick-standalone-node ansible_host=192.168.1.2 @@ -148,35 +134,29 @@ Ansible: .. note:: - SSH access without password needs to be configured for all your nodes defined in - ``install-inventory.ini`` file. - If you want to use password authentication you need to install sshpass - - .. code-block:: console + SSH access without password needs to be configured for all your nodes + defined in ``yardstick-install-inventory.ini`` file. + If you want to use password authentication you need to install ``sshpass``:: sudo -EH apt-get install sshpass -To execute an installation for a Bare-Metal or a Standalone context: - -.. code-block:: console +To execute an installation for a BareMetal or a Standalone context:: ./nsb_setup.sh -To execute an installation for an OpenStack context: - -.. code-block:: console +To execute an installation for an OpenStack context:: ./nsb_setup.sh <path to admin-openrc.sh> -Above command setup docker with latest yardstick code. To execute - -.. code-block:: console +The above commands will set up Docker with the latest Yardstick code. To +execute:: docker exec -it yardstick bash It will also automatically download all the packages needed for NSB Testing -setup. Refer chapter :doc:`04-installation` for more on docker +setup. Refer chapter :doc:`04-installation` for more on Docker + **Install Yardstick using Docker (recommended)** Another way to execute an installation for a Bare-Metal or a Standalone context @@ -201,24 +181,22 @@ System Topology Environment parameters and credentials -------------------------------------- -Config yardstick conf -~~~~~~~~~~~~~~~~~~~~~ +Configure yardstick.conf +^^^^^^^^^^^^^^^^^^^^^^^^ -If user did not run 'yardstick env influxdb' inside the container, which will -generate correct ``yardstick.conf``, then create the config file manually (run -inside the container): -:: +If you did not run ``yardstick env influxdb`` inside the container to generate + ``yardstick.conf``, then create the config file manually (run inside the +container):: cp ./etc/yardstick/yardstick.conf.sample /etc/yardstick/yardstick.conf vi /etc/yardstick/yardstick.conf -Add trex_path, trex_client_lib and bin_path in 'nsb' section. - -:: +Add ``trex_path``, ``trex_client_lib`` and ``bin_path`` to the ``nsb`` +section:: [DEFAULT] debug = True - dispatcher = file, influxdb + dispatcher = influxdb [dispatcher_influxdb] timeout = 5 @@ -235,25 +213,32 @@ Add trex_path, trex_client_lib and bin_path in 'nsb' section. Run Yardstick - Network Service Testcases ----------------------------------------- - NS testing - using yardstick CLI -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ See :doc:`04-installation` -.. code-block:: console - +Connect to the Yardstick container:: docker exec -it yardstick /bin/bash - source /etc/yardstick/openstack.creds (only for heat TC if nsb_setup.sh was NOT used) - export EXTERNAL_NETWORK="<openstack public network>" (only for heat TC) + +If you're running ``heat`` testcases and ``nsb_setup.sh`` was not used:: + source /etc/yardstick/openstack.creds + +In addition to the above, you need to se the ``EXTERNAL_NETWORK`` for +OpenStack:: + + export EXTERNAL_NETWORK="<openstack public network>" + +Finally, you should be able to run the testcase:: + yardstick --debug task start yardstick/samples/vnf_samples/nsut/<vnf>/<test case> Network Service Benchmarking - Bare-Metal ----------------------------------------- Bare-Metal Config pod.yaml describing Topology -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Bare-Metal 2-Node setup +++++++++++++++++++++++ @@ -284,8 +269,8 @@ Bare-Metal 3-Node setup - Correlated Traffic Bare-Metal Config pod.yaml -~~~~~~~~~~~~~~~~~~~~~~~~~~ -Before executing Yardstick test cases, make sure that pod.yaml reflects the +^^^^^^^^^^^^^^^^^^^^^^^^^^ +Before executing Yardstick test cases, make sure that ``pod.yaml`` reflects the topology and update all the required fields.:: cp /etc/yardstick/nodes/pod.yaml.nsb.sample /etc/yardstick/nodes/pod.yaml @@ -358,22 +343,20 @@ topology and update all the required fields.:: if: "xe1" -Network Service Benchmarking - Standalone Virtualization --------------------------------------------------------- +Standalone Virtualization +------------------------- SR-IOV -~~~~~~ +^^^^^^ SR-IOV Pre-requisites +++++++++++++++++++++ On Host, where VM is created: - a) Create and configure a bridge named ``br-int`` for VM to connect to external network. - Currently this can be done using VXLAN tunnel. + a) Create and configure a bridge named ``br-int`` for VM to connect to + external network. Currently this can be done using VXLAN tunnel. - Execute the following on host, where VM is created: - - .. code-block:: console + Execute the following on host, where VM is created:: ip link add type vxlan remote <Jumphost IP> local <DUT IP> id <ID: 10> dstport 4789 brctl addbr br-int @@ -382,7 +365,7 @@ On Host, where VM is created: ip addr add <IP#1, like: 172.20.2.1/24> dev br-int ip link set dev br-int up - .. note:: May be needed to add extra rules to iptable to forward traffic. + .. note:: You may need to add extra rules to iptable to forward traffic. .. code-block:: console @@ -416,23 +399,24 @@ On Host, where VM is created: Yardstick has a tool for building this custom image with SampleVNF. It is necessary to have ``sudo`` rights to use this tool. - Also you may need to install several additional packages to use this tool, by - following the commands below:: + Also you may need to install several additional packages to use this tool, by + following the commands below:: - sudo apt-get update && sudo apt-get install -y qemu-utils kpartx + sudo apt-get update && sudo apt-get install -y qemu-utils kpartx - This image can be built using the following command in the directory where Yardstick is installed + This image can be built using the following command in the directory where + Yardstick is installed:: - .. code-block:: console + export YARD_IMG_ARCH='amd64' + sudo echo "Defaults env_keep += \'YARD_IMG_ARCH\'" >> /etc/sudoers - export YARD_IMG_ARCH='amd64' - sudo echo "Defaults env_keep += \'YARD_IMG_ARCH\'" >> /etc/sudoers + For instructions on generating a cloud image using Ansible, refer to + :doc:`04-installation`. - Please use ansible script to generate a cloud image refer to :doc:`04-installation` + for more details refer to chapter :doc:`04-installation` - for more details refer to chapter :doc:`04-installation` - - .. note:: VM should be build with static IP and should be accessible from yardstick host. + .. note:: VM should be build with static IP and be accessible from the + Yardstick host. SR-IOV Config pod.yaml describing Topology @@ -457,10 +441,10 @@ SR-IOV 2-Node setup +----------+ +-------------------------+ | | | ^ ^ | | | | | | | - | | (0)<----->(0) | ------ | | - | TG1 | | SUT | | - | | | | | - | | (n)<----->(n) |------------------ | + | | (0)<----->(0) | ------ SUT | | + | TG1 | | | | + | | (n)<----->(n) | ----------------- | + | | | | +----------+ +-------------------------+ trafficgen_1 host @@ -470,29 +454,29 @@ SR-IOV 3-Node setup - Correlated Traffic ++++++++++++++++++++++++++++++++++++++++ .. code-block:: console - +--------------------+ - | | - | | - | DUT | - | (VNF) | - | | - +--------------------+ - | VF NIC | | VF NIC | - +--------+ +--------+ - ^ ^ - | | - | | - +----------+ +-------------------------+ +--------------+ - | | | ^ ^ | | | - | | | | | | | | - | | (0)<----->(0) | ------ | | | TG2 | - | TG1 | | SUT | | | (UDP Replay) | - | | | | | | | - | | (n)<----->(n) | ------ | (n)<-->(n) | | - +----------+ +-------------------------+ +--------------+ - trafficgen_1 host trafficgen_2 - -Before executing Yardstick test cases, make sure that pod.yaml reflects the + +--------------------+ + | | + | | + | DUT | + | (VNF) | + | | + +--------------------+ + | VF NIC | | VF NIC | + +--------+ +--------+ + ^ ^ + | | + | | + +----------+ +---------------------+ +--------------+ + | | | ^ ^ | | | + | | | | | | | | + | | (0)<----->(0) |----- | | | TG2 | + | TG1 | | SUT | | | (UDP Replay) | + | | | | | | | + | | (n)<----->(n) | -----| (n)<-->(n) | | + +----------+ +---------------------+ +--------------+ + trafficgen_1 host trafficgen_2 + +Before executing Yardstick test cases, make sure that ``pod.yaml`` reflects the topology and update all the required fields. .. code-block:: console @@ -547,8 +531,8 @@ SR-IOV Config host_sriov.yaml SR-IOV testcase update: ``<yardstick>/samples/vnf_samples/nsut/vfw/tc_sriov_rfc2544_ipv4_1rule_1flow_64B_trex.yaml`` -Update "contexts" section -''''''''''''''''''''''''' +Update contexts section +''''''''''''''''''''''' .. code-block:: YAML @@ -591,16 +575,15 @@ Update "contexts" section gateway_ip: '152.16.100.20' - OVS-DPDK -~~~~~~~~ +^^^^^^^^ OVS-DPDK Pre-requisites -~~~~~~~~~~~~~~~~~~~~~~~ ++++++++++++++++++++++++ On Host, where VM is created: - a) Create and configure a bridge named ``br-int`` for VM to connect to external network. - Currently this can be done using VXLAN tunnel. + a) Create and configure a bridge named ``br-int`` for VM to connect to + external network. Currently this can be done using VXLAN tunnel. Execute the following on host, where VM is created: @@ -647,26 +630,27 @@ On Host, where VM is created: Yardstick has a tool for building this custom image with SampleVNF. It is necessary to have ``sudo`` rights to use this tool. - Also you may need to install several additional packages to use this tool, by - following the commands below:: + You may need to install several additional packages to use this tool, by + following the commands below:: - sudo apt-get update && sudo apt-get install -y qemu-utils kpartx + sudo apt-get update && sudo apt-get install -y qemu-utils kpartx - This image can be built using the following command in the directory where Yardstick is installed:: + This image can be built using the following command in the directory where + Yardstick is installed:: - export YARD_IMG_ARCH='amd64' - sudo echo "Defaults env_keep += \'YARD_IMG_ARCH\'" >> /etc/sudoers - sudo tools/yardstick-img-dpdk-modify tools/ubuntu-server-cloudimg-samplevnf-modify.sh + export YARD_IMG_ARCH='amd64' + sudo echo "Defaults env_keep += \'YARD_IMG_ARCH\'" >> /etc/sudoers + sudo tools/yardstick-img-dpdk-modify tools/ubuntu-server-cloudimg-samplevnf-modify.sh - for more details refer to chapter :doc:`04-installation` + for more details refer to chapter :doc:`04-installation` - .. note:: VM should be build with static IP and should be accessible from yardstick host. + .. note:: VM should be build with static IP and should be accessible from + yardstick host. - c) OVS & DPDK version. - - OVS 2.7 and DPDK 16.11.1 above version is supported +3. OVS & DPDK version. + * OVS 2.7 and DPDK 16.11.1 above version is supported - d) Setup OVS/DPDK on host. - Please refer to below link on how to setup `OVS-DPDK <http://docs.openvswitch.org/en/latest/intro/install/dpdk/>`_ +4. Setup `OVS-DPDK`_ on host. OVS-DPDK Config pod.yaml describing Topology @@ -732,10 +716,8 @@ OVS-DPDK 3-Node setup - Correlated Traffic trafficgen_1 host trafficgen_2 -Before executing Yardstick test cases, make sure that pod.yaml reflects the -topology and update all the required fields. - -.. code-block:: console +Before executing Yardstick test cases, make sure that the ``pod.yaml`` reflects +the topology and update all the required fields:: cp <yardstick>/etc/yardstick/nodes/standalone/trex_bm.yaml.sample /etc/yardstick/nodes/standalone/pod_trex.yaml cp <yardstick>/etc/yardstick/nodes/standalone/host_ovs.yaml /etc/yardstick/nodes/standalone/host_ovs.yaml @@ -786,8 +768,8 @@ OVS-DPDK Config host_ovs.yaml ovs_dpdk testcase update: ``<yardstick>/samples/vnf_samples/nsut/vfw/tc_ovs_rfc2544_ipv4_1rule_1flow_64B_trex.yaml`` -Update "contexts" section -''''''''''''''''''''''''' +Update contexts section +''''''''''''''''''''''' .. code-block:: YAML @@ -841,16 +823,16 @@ Update "contexts" section gateway_ip: '152.16.100.20' -Network Service Benchmarking - OpenStack with SR-IOV support ------------------------------------------------------------- +OpenStack with SR-IOV support +----------------------------- This section describes how to run a Sample VNF test case, using Heat context, with SR-IOV. It also covers how to install OpenStack in Ubuntu 16.04, using DevStack, with SR-IOV support. -Single node OpenStack setup with external TG -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Single node OpenStack with external TG +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: console @@ -883,26 +865,22 @@ Single node OpenStack setup with external TG Host pre-configuration ++++++++++++++++++++++ -.. warning:: The following configuration requires sudo access to the system. Make - sure that your user have the access. +.. warning:: The following configuration requires sudo access to the system. + Make sure that your user have the access. -Enable the Intel VT-d or AMD-Vi extension in the BIOS. Some system manufacturers -disable this extension by default. +Enable the Intel VT-d or AMD-Vi extension in the BIOS. Some system +manufacturers disable this extension by default. Activate the Intel VT-d or AMD-Vi extension in the kernel by modifying the GRUB config file ``/etc/default/grub``. -For the Intel platform: - -.. code:: bash +For the Intel platform:: ... GRUB_CMDLINE_LINUX_DEFAULT="intel_iommu=on" ... -For the AMD platform: - -.. code:: bash +For the AMD platform:: ... GRUB_CMDLINE_LINUX_DEFAULT="amd_iommu=on" @@ -917,9 +895,7 @@ Update the grub configuration file and restart the system: sudo update-grub sudo reboot -Make sure the extension has been enabled: - -.. code:: bash +Make sure the extension has been enabled:: sudo journalctl -b 0 | grep -e IOMMU -e DMAR @@ -932,6 +908,8 @@ Make sure the extension has been enabled: Feb 06 14:50:14 hostname kernel: DMAR: dmar1: reg_base_addr e0ffc000 ver 1:0 cap 8d2078c106f0466 ecap f020de Feb 06 14:50:14 hostname kernel: DMAR: DRHD base: 0x000000ee7fc000 flags: 0x0 +.. TODO: Refer to the yardstick installation guide for proxy set up + Setup system proxy (if needed). Add the following configuration into the ``/etc/environment`` file: @@ -954,13 +932,11 @@ Upgrade the system: sudo -EH apt-get upgrade sudo -EH apt-get dist-upgrade -Install dependencies needed for the DevStack +Install dependencies needed for DevStack .. code:: bash - sudo -EH apt-get install python - sudo -EH apt-get install python-dev - sudo -EH apt-get install python-pip + sudo -EH apt-get install python python-dev python-pip Setup SR-IOV ports on the host: @@ -983,10 +959,10 @@ Setup SR-IOV ports on the host: DevStack installation +++++++++++++++++++++ -Use official `Devstack <https://docs.openstack.org/devstack/pike/>`_ -documentation to install OpenStack on a host. Please note, that stable -``pike`` branch of devstack repo should be used during the installation. -The required `local.conf`` configuration file are described below. +If you want to try out NSB, but don't have OpenStack set-up, you can use +`Devstack`_ to install OpenStack on a host. Please note, that the +``stable/pike`` branch of devstack repo should be used during the installation. +The required ``local.conf`` configuration file are described below. DevStack configuration file: @@ -1001,15 +977,13 @@ DevStack configuration file: Start the devstack installation on a host. - TG host configuration +++++++++++++++++++++ -Yardstick automatically install and configure Trex traffic generator on TG +Yardstick automatically installs and configures Trex traffic generator on TG host based on provided POD file (see below). Anyway, it's recommended to check -the compatibility of the installed NIC on the TG server with software Trex using -the manual at https://trex-tgn.cisco.com/trex/doc/trex_manual.html. - +the compatibility of the installed NIC on the TG server with software Trex +using the `manual <https://trex-tgn.cisco.com/trex/doc/trex_manual.html>`_. Run the Sample VNF test case ++++++++++++++++++++++++++++ @@ -1018,7 +992,7 @@ There is an example of Sample VNF test case ready to be executed in an OpenStack environment with SR-IOV support: ``samples/vnf_samples/nsut/vfw/ tc_heat_sriov_external_rfc2544_ipv4_1rule_1flow_64B_trex.yaml``. -Install yardstick using `Install Yardstick (NSB Testing)`_ steps for OpenStack +Install Yardstick using `Install Yardstick (NSB Testing)`_ steps for OpenStack context. Create pod file for TG in the yardstick repo folder located in the yardstick @@ -1071,16 +1045,14 @@ Controller/Compute pre-configuration ++++++++++++++++++++++++++++++++++++ Pre-configuration of the controller and compute hosts are the same as -described in `Host pre-configuration`_ section. Follow the steps in the section. - +described in `Host pre-configuration`_ section. DevStack configuration ++++++++++++++++++++++ -Use official `Devstack <https://docs.openstack.org/devstack/pike/>`_ -documentation to install OpenStack on a host. Please note, that stable -``pike`` branch of devstack repo should be used during the installation. -The required `local.conf`` configuration file are described below. +A reference ``local.conf`` for deploying OpenStack in a multi-host environment +using `Devstack`_ is shown in this section. The ``stable/pike`` branch of +devstack repo should be used during the installation. .. note:: Update the devstack configuration files by replacing angluar brackets with a short description inside. @@ -1100,17 +1072,17 @@ DevStack configuration file for compute host: Start the devstack installation on the controller and compute hosts. - Run the sample vFW TC +++++++++++++++++++++ -Install yardstick using `Install Yardstick (NSB Testing)`_ steps for OpenStack +Install Yardstick using `Install Yardstick (NSB Testing)`_ steps for OpenStack context. -Run sample vFW RFC2544 SR-IOV TC (``samples/vnf_samples/nsut/vfw/ -tc_heat_rfc2544_ipv4_1rule_1flow_64B_trex.yaml``) in the heat -context using steps described in `NS testing - using yardstick CLI`_ section -and the following yardtick command line arguments: +Run the sample vFW RFC2544 SR-IOV test case +(``samples/vnf_samples/nsut/vfw/tc_heat_rfc2544_ipv4_1rule_1flow_64B_trex.yaml``) +in the heat context using steps described in +`NS testing - using yardstick CLI`_ section and the following Yardstick command +line arguments: .. code:: bash @@ -1118,8 +1090,8 @@ and the following yardtick command line arguments: samples/vnf_samples/nsut/vfw/tc_heat_rfc2544_ipv4_1rule_1flow_64B_trex.yaml -Enabling other Traffic generator --------------------------------- +Enabling other Traffic generators +--------------------------------- IxLoad ~~~~~~ @@ -1138,14 +1110,16 @@ IxLoad .. code-block:: console - cp <repo>/etc/yardstick/nodes/pod.yaml.nsb.sample.ixia etc/yardstick/nodes/pod_ixia.yaml + cp <repo>/etc/yardstick/nodes/pod.yaml.nsb.sample.ixia \ + etc/yardstick/nodes/pod_ixia.yaml Config ``pod_ixia.yaml`` .. literalinclude:: code/pod_ixia.yaml :language: console - for sriov/ovs_dpdk pod files, please refer to above Standalone Virtualization for ovs-dpdk/sriov configuration + for sriov/ovs_dpdk pod files, please refer to `Standalone Virtualization`_ + for ovs-dpdk/sriov configuration 3. Start IxOS TCL Server (Install 'Ixia IxExplorer IxOS <version>') You will also need to configure the IxLoad machine to start the IXIA @@ -1155,7 +1129,7 @@ IxLoad * Go to: ``Start->Programs->Ixia->IxOS->IxOS 8.01-GA-Patch1->Ixia Tcl Server IxOS 8.01-GA-Patch1`` or - ``"C:\Program Files (x86)\Ixia\IxOS\8.01-GA-Patch1\ixTclServer.exe"`` + ``C:\Program Files (x86)\Ixia\IxOS\8.01-GA-Patch1\ixTclServer.exe`` 4. Create a folder ``Results`` in c:\ and share the folder on the network. @@ -1163,7 +1137,7 @@ IxLoad ``<repo>/samples/vnf_samples/nsut/vfw/tc_baremetal_http_ixload_1b_Requests-65000_Concurrency.yaml`` IxNetwork -~~~~~~~~~ +^^^^^^^^^ IxNetwork testcases use IxNetwork API Python Bindings module, which is installed as part of the requirements of the project. @@ -1172,14 +1146,16 @@ installed as part of the requirements of the project. .. code-block:: console - cp <repo>/etc/yardstick/nodes/pod.yaml.nsb.sample.ixia etc/yardstick/nodes/pod_ixia.yaml + cp <repo>/etc/yardstick/nodes/pod.yaml.nsb.sample.ixia \ + etc/yardstick/nodes/pod_ixia.yaml - Config pod_ixia.yaml + Configure ``pod_ixia.yaml`` .. literalinclude:: code/pod_ixia.yaml :language: console - for sriov/ovs_dpdk pod files, please refer to above Standalone Virtualization for ovs-dpdk/sriov configuration + for sriov/ovs_dpdk pod files, please refer to above + `Standalone Virtualization`_ for ovs-dpdk/sriov configuration 2. Start IxNetwork TCL Server You will also need to configure the IxNetwork machine to start the IXIA diff --git a/docs/testing/user/userguide/14-nsb-operation.rst b/docs/testing/user/userguide/14-nsb-operation.rst index 7ec5b4ec0..12e269187 100644 --- a/docs/testing/user/userguide/14-nsb-operation.rst +++ b/docs/testing/user/userguide/14-nsb-operation.rst @@ -2,6 +2,16 @@ .. License. .. http://creativecommons.org/licenses/by/4.0 .. (c) OPNFV, 2016-2018 Intel Corporation. +.. + Convention for heading levels in Yardstick documentation: + + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ^^^^^^^ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. Yardstick - NSB Testing - Operation =================================== @@ -89,9 +99,9 @@ Availability zone ^^^^^^^^^^^^^^^^^ The configuration of the availability zone is requred in cases where location -of exact compute host/group of compute hosts needs to be specified for SampleVNF -or traffic generator in the heat test case. If this is the case, please follow -the instructions below. +of exact compute host/group of compute hosts needs to be specified for +:term:`SampleVNF` or traffic generator in the heat test case. If this is the +case, please follow the instructions below. .. _`Create a host aggregate`: @@ -105,7 +115,8 @@ the instructions below. .. code-block:: bash # create host aggregate - openstack aggregate create --zone <AZ_NAME> --property availability_zone=<AZ_NAME> <AGG_NAME> + openstack aggregate create --zone <AZ_NAME> \ + --property availability_zone=<AZ_NAME> <AGG_NAME> # show available hosts openstack compute service list --service nova-compute # add selected host into the host aggregate @@ -136,8 +147,9 @@ the instructions below. networks: ... -There are two example of SampleVNF scale out test case which use the availability zone -feature to specify the exact location of scaled VNFs and traffic generators. +There are two example of SampleVNF scale out test case which use the +``availability zone`` feature to specify the exact location of scaled VNFs and +traffic generators. Those are: @@ -164,21 +176,19 @@ Those are: | 5 | agg1 | AZ_NAME_1 | +----+------+-------------------+ -2. If no host aggregates are configured, please use `steps above`__ to - configure them. +2. If no host aggregates are configured, please follow the instructions to + `Create a host aggregate`_ -__ `Create a host aggregate`_ - -3. Run the SampleVNF PROX scale-out test case, specifying the availability - zone of each VNF and traffic generator as a task arguments. +3. Run the SampleVNF PROX scale-out test case, specifying the + ``availability zone`` of each VNF and traffic generator as task arguments. .. note:: The ``az_0`` and ``az_1`` should be changed according to the host - aggregates created in the OpenStack. + aggregates created in the OpenStack. .. code-block:: console - yardstick -d task start\ + yardstick -d task start \ <repo>/samples/vnf_samples/nsut/prox/tc_prox_heat_context_l2fwd_multiflow-2-scale-out.yaml\ --task-args='{ "num_vnfs": 4, "availability_zone": { @@ -198,7 +208,7 @@ Collectd KPIs ------------- NSB can collect KPIs from collected. We have support for various plugins -enabled by the Barometer project. +enabled by the :term:`Barometer` project. The default yardstick-samplevnf has collectd installed. This allows for collecting KPIs from the VNF. @@ -208,12 +218,11 @@ We assume that collectd is not installed on the compute nodes. To collectd KPIs from the NFVi compute nodes: - * install_collectd on the compute nodes * create pod.yaml for the compute nodes * enable specific plugins depending on the vswitch and DPDK - example pod.yaml section for Compute node running collectd. + example ``pod.yaml`` section for Compute node running collectd. .. code-block:: yaml @@ -356,8 +365,8 @@ Scale-Out VNFs performance data with scale-out helps - * in capacity planning to meet the given network node requirements - * in comparison between different VNF vendor offerings + * capacity planning to meet the given network node requirements + * comparison between different VNF vendor offerings * better the scale-out index, provides the flexibility in meeting future capacity requirements @@ -488,11 +497,11 @@ Default values for OVS-DPDK: Sample test case file ^^^^^^^^^^^^^^^^^^^^^ - 1. Prepare SampleVNF image and copy it to ``flavor/images``. - 2. Prepare context files for TREX and SampleVNF under ``contexts/file``. - 3. Add bridge named ``br-int`` to the baremetal where SampleVNF image is deployed. - 4. Modify ``networks/phy_port`` accordingly to the baremetal setup. - 5. Run test from: +1. Prepare SampleVNF image and copy it to ``flavor/images``. +2. Prepare context files for TREX and SampleVNF under ``contexts/file``. +3. Add bridge named ``br-int`` to the baremetal where SampleVNF image is deployed. +4. Modify ``networks/phy_port`` accordingly to the baremetal setup. +5. Run test from: .. literalinclude:: /../samples/vnf_samples/nsut/acl/tc_ovs_rfc2544_ipv4_1rule_1flow_64B_trex.yaml :language: yaml @@ -601,3 +610,33 @@ may be changed. 2. Subsection ``runner``: specifies the test duration and the interval of TG and VNF side KPIs polling. For more details, refer to :doc:`03-architecture`. + +Preparing test run of vPE test case +----------------------------------- +The vPE (Provider Edge Router) is a :term: `VNF` approximation +serving as an Edge Router. The vPE is approximated using the +``ip_pipeline`` dpdk application. + + .. image:: images/vPE_Diagram.png + :width: 800px + :alt: NSB vPE Diagram + +The ``vpe_config`` file must be passed as it is not auto generated. +The ``vpe_script`` defines the rules applied to each of the pipelines. This can be +auto generated or a file can be passed using the ``script_file`` option in +``vnf_config`` as shown below. The ``full_tm_profile_file`` option must be +used if a traffic manager is defined in ``vpe_config``. + +.. code-block:: yaml + + vnf_config: { file: './vpe_config/vpe_config_2_ports', + action_bulk_file: './vpe_config/action_bulk_512.txt', + full_tm_profile_file: './vpe_config/full_tm_profile_10G.cfg', + script_file: './vpe_config/vpe_script_sample' } + +Testcases for vPE can be found in the ``vnf_samples/nsut/vpe`` directory. +A testcase can be started with the following command as an example: + +.. code-block:: bash + + yardstick task start /yardstick/samples/vnf_samples/nsut/vpe/tc_baremetal_rfc2544_ipv4_1flow_64B_ixia.yaml diff --git a/docs/testing/user/userguide/glossary.rst b/docs/testing/user/userguide/glossary.rst index 6a153943c..cef9b69a5 100644 --- a/docs/testing/user/userguide/glossary.rst +++ b/docs/testing/user/userguide/glossary.rst @@ -13,23 +13,54 @@ Glossary API Application Programming Interface + Barometer + OPNFV NFVi Service Assurance project. Barometer upstreams changes to + collectd, OpenStack, etc to improve features related to NFVi monitoring + and service assurance. + More info on: https://opnfv-barometer.readthedocs.io/en/latest/ + + collectd + collectd is a system statistics collection daemon. + More info on: https://collectd.org/ + + context + A context describes the environment in which a yardstick testcase will + be run. It can refer to a pre-provisioned environment, or an environment + that will be set up using OpenStack or Kubernetes. + Docker Docker provisions and manages containers. Yardstick and many other OPNFV projects are deployed in containers. Docker is required to launch the containerized versions of these projects. - DPI - Deep Packet Inspection - DPDK Data Plane Development Kit + DPI + Deep Packet Inspection + DSCP Differentiated Services Code Point + flavor + A specification of virtual resources used by OpenStack in the creation + of a VM instance. + + Grafana + A visualization tool, used in Yardstick to retrieve test data from + InfluxDB and display it. Grafana works by defining dashboards, which are + combinations of visualization panes (e.g. line charts and gauges) and + forms that assist the user in formulating SQL-like queries for InfluxDB. + More info on: https://grafana.com/ + IGMP Internet Group Management Protocol + InfluxDB + One of the Dispatchers supported by Yardstick, it allows test results to + be reported to a time-series database. + More info on: https://www.influxdata.com/ + IOPS Input/Output Operations Per Second A performance measurement used to benchmark storage devices. @@ -43,6 +74,9 @@ Glossary deployment, scaling and management of containerized applications. It is one of the contexts supported in Yardstick. + MPLS + Multiprotocol Label Switching + NFV Network Function Virtualization NFV is an initiative to take network services which were traditionally run @@ -56,6 +90,10 @@ Glossary NIC Network Interface Controller + NSB + Network Services Benchmarking. A subset of Yardstick features concerned + with NFVI and VNF characterization. + OpenStack OpenStack is a cloud operating system that controls pools of compute, storage, and networking resources. OpenStack is an open source project @@ -77,6 +115,18 @@ Glossary performance in Input/Output Operations Per Second (IOPS), throttling agreements, and performance expectations at peak load + runner + The part of a Yardstick testcase that determines how the test will be run + (e.g. for x iterations, y seconds or until state z is reached). The runner + also determines when the metrics are collected/reported. + + SampleVNF + OPNFV project providing a repository of reference VNFs. + More info on: https://opnfv-samplevnf.readthedocs.io/en/latest/ + + scenario + The part of a Yardstick testcase that describes each test step. + SLA Service Level Agreement An SLA is an agreement between a service provider and a customer to @@ -92,6 +142,10 @@ Glossary SUT System Under Test + testcase + A task in Yardstick; the yaml file that is read by Yardstick to + determine how to run a test. + ToS Type of Service diff --git a/docs/testing/user/userguide/nsb/nsb-list-of-tcs.rst b/docs/testing/user/userguide/nsb/nsb-list-of-tcs.rst index 723cd6f99..6c18c7d89 100644 --- a/docs/testing/user/userguide/nsb/nsb-list-of-tcs.rst +++ b/docs/testing/user/userguide/nsb/nsb-list-of-tcs.rst @@ -33,3 +33,6 @@ NSB PROX Test Case Descriptions tc_epc_saegw_tput_relocation_landslide tc_epc_network_service_request_landslide tc_epc_ue_service_request_landslide + tc_vfw_rfc2544 + tc_vfw_rfc2544_correlated + tc_vfw_rfc3511 diff --git a/docs/testing/user/userguide/nsb/tc_vfw_rfc2544.rst b/docs/testing/user/userguide/nsb/tc_vfw_rfc2544.rst new file mode 100644 index 000000000..139990bc3 --- /dev/null +++ b/docs/testing/user/userguide/nsb/tc_vfw_rfc2544.rst @@ -0,0 +1,189 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International +.. License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) OPNFV, 2018 Intel Corporation. + +************************************************ +Yardstick Test Case Description: NSB vFW RFC2544 +************************************************ + ++------------------------------------------------------------------------------+ +| NSB vFW test for VNF characterization | +| | ++---------------+--------------------------------------------------------------+ +| test case id | tc_{context}_rfc2544_ipv4_1rule_1flow_{pkt_size}_{tg_type} | +| | | +| | * context = baremetal, heat, heat_external, ovs, sriov | +| | heat_sriov_external contexts; | +| | * tg_type = ixia (context != heat,heat_sriov_external), | +| | trex; | +| | * pkt_size = 64B - all contexts; | +| | 128B, 256B, 512B, 1024B, 1280B, 1518B - | +| | (context = heat, tg_type = ixia) | +| | | ++---------------+--------------------------------------------------------------+ +| metric | * Network Throughput; | +| | * TG Packets Out; | +| | * TG Packets In; | +| | * TG Latency; | +| | * VNF Packets Out; | +| | * VNF Packets In; | +| | * VNF Packets Fwd; | +| | * Dropped packets; | +| | | ++---------------+--------------------------------------------------------------+ +| test purpose | The VFW RFC2544 tests measure performance characteristics of | +| | the SUT (multiple ports) and sends UDP bidirectional traffic | +| | from all TG ports to SampleVNF vFW application. The | +| | application forwards received traffic based on rules | +| | provided by the user in the TC configuration and default | +| | rules created by vFW to send traffic from uplink ports to | +| | downlink and voice versa. | +| | | ++---------------+--------------------------------------------------------------+ +| configuration | The 2 ports RFC2544 test cases are listed below: | +| | | +| | * tc_baremetal_rfc2544_ipv4_1rule_1flow_64B_ixia.yaml | +| | * tc_baremetal_rfc2544_ipv4_1rule_1flow_64B_trex.yaml | +| | * tc_heat_external_rfc2544_ipv4_1rule_1flow_1024B_ixia.yaml | +| | * tc_heat_external_rfc2544_ipv4_1rule_1flow_1280B_ixia.yaml | +| | * tc_heat_external_rfc2544_ipv4_1rule_1flow_128B_ixia.yaml | +| | * tc_heat_external_rfc2544_ipv4_1rule_1flow_1518B_ixia.yaml | +| | * tc_heat_external_rfc2544_ipv4_1rule_1flow_256B_ixia.yaml | +| | * tc_heat_external_rfc2544_ipv4_1rule_1flow_512B_ixia.yaml | +| | * tc_heat_external_rfc2544_ipv4_1rule_1flow_64B_ixia.yaml | +| | * tc_heat_external_rfc2544_ipv4_1rule_1flow_64B_trex.yaml | +| | * tc_heat_sriov_external_rfc2544_ipv4_1rule_1flow_64B_trex. | +| | yaml | +| | * tc_heat_rfc2544_ipv4_1rule_1flow_64B_trex.yaml | +| | * tc_ovs_rfc2544_ipv4_1rule_1flow_64B_ixia.yaml | +| | * tc_ovs_rfc2544_ipv4_1rule_1flow_64B_trex.yaml | +| | * tc_sriov_rfc2544_ipv4_1rule_1flow_64B_ixia.yaml | +| | * tc_sriov_rfc2544_ipv4_1rule_1flow_64B_trex.yaml | +| | | +| | The 4 ports RFC2544 test cases are listed below: | +| | | +| | * tc_baremetal_rfc2544_ipv4_1rule_1flow_64B_ixia_4port.yaml | +| | * tc_tc_baremetal_rfc2544_ipv4_1rule_1flow_64B_trex_4port. | +| | yaml | +| | * tc_tc_heat_external_rfc2544_ipv4_1rule_1flow_64B_trex_4 | +| | port.yaml | +| | * tc_tc_heat_rfc2544_ipv4_1rule_1flow_64B_trex_4port.yaml | +| | | +| | The scale-up RFC2544 test cases are listed below: | +| | | +| | * tc_tc_heat_rfc2544_ipv4_1rule_1flow_64B_trex_scale-up.yaml | +| | | +| | The scale-out RFC2544 test cases are listed below: | +| | | +| | * tc_heat_rfc2544_ipv4_1rule_1flow_64B_trex_scale_out.yaml | +| | | +| | Test duration is set as 30 sec for each test and default | +| | number of rules are applied. These can be configured | +| | | ++---------------+--------------------------------------------------------------+ +| test tool | The vFW is a DPDK application that performs basic filtering | +| | for malformed packets and dynamic packet filtering of | +| | incoming packets using the connection tracker library. | +| | | ++---------------+--------------------------------------------------------------+ +| applicability | The vFW RFC2544 test cases can be configured with different: | +| | | +| | * packet sizes; | +| | * test duration; | +| | * tolerated loss; | +| | * traffic flows; | +| | * rules; | +| | | +| | Default values exist. | +| | | ++---------------+--------------------------------------------------------------+ +| pre-test | For OpenStack test case image (yardstick-samplevnf) needs | +| conditions | to be installed into Glance with vFW and DPDK included in | +| | it (NSB install). | +| | | +| | For Baremetal tests cases vFW and DPDK must be installed on | +| | the hosts where the test is executed. The pod.yaml file must | +| | have the necessary system and NIC information. | +| | | +| | For standalone (SA) SRIOV/OvS test cases the | +| | yardstick-samplevnf image needs to be installed on hosts and | +| | pod.yaml file must be provided with necessary system, NIC | +| | information. | +| | | ++---------------+--------------------------------------------------------------+ +| test sequence | Description and expected result | +| | | ++---------------+--------------------------------------------------------------+ +| step 1 | For Baremetal test: The TG (except IXIA) and VNF are started | +| | on the hosts based on the pod file. | +| | | +| | For Heat test: Two host VMs are booted, as Traffic generator | +| | and VNF(vFW) based on the test flavor. In case of scale-out | +| | scenario the multiple VNF VMs will be started. | +| | | +| | For Heat external test: vFW VM is booted and TG (except IXIA)| +| | generator is started on the external host based on the pod | +| | file. In case of scale-out scenario the multiple VNF VMs | +| | will be deployed. | +| | | +| | For Heat SRIOV external test: vFW VM is booted with network | +| | interfaces of `direct` type which are mapped to VFs that are | +| | available to OpenStack. TG (except IXIA) is started on the | +| | external host based on the pod file. In case of scale-out | +| | scenario the multiple VNF VMs will be deployed. | +| | | +| | For SRIOV test: VF ports are created on host's PFs specified | +| | in the TC file and VM is booed using those ports and image | +| | provided in the configuration. TG (except IXIA) is started | +| | on other host connected to VNF machine based on the pod | +| | file. The vFW is started in the booted VM. In case of | +| | scale-out scenario the multiple VNF VMs will be created. | +| | | +| | For OvS-DPDK test: OvS DPDK switch is started and bridges | +| | are created with ports specified in the TC file. DPDK vHost | +| | ports are added to corresponding bridge and VM is booed | +| | using those ports and image provided in the configuration. | +| | TG (except IXIA) is started on other host connected to VNF | +| | machine based on the pod file. The vFW is started in the | +| | booted VM. In case of scale-out scenario the multiple VNF | +| | VMs will be deployed. | +| | | ++---------------+--------------------------------------------------------------+ +| step 2 | Yardstick is connected with the TG and VNF by using ssh (in | +| | case of IXIA TG is connected via TCL interface). The test | +| | will resolve the topology and instantiate all VNFs | +| | and TG and collect the KPI's/metrics. | +| | | ++---------------+--------------------------------------------------------------+ +| step 3 | The TG will send packets to the VNFs. If the number of | +| | dropped packets is more than the tolerated loss the line | +| | rate or throughput is halved. This is done until the dropped | +| | packets are within an acceptable tolerated loss. | +| | | +| | The KPI is the number of packets per second for different | +| | packet size with an accepted minimal packet loss for the | +| | default configuration. | +| | | ++---------------+--------------------------------------------------------------+ +| step 4 | In Baremetal test: The test quits the application and unbind | +| | the DPDK ports. | +| | | +| | In Heat test: All VNF VMs and TG are deleted on test | +| | completion. | +| | | +| | In SRIOV test: The deployed VM with vFW is destroyed on the | +| | host and TG (exclude IXIA) is stopped. | +| | | +| | In Heat SRIOV test: The deployed VM with vFW is destroyed, | +| | VFs are released and TG (exclude IXIA) is stopped. | +| | | +| | In OvS test: The deployed VM with vFW is destroyed on the | +| | host and OvS DPDK switch is stopped and ports are unbinded. | +| | The TG (exclude IXIA) is stopped. | +| | | ++---------------+--------------------------------------------------------------+ +| test verdict | The test case will achieve a Throughput with an accepted | +| | minimal tolerated packet loss. | ++---------------+--------------------------------------------------------------+ + diff --git a/docs/testing/user/userguide/nsb/tc_vfw_rfc2544_correlated.rst b/docs/testing/user/userguide/nsb/tc_vfw_rfc2544_correlated.rst new file mode 100644 index 000000000..de490900d --- /dev/null +++ b/docs/testing/user/userguide/nsb/tc_vfw_rfc2544_correlated.rst @@ -0,0 +1,130 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International +.. License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) OPNFV, 2018 Intel Corporation. + +************************************************************* +Yardstick Test Case Description: NSB vFW RFC2544 (correlated) +************************************************************* + ++------------------------------------------------------------------------------+ +| NSB vFW test for VNF characterization using correlated traffic | +| | ++---------------+--------------------------------------------------------------+ +| test case id | tc_{context}_rfc2544_ipv4_1rule_1flow_64B_trex_corelated | +| | | +| | * context = baremetal, heat | +| | | ++---------------+--------------------------------------------------------------+ +| metric | * Network Throughput; | +| | * TG Packets Out; | +| | * TG Packets In; | +| | * TG Latency; | +| | * VNF Packets Out; | +| | * VNF Packets In; | +| | * VNF Packets Fwd; | +| | * Dropped packets; | +| | | +| | NOTE: For correlated TCs the TG metrics are available on | +| | uplink ports. | +| | | ++---------------+--------------------------------------------------------------+ +| test purpose | The VFW RFC2544 correlated tests measure performance | +| | characteristics of the SUT (multiple ports) and sends UDP | +| | traffic from uplink TG ports to SampleVNF vFW application. | +| | The application forwards received traffic from uplink ports | +| | to downlink ports based on rules provided by the user in the | +| | TC configuration and default rules created by vFW. The VNF | +| | downlink traffic is received by another UDPReplay VNF and it | +| | is mirrored back to the VNF on the same port. Finally, the | +| | traffic is received back to the TG uplink port. | +| | | ++---------------+--------------------------------------------------------------+ +| configuration | The 2 ports RFC2544 correlated test cases are listed below: | +| | | +| | * tc_baremetal_rfc2544_ipv4_1rule_1flow_64B_trex_corelated | +| | _traffic.yaml | +| | | +| | Multiple VNF (2, 4, 10) RFC2544 correlated test cases are | +| | listed below: | +| | | +| | * tc_heat_rfc2544_ipv4_1rule_1flow_64B_trex_correlated | +| | _scale_10.yaml | +| | * tc_heat_rfc2544_ipv4_1rule_1flow_64B_trex_correlated_scale | +| | _2.yaml | +| | * tc_heat_rfc2544_ipv4_1rule_1flow_64B_trex_correlated_scale | +| | _4.yaml | +| | | +| | The scale-out RFC2544 test cases are listed below: | +| | | +| | * tc_heat_rfc2544_ipv4_1rule_1flow_64B_trex_correlated_scale | +| | _out.yaml | +| | | +| | Test duration is set as 30 sec for each test and default | +| | number of rules are applied. These can be configured | +| | | ++---------------+--------------------------------------------------------------+ +| test tool | The vFW is a DPDK application that performs basic filtering | +| | for malformed packets and dynamic packet filtering of | +| | incoming packets using the connection tracker library. | +| | | ++---------------+--------------------------------------------------------------+ +| applicability | The vFW RFC2544 test cases can be configured with different: | +| | | +| | * packet sizes; | +| | * test duration; | +| | * tolerated loss; | +| | * traffic flows; | +| | * rules; | +| | | +| | Default values exist. | +| | | ++---------------+--------------------------------------------------------------+ +| pre-test | For OpenStack test case image (yardstick-samplevnf) needs | +| conditions | to be installed into Glance with vFW and DPDK included in | +| | it (NSB install). | +| | | +| | For Baremetal tests cases vFW and DPDK must be installed on | +| | the hosts where the test is executed. The pod.yaml file must | +| | have the necessary system and NIC information. | +| | | ++---------------+--------------------------------------------------------------+ +| test sequence | Description and expected result | +| | | ++---------------+--------------------------------------------------------------+ +| step 1 | For Baremetal test: The TG (except IXIA), vFW and UDPReplay | +| | VNFs are started on the hosts based on the pod file. | +| | | +| | For Heat test: Three host VMs are booted, as Traffic | +| | generator, vFW and UDPReplay VNF(vFW) based on the test | +| | flavor. In case of scale-out scenario the multiple vFW VNF | +| | VMs will be started. | +| | | ++---------------+--------------------------------------------------------------+ +| step 2 | Yardstick is connected with the TG, vFW and UDPReplay VNF by | +| | using ssh (in case of IXIA TG is connected via TCL | +| | interface). The test will resolve the topology and | +| | instantiate all VNFs and TG and collect the KPI's/metrics. | +| | | ++---------------+--------------------------------------------------------------+ +| step 3 | The TG will send packets to the VNFs. If the number of | +| | dropped packets is more than the tolerated loss the line | +| | rate or throughput is halved. This is done until the dropped | +| | packets are within an acceptable tolerated loss. | +| | | +| | The KPI is the number of packets per second for 64B packet | +| | size with an accepted minimal packet loss for the default | +| | configuration. | +| | | ++---------------+--------------------------------------------------------------+ +| step 4 | In Baremetal test: The test quits the application and unbind | +| | the DPDK ports. | +| | | +| | In Heat test: All VNF VMs and TG are deleted on test | +| | completion. | +| | | ++---------------+--------------------------------------------------------------+ +| test verdict | The test case will achieve a Throughput with an accepted | +| | minimal tolerated packet loss. | ++---------------+--------------------------------------------------------------+ + diff --git a/docs/testing/user/userguide/nsb/tc_vfw_rfc3511.rst b/docs/testing/user/userguide/nsb/tc_vfw_rfc3511.rst new file mode 100644 index 000000000..9051fc4df --- /dev/null +++ b/docs/testing/user/userguide/nsb/tc_vfw_rfc3511.rst @@ -0,0 +1,133 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International +.. License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) OPNFV, 2018 Intel Corporation. + +******************************************************* +Yardstick Test Case Description: NSB vFW RFC3511 (HTTP) +******************************************************* + ++------------------------------------------------------------------------------+ +| NSB vFW test for VNF characterization based on RFC3511 and IXIA | +| | ++---------------+--------------------------------------------------------------+ +| test case id | tc_{context}_http_ixload_{http_size}_Requests-65000_{type} | +| | | +| | * context = baremetal, heat_external | +| | * http_size = 1b, 4k, 64k, 256k, 512k, 1024k payload size | +| | * type = Concurrency, Connections, Throughput | +| | | ++---------------+--------------------------------------------------------------+ +| metric | * HTTP Total Throughput (Kbps); | +| | * HTTP Simulated Users; | +| | * HTTP Concurrent Connections; | +| | * HTTP Connection Rate; | +| | * HTTP Transaction Rate | +| | | ++---------------+--------------------------------------------------------------+ +| test purpose | The vFW RFC3511 tests measure performance characteristics of | +| | the SUT by sending the HTTP traffic from uplink to downlink | +| | TG ports through vFW VNF. The application forwards received | +| | traffic based on rules provided by the user in the TC | +| | configuration and default rules created by vFW to send | +| | traffic from uplink ports to downlink and voice versa. | +| | | ++---------------+--------------------------------------------------------------+ +| configuration | The 2 ports RFC3511 test cases are listed below: | +| | | +| | * tc_baremetal_http_ixload_1024k_Requests-65000 | +| | _Concurrency.yaml | +| | * tc_baremetal_http_ixload_1b_Requests-65000 | +| | _Concurrency.yaml | +| | * tc_baremetal_http_ixload_256k_Requests-65000 | +| | _Concurrency.yaml | +| | * tc_baremetal_http_ixload_4k_Requests-65000 | +| | _Concurrency.yaml | +| | * tc_baremetal_http_ixload_512k_Requests-65000 | +| | _Concurrency.yaml | +| | * tc_baremetal_http_ixload_64k_Requests-65000 | +| | _Concurrency.yaml | +| | * tc_heat_external_http_ixload_1b_Requests-10Gbps | +| | _Throughput.yaml | +| | * tc_heat_external_http_ixload_1b_Requests-65000 | +| | _Concurrency.yaml | +| | * tc_heat_external_http_ixload_1b_Requests-65000 | +| | _Connections.yaml | +| | | +| | The 4 ports RFC3511 test cases are listed below: | +| | | +| | * tc_baremetal_http_ixload_1b_Requests-65000 | +| | _Concurrency_4port.yaml | +| | | ++---------------+--------------------------------------------------------------+ +| test tool | The vFW is a DPDK application that performs basic filtering | +| | for malformed packets and dynamic packet filtering of | +| | incoming packets using the connection tracker library. | +| | | ++---------------+--------------------------------------------------------------+ +| applicability | The vFW RFC3511 test cases can be configured with different: | +| | | +| | * http payload sizes; | +| | * traffic flows; | +| | * rules; | +| | | +| | Default values exist. | +| | | ++---------------+--------------------------------------------------------------+ +| pre-test | For OpenStack test case image (yardstick-samplevnf) needs | +| conditions | to be installed into Glance with vFW and DPDK included in | +| | it (NSB install). | +| | | +| | For Baremetal tests cases vFW and DPDK must be installed on | +| | the hosts where the test is executed. The pod.yaml file must | +| | have the necessary system and NIC information. | +| | | ++---------------+--------------------------------------------------------------+ +| test sequence | Description and expected result | +| | | ++---------------+--------------------------------------------------------------+ +| step 1 | For Baremetal test: The vFW VNF is started on the hosts | +| | based on the pod file. | +| | | +| | For Heat external test: The vFW VM are deployed and booted. | +| | | ++---------------+--------------------------------------------------------------+ +| step 2 | Yardstick is connected with the TG (IxLoad) via IxLoad API | +| | and VNF by using ssh. The test will resolve the topology and | +| | instantiate all VNFs and TG and collect the KPI's/metrics. | +| | | ++---------------+--------------------------------------------------------------+ +| step 3 | The TG simulates HTTP traffic based on selected type of TC. | +| | | +| | Concurrency: | +| | The TC attempts to simulate some number of human users. | +| | The simulated users are gradually brought online until 64K | +| | users is met (the Ramp-Up phase), then taken offline (the | +| | Ramp Down phase). | +| | | +| | Connections: | +| | The TC creates some number of HTTP connections per second. | +| | It will attempt to generate the 64K of HTTP connections | +| | per second. | +| | | +| | Throughput: | +| | TC simultaneously transmits and receives TCP payload | +| | (bytes) at a certain rate measured in Megabits per second | +| | (Mbps), Kilobits per second (Kbps), or Gigabits per | +| | second. The 10 Gbits is default throughput. | +| | | +| | At the end of the TC, the KPIs are collected and stored | +| | (depends on the selected dispatcher). | +| | | ++---------------+--------------------------------------------------------------+ +| step 4 | In Baremetal test: The test quits the application and | +| | unbinds the DPDK ports. | +| | | +| | In Heat test: All VNF VMs are deleted and connections to TG | +| | are terminated. | +| | | ++---------------+--------------------------------------------------------------+ +| test verdict | The test case will try to achieve the configured HTTP | +| | Concurrency/Throughput/Connections. | ++---------------+--------------------------------------------------------------+ + |
