Merge "Docs: Adding preliminary documentation for Network Service Benchmarking."

1 files changed, 253 insertions, 0 deletions

diff --git a/docs/userguide/08-nsb_installation.rst b/docs/userguide/08-nsb_installation.rst
new file mode 100644
index 000000000..a390bb7d7
--- /dev/null
+++ b/docs/userguide/08-nsb_installation.rst
@@ -0,0 +1,253 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International
+.. License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) OPNFV, 2016-2017 Intel Corporation.
+
+Yardstick - NSB Testing -Installation
+=====================================
+
+Abstract
+--------
+
+Yardstick supports installation on Ubuntu 14.04 or via a Docker image. The
+installation procedure on Ubuntu 14.04 or via the docker image are detailed in
+the section below.
+
+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 pod.yaml describing Test topology
+* Create the test configuration yaml file.
+* Run the test case.
+
+
+Prerequisites
+-------------
+
+Refer chapter 08-instalaltion.rst for more information on yardstick
+prerequisites
+
+Several prerequisites are needed for Yardstick(VNF testing):
+* Python Modules: pyzmq, pika.
+* flex
+* bison
+* build-essential
+* automake
+* libtool
+* librabbitmq-dev
+* rabbitmq-server
+* collectd
+* intel-cmt-cat
+
+Installing Yardstick on Ubuntu 14.04
+------------------------------------
+
+.. _install-framework:
+
+You can install Yardstick framework directly on Ubuntu 14.04 or in an Ubuntu
+14.04 Docker image. No matter which way you choose to install Yardstick
+framework, the following installation steps are identical.
+
+If you choose to use the Ubuntu 14.04 Docker image, You can pull the Ubuntu
+14.04 Docker image from Docker hub:
+
+::
+
+  docker pull ubuntu:14.04
+
+Installing Yardstick framework
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Download source code and install python dependencies:
+
+::
+
+  git clone https://gerrit.opnfv.org/gerrit/yardstick
+  cd yardstick
+  ./nsb_setup.sh
+
+It will automatically download all the packages needed for NSB Testing setup.
+
+System Topology:
+-----------------
+
+.. code-block:: console
+
+  +----------+              +----------+
+  |          |              |          |
+  |          | (0)----->(0) |   Ping/  |
+  |    TG1   |              |   vPE/   |
+  |          |              |   2Trex  |
+  |          | (1)<-----(1) |          |
+  +----------+              +----------+
+  trafficgen_1                   vnf
+
+
+OpenStack parameters and credentials
+------------------------------------
+
+Environment variables
+^^^^^^^^^^^^^^^^^^^^^
+Before running Yardstick (NSB Testing) it is necessary to export traffic
+generator libraries.
+
+::
+  source ~/.bash_profile
+
+Config yardstick conf
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+cp ./etc/yardstick/yardstick.conf.sample /etc/yardstick/yardstick.conf
+
+vi /etc/yardstick/yardstick.conf
+
+Config yardstick.conf
+::
+
+  [DEFAULT]
+  debug = True
+  dispatcher = influxdb
+
+  [dispatcher_influxdb]
+  timeout = 5
+  target = http://{YOUR_IP_HERE}:8086
+  db_name = yardstick
+  username = root
+  password = root
+
+  [nsb]
+  trex_path=/opt/nsb_bin/trex/scripts
+  bin_path=/opt/nsb_bin
+
+
+Config pod.yaml describing Topology
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Before executing Yardstick test cases, make sure that pod.yaml reflects the
+topology and update all the required fields.
+
+copy /etc/yardstick/nodes/pod.yaml.nsb.example to /etc/yardstick/nodes/pod.yaml
+
+Config pod.yaml
+::
+    nodes:
+    -
+        name: trafficgen_1
+        role: TrafficGen
+        ip: 1.1.1.1
+        user: root
+        password: r00t
+        interfaces:
+            xe0:  # logical name from topology.yaml and vnfd.yaml
+                vpci:      "0000:07:00.0"
+                driver:    i40e # default kernel driver
+                dpdk_port_num: 0
+                local_ip: "152.16.100.20"
+                netmask:   "255.255.255.0"
+                local_mac: "00:00:00:00:00:01"
+            xe1:  # logical name from topology.yaml and vnfd.yaml
+                vpci:      "0000:07:00.1"
+                driver:    i40e # default kernel driver
+                dpdk_port_num: 1
+                local_ip: "152.16.40.20"
+                netmask:   "255.255.255.0"
+                local_mac: "00:00.00:00:00:02"
+
+    -
+        name: vnf
+        role: vnf
+        ip: 1.1.1.2
+        user: root
+        password: r00t
+        host: 1.1.1.2 #BM - host == ip, virtualized env - Host - compute node
+        interfaces:
+            xe0:  # logical name from topology.yaml and vnfd.yaml
+                vpci:      "0000:07:00.0"
+                driver:    i40e # default kernel driver
+                dpdk_port_num: 0
+                local_ip: "152.16.100.19"
+                netmask:   "255.255.255.0"
+                local_mac: "00:00:00:00:00:03"
+
+            xe1:  # logical name from topology.yaml and vnfd.yaml
+                vpci:      "0000:07:00.1"
+                driver:    i40e # default kernel driver
+                dpdk_port_num: 1
+                local_ip: "152.16.40.19"
+                netmask:   "255.255.255.0"
+                local_mac: "00:00:00:00:00:04"
+        routing_table:
+        - network: "152.16.100.20"
+          netmask: "255.255.255.0"
+          gateway: "152.16.100.20"
+          if: "xe0"
+        - network: "152.16.40.20"
+          netmask: "255.255.255.0"
+          gateway: "152.16.40.20"
+          if: "xe1"
+        nd_route_tbl:
+        - network: "0064:ff9b:0:0:0:0:9810:6414"
+          netmask: "112"
+          gateway: "0064:ff9b:0:0:0:0:9810:6414"
+          if: "xe0"
+        - network: "0064:ff9b:0:0:0:0:9810:2814"
+          netmask: "112"
+          gateway: "0064:ff9b:0:0:0:0:9810:2814"
+          if: "xe1"
+
+Enable yardstick virtual environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Before executing yardstick test cases, make sure to activate yardstick
+python virtual environment
+
+::
+    source /opt/nsb_bin/yardstick_venv/bin/activate
+
+
+Examples and verifying the install
+----------------------------------
+
+It is recommended to verify that Yardstick was installed successfully
+by executing some simple commands and test samples. Before executing yardstick
+test cases make sure yardstick flavor and building yardstick-trusty-server
+image can be found in glance and openrc file is sourced. Below is an example
+invocation of yardstick help command and ping.py test sample:
+::
+
+  yardstick –h
+  yardstick task start samples/ping.yaml
+
+Each testing tool supported by Yardstick has a sample configuration file.
+These configuration files can be found in the **samples** directory.
+
+Default location for the output is ``/tmp/yardstick.out``.
+
+
+Run Yardstick - Network Service Testcases
+-----------------------------------------
+
+NS testing - using NSBperf CLI
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+::
+
+  source /opt/nsb_setup/yardstick_venv/bin/activate
+  PYTHONPATH: ". ~/.bash_profile"
+  cd <yardstick_repo>/yardstick/cmd
+  Execute command: ./NSPerf.py -h
+      ./NSBperf.py --vnf <selected vnf> --test <rfc test>
+      eg: ./NSBperf.py --vnf vpe --test tc_baremetal_rfc2544_ipv4_1flow_64B.yaml
+
+NS testing - using yardstick CLI
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+::
+
+  source /opt/nsb_setup/yardstick_venv/bin/activate
+  PYTHONPATH: ". ~/.bash_profile"
+  Go to test case forlder type we want to execute.
+      e.g. <yardstick repo>/samples/vnf_samples/nsut/<vnf>/
+      run: yardstick --debug task start <test_case.yaml>