=== Introduction ====

The traffic generator working group is an adhoc, interdisciplinary working group focused on addressing the challenges of traffic generation, particularly as it relates to the challenges of test automation. It is not currently an approved OPNVF project nor is there a proposal planned at this time.

== Members ==
^ Name         ^ Email                     ^ Project       ^
| Gene Snider  | eugene.snider@huawei.com  | VSPEF           |
| Daniel Smith | daniel.smith@ericsson.com | FUEL/YARDSTICK  |


=== Problem Definition ===

The need for traffic generation is an implicit requirement for testing in OPNFV. Unfortunately there is no standard mechanism defined to support this, leaving each project to develop its own strategy. The challenge that the various PODs are not necessarily consistent and may ( or may not ) have one or more traffic generators installed. This makes it more difficult to code and implement a general purpose solution.

The problem is further complicated by the installation and configuration of required packages for managing external devices. Many of these are proprietary, licensed software which may not be freely distributed and even if they can be distributed many of labs or 3rd party users may not have the physical devices. Consequently they cannot be integrated into the standard installers for automation.

Additionally it is a common practice to install these on the DUT where they conflict with or impede performance and, at the very least, will compete for system resources. It also makes it impossible to automate the installation process in a way that will work for all users.

The goal of the Traffic Generator Working Group is to get all the interested parties talking and see if we can arrive at a common set of requirements and possibly a common solution for the installation and management of the traffic generator platform.

=== Proposed Solution - A toothpick in a anthill ===

== The Traffic Generator as a defined and supported platform ==
  - The traffic generator platform should be supported as a separate, supported device type
    * Because of the requirements for 3rd party vendors such as IXIA and Spirent we can recognize that the installation may never be fully automated but significant progress can still be made
  - It should be integrated with the existing installers such as Fuel and Compass to create a standardized basic install
    * The installer should lay down:
      * The base OS installation
      * Any supported Open Source software packet generators such as Moongen
      * Any supported 3rd party client libraries that can be legally distributed
      * The OPNFV traffic generator REST API for abstracting the TG interface

== A REST API Traffic Generator abstraction ==

A standardized TG platform is not, of itself, a complete solution. Traditional solutions would normally include some sort of client solution for the DUT or other test bed. The REST API proposal is intended to provide a standardized solution which can be leveraged by each project in a method consistent with that projects overall architecture and implementation.

The basic assumptions of the REST API are:
  * The primary output from a traffic generator is a data stream
  * There are a finite number of data streams used by testing, these can be identified in advance
  * The test infrastructure does not care about the underlying traffic generator implementation, they are only concerned with starting ( and stopping ) traffic in a particular data stream
  * The REST API implementation should also not be concerned with the underlying implementation

Based on these assumptions the REST API has two components. 
  * There is a standard REST API running on port 80 ( or whatever ) of the TG platform. This provides a uniform interface for OPNFV test infrastructures to leverage in a variety of ways including discovery of the installed traffic generators.
  * There is also a python based interface that provides the implementation solution. A preliminary version of this was developed by the VSPERF TOIT infrastructure and can be seen here: [[https://gerrit.opnfv.org/gerrit/gitweb?p=vswitchperf.git;a=blob_plain;f=core/traffic_controller.py|traffic_controller.py]]

== Initial REST API Draft Specification ==

|Title:|Get Traffic Generator Information| |
|URL:|/tg/v1/ or /tg/v1/:vendor or /tg/v1/:vendor/:model| |
|Method:|GET| |
|Header Params:|Optional:|AcceptType=json or html|
|URL Params:|Required:|N/A|
| |Optional:|vendor=[alphanumeric]|
| | |model=[alphanumeric]|
|Success Response:|HTTP Code:|200 - OK|
|URL: /tg/v1|Returns collection of installed PGs|
|URL: /tg/v1/:vendor|Returns collection of install models|
|URL: /tg/v1/:vendor/:model|Returns device specific configuration data|
|Error Response:|HTTP Code:|404 Not Found|
| |URL: /tg/v1|No traffic generators installed|
| |URL: /tg/v1/:vendor|No traffic generators installed for vendor|
| |URL: /tg/v1/:vendor/:model|Model not installed or no config data available|

|Title:|Configure Traffic Generator||
|URL:| /tg/v1/:vendor/:model or /tg/v1/:id||
|Method:|POST||
|Header Params:|Optional:|AcceptType=json or html|Default: HTML|
|URL Params:|Required:|vendor=[alphanumeric]|
| | |model=[alphanumeric]|
| | |OR|
| ||Id=[uuid]|
| |Optional:|N/A|
|Data Params:|Required:|TOIT Configuration parameters as JSON|
| |Optional:|N/A|
|Success Response:|HTTP Code:|200|
| |URL: /tg/v1/:vendor/:model|Returns device specific configuration data|
|Error Response:|HTTP Code:|404 Not Found|
| |URL: /tg/v1/:vendor/:model|Device not found. No additional data returned|
| |HTTP Code:|422 Unprocessable Entry|
| |URL: /tg/v1/:vendor/:model|Returns log message or debug info if available|

|Title:|Get Available Traffic Flows| |
|URL:| /tg/v1/flow/:id| |
|Method:|GET| |
|Header Params:|Optional:|AcceptType=json or html|Default: HTML|
|URL Params:|Required:|id=[uuid]|Traffic generator ID
| |Optional:|N/A|
|Data Params:|Required:|N/A|
| |Optional:|N/A|
|Success Response:|HTTP Code:|200|
| |URL: /tg/v1/flow|Returns collection of available flows|
|Error Response:|HTTP Code:|404 <96> Not Found|
| |URL: /tg/v1/flow|No available flows|

|Title:|Start Traffic Flow||
|URL:| /tg/v1/flow/:flow_id||
|Method:|POST| |
|Header Params:|Optional:|AcceptType=json or html|Default: HTML|
|URL Params:|Required:|flow_id=[uuid]|
| | |wait=[yes or no]|Wait for Completion|
| |Optional:|N/A|
|Data Params:|Required:|TOIT Configuration Params as JSON|
| |Optional:|N/A|
|Success Response:|HTTP Code:|200|
| |URL: /tg/v1/flow/:flow_id|flow_instance=[uuid]|
|Error Response:|HTTP Code:|404 <96> Not Found|
| |URL: /tg/v1/flow/:flow_id|No available flow|
| |HTTP Code:|422 Unprocessable Entry|
| |URL: /tg/v1/flow/:flow_id|Invalid parameters for traffic flow|

|Title:|Terminate Traffic Flow||
|URL:| /tg/v1/flow_instance/:flow_instance||
|Method:|PUT||
|Header Params:|Optional:|AcceptType=json or html|Default: HTML|
|URL Params:|Required:|flow_instance=[uuid]|
||Optional:|N/A|
|Data Params:|Required:|N/A|
| |Optional:|N/A|
|Success Response:|HTTP Code:|200|
| |URL: /tg/v1/test/:flow_instance||
|Error Response:|HTTP Code:|404 Not Found|
| |URL: /tg/v1/test/:flow_instance|No available flow|
| |HTTP Code:|422 Unprocessable Entry|
| |URL: /tg/v1/test/:flow_instance|Invalid parameters for traffic flow|

|Title:|Get Traffic Flow Results||
|URL:| /tg/v1/test/:flow_instance||
|Method:|GET||
|Header Params:|Optional:|AcceptType=json or html|Default: HTML|
|URL Params:|Required:|flow_instance=[uuid]|
| |Optional:|N/A|
|Data Params:|Required:|TOIT Configuration Params as JSON|
| |Optional:|N/A|
|Success Response:|HTTP Code:|200|
| |URL: /tg/v1/test/:flow_instance|Flow result data|
|Error Response:|HTTP Code:|404 Not Found|
| |URL: /tg/v1/test/:flow_instance|Instance no longer exists|

|Title:|Delete Traffic Flow ||
|URL:| /tg/v1/test/:flow_instance||
|Method:|GET||
|Header Params:|Optional:|AcceptType=json or html|Default: HTML|
|URL Params:|Required:|flow_instance=[uuid]|
| |Optional:|N/A|
|Data Params:|Required:|N/A|
| |Optional:|N/A|
|Success Response:|HTTP Code:|200|
| |URL: /tg/v1/test/:flow_instance|Flow result data|
|Error Response:|HTTP Code:|404 Not Found|
| |URL: /tg/v1/test/:flow_instance|Instance no longer exists|