**Welcome to SampleVNF's documentation !**
-.. _Pharos: https://wiki.opnfv.org/pharos
+.. _Pharos: https://wiki.opnfv.org/display/pharos
.. _SampleVNF: https://wiki.opnfv.org/samplevnf
-.. _Technical_Briefs: https://wiki.opnfv.org/display/SAM/Technical+Briefs+of+VNFs
SampleVNF_ is an OPNFV Project.
-The project's goal is to provides a placeholder for various sample VNF
+The project's goal was to provide a placeholder for various sample VNF
(Virtual Network Function (:term:`VNF`)) development which includes example
reference architecture and optimization methods related to VNF/Network service
-for high performance VNFs. This project provides benefits to other OPNFV
-projects like Functest, Models, yardstick etc to perform real life
-use-case based testing and VNF/ Network Function Virtualization Infrastructure
-(:term:`NFVI`) characterization for the same.
+for high performance VNFs.
+Today, we only maintain PROX and rapid scripts as part of this project
+to perform Network Function Virtualization Infrastructure
+(:term:`NFVI`) characterization.
-The Project's scope to create a repository of sample VNFs to help VNF
-benchmarking and NFVI characterization with real world traffic and host a
-common development environment for developing the VNF using optimized libraries.
-Also, develop a test framework in yardstick to enable VNF/NFVI verification.
+*SampleVNF* is used in OPNFV for characterization of NFVI on OPNFV infrastructure.
-*SampleVNF* is used in OPNFV for characterization of NFVI/VNF on OPNFV infrastructure
-and some of the OPNFV features.
-
-.. seealso:: Pharos_ for information on OPNFV community labs and this
- Technical_Briefs_ for an overview of *SampleVNF*
+.. seealso:: Pharos_ for information on OPNFV community labs
About This Document
project's background and describes the structure of this document.
* Chapter :doc:`02-methodology` describes the methodology implemented by the
- *SampleVNF* Project for :term:`VNF` and :term:`NFVI` verification.
-
-* Chapter :doc:`03-architecture` provides information on the software architecture
- of *SampleVNF*.
+ *SampleVNF* Project for :term:`NFVI` verification.
-* Chapter :doc:`04-installation` provides instructions to install *SampleVNF*.
+* Chapter :doc:`03-installation` provides instructions to install *SampleVNF*.
* Chapter :doc:`05-How_to_run_SampleVNFs` provides example on how installing and running *SampleVNF*.
===========
Methodology
===========
+.. _NFV-TST009: https://docbox.etsi.org/ISG/NFV/open/Publications_pdf/Specs-Reports/NFV-TST%20009v3.2.1%20-%20GS%20-%20NFVI_Benchmarks.pdf
Abstract
========
This chapter describes the methodology/overview of SampleVNF project from
-the perspective of a :term:`VNF` and :term:`NFVI` Characterization
+the perspective of :term:`NFVI` Characterization
Overview
========
-This project provides a placeholder for various sample VNF (Virtual Network Function (:term:`VNF`))
-development which includes example reference architecture and optimization methods
-related to VNF/Network service for high performance VNFs.
+This project covers the dataplane benchmarking for Network Function Virtualization
+Infrastructure (:term:`NFVI`)) using the PROX tool, according to ETSI GS NFV-TST009_.
-The sample VNFs are Open Source approximations* of Telco grade :term:`VNF`
-using optimized VNF + NFVi Infrastructure libraries, with Performance Characterization of Sample† Traffic Flows.
-• * Not a commercial product. Encourage the community to contribute and close the feature gaps.
-• † No Vendor/Proprietary Workloads
+The test execution and reporting is driven by the Xtesting framework and is fully automated.
-ETSI-NFV
-========
-
-.. _NFV-TST001: http://www.etsi.org/deliver/etsi_gs/NFV-TST/001_099/001/01.01.01_60/gs_NFV-TST001v010101p.pdf
-.. _SampleVNFtst: https://wiki.opnfv.org/display/SAM/Technical+Briefs+of+VNFs
-.. _Yardstick_NSB: http://artifacts.opnfv.org/yardstick/docs/testing_user_userguide/index.html#document-13-nsb-overview
-
-SampleVNF Test Infrastructure (NSB (Yardstick_NSB_))in yardstick helps to facilitate
-consistent/repeatable methodologies for characterizing & validating the
-sample VNFs (:term:`VNF`) through OPEN SOURCE VNF approximations.
-
-Network Service Benchmarking in yardstick framework follows ETSI GS NFV-TST001_
-to verify/characterize both :term:`NFVI` & :term:`VNF`
-
-The document ETSI GS NFV-TST001_, "Pre-deployment Testing; Report on Validation
-of NFV Environments and Services", recommends methods for pre-deployment
-testing of the functional components of an NFV environment.
+When executing the tests, traffic will be send between 2 or more PROX VMs and all metrics
+will be collected in the Xtesting database.
+The placement of the test VMs (in which the PROX tool is running), can be controlled by
+Heat stacks, but can also be done through other means. This will be explained in the chapter
+covering the PROX instance deployment, and needs to be done prior to the test execution.
-The SampleVNF project implements the methodology described in chapter 13 of Yardstick_NSB_,
-"Pre-deployment validation of NFV infrastructure".
+The PROX tool is a DPDK based application optimized for high throughput packet handling.
+As such, we will not measure limitations imposed by the tool, but the capacity of the
+NFVI. In the rare case that the PROX tool would impose a limit, a warning will be logged.
-The methodology consists in decomposing the typical :term:`VNF` work-load
-performance metrics into a number of characteristics/performance vectors, which
-each can be represented by distinct test-cases.
-
-.. seealso:: SampleVNFtst_ for material on alignment ETSI TST001 and SampleVNF.
+ETSI-NFV
+========
+The document ETSI GS NFV-TST009_, "Specification of Networking Benchmarks and
+Measurement Methods for NFVI", specifies vendor-agnostic definitions of performance
+metrics and the associated methods of measurement for Benchmarking networks supported
+in the NFVI. Throughput, latency, packet loss and delay variation will be measured.
+The delay variation is not represented by the Frame Delay Variation (FDV) as defined in
+the specification, but by the average latency, the 99 percentile latency, the maximum
+latency and the complete latency distribution histogram.
Metrics
=======
-The metrics, as defined by ETSI GS NFV-TST001, are shown in
-:ref:`Table1 <table2_1>`.
+The metrics, as reported by the tool, and aligned with the definitions in ETSI GS NFV-TST009_,
+
are shown in :ref:`Table1 <table2_1>`.
.. _table2_1:
-**Table 1 - Performance/Speed Metrics**
-
-+---------+-------------------------------------------------------------------+
-| Category| Performance/Speed |
-| | |
-+---------+-------------------------------------------------------------------+
-| Network | * Throughput per NFVI node (frames/byte per second) |
-| | * Throughput provided to a VM (frames/byte per second) |
-| | * Latency per traffic flow |
-| | * Latency between VMs |
-| | * Latency between NFVI nodes |
-| | * Packet delay variation (jitter) between VMs |
-| | * Packet delay variation (jitter) between NFVI nodes |
-| | * RFC 3511 benchmark |
-| | |
-+---------+-------------------------------------------------------------------+
+**Table 1 - Network Metrics**
+
++-----------------+---------------------------------------------------------------+
+| Measurement | Description |
+| | |
++-----------------+---------------------------------------------------------------+
+| Throughput | Maximum number of traffic that can be sent between 2 VM |
+| | instances, within the allowed packet loss requirements. |
+| | Results are expressed in Mpps and in Gb/s |
++-----------------+---------------------------------------------------------------+
+| Latency | 99 percentile Round trip latency expressed in micro-seconds |
+| | Note that you can also specify the n-th percentile |
++-----------------+---------------------------------------------------------------+
+| Delay Variation | Average latency, maximum latency and the latency histogram |
++-----------------+---------------------------------------------------------------+
+| Loss | Packets per seconds that were lost on their round trip between|
+| | VMs. Total packet loss numbers are also reported |
++-----------------+---------------------------------------------------------------+
.. note:: The description in this OPNFV document is intended as a reference for
users to understand the scope of the SampleVNF Project and the
deliverables of the SampleVNF framework. For complete description of
the methodology, please refer to the ETSI document.
-
-.. rubric:: Footnotes
-.. [1] To be included in future deliveries.
-
--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International
+.. License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) OPNFV, Intel Corporation and others.
+
+SampleVNF Installation
+======================
+
+Abstract
+--------
+The installation procedures described below will result in the deployment of
+all SW components needed to run the benchmarking procedures as defined in ETSI
+GS NFV-TST009 on top of an NFVI instance that is the subject of this characterization.
+Xtesting in combination with the rapid scripts and the PROX tool will be used to achieve this.
+
+The steps needed to run the benchmarking are:
+ 1) Identify a machine on which you will install the containers to support the testing
+ 2) Clone the samplevnf project on that machine
+ 3) Deploy the testing VMs (hosting PROX tool) (Or containers)
+ 4) Deploy your own Xtesting toolchain.
+ 5) Build the test container that will drive the TST009 testing
+ 6) Publish your container on your local repository
+ 7) Execute the testing
+
+In this chapter, we will cover the first 6 installation steps.
+
+Prerequisites
+-------------
+
+Supported Test setup
+^^^^^^^^^^^^^^^^^^^^^
+The device under test (DUT) is an NFVI instance on which we can deploy PROX instances.
+A PROX instance is a machine that
+ * has a management interface that can be reached from the test container
+ * has one or more data plane interfaces on a dataplane network.
+ * can be a container, a VM or a bare metal machine. We just need to be able to ssh into the
+ PROX machine from the test container.
+ * is optimized for data plane traffic.
+ * will measure the throughput that is offered through its dataplane interface(s)
+There are no requirements on the NFVI instance itself. Of course, the measured throughput will
+depend heavily on the NFVI characteristics.
+In this release, we are supporting an automated deployment of the PROX instance on an NFVI that
+provides the OpenStack Heat interface. You could also deploy the PROX instances using other
+mechanisms. As long as you provide the necessary files describing these instances, the execution
+of the test can also be done automatically (steps 4-7) and hence be executed on different DUTs,
+e.g. VMWare, K8s, bare metal, ...
+
+Below is the basic picture of the deployment needed for the testing.
+
+.. image:: images/rapid.png
+ :width: 800px
+ :alt: supported topology
+
+Different test scenario's can now be executed by deploying the PROX machines on different systems:
+ * The generator machine could be deployed on a well defined compute node, that has network access
+ to the other nodes through the TOR. The generated traffic is very similar to external traffic.
+ * The Generator and the Swap instance could be on the same compute node to test E-W traffic between
+ 2 instance on the same compute node
+ * The Generator and the Swap instance could be on a different compute node
+
+Many VMs can be deployed before the test is running: each test case can then use different pairs of
+PROX instances to test all the above scenarios
+
+Hardware & Software Ingredients
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The only requirement is to have the PROX instances running. There are no stringent requirements to be able
+to run the test. Of course, the dataplane performance will heavily depend on the underlying NFVI HW & SW
+
+Installation Steps
+------------------
+
+Step 1: Identify a machine on which you will install the containers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This machine will needs enough resource to install the Xtesting framework and needs to be enabled
+for containers.
+Form a network point of view, it will need to have access to the PROX instances: That means it will need
+to be able to ssh into these machines and that the network also needs to allow for TCP port 8474 traffic.
+
+When using the automation to create the VM through the Heat Stack API, this machine also needs to be able
+execute the OpenStack API. Alternatively, the creation of the VMs can be executed on another machine, but
+this will involve some manual file copying.
+
+Step 2: Clone the samplevnf project on that machine
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ ::
+ git clone https://git.opnfv.org/samplevnf
+Go to the relevant directory in this repository: samplevnf/VNFs/DPPD-PROX/helper-scripts/rapid/
+
+Step 3: Deploy the testing VMs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+In this step, we will be deploying 2 or more instances that host the PROX tool. At the end of this step,
+the instances will be running and an environment file (default name: rapid.env) will be created. This file
+will have all information needed to run the actual test. You can do this step manually on all kinds of
+platforms (OpenStack, VMWare, K8s, bare metal, ...), but the automation tools described in the rest of this
+paragraph will using OpenStack Heat yaml files.
+First, a PROX qcow2 image needs to be downloaded.
+ ::
+ wget http://artifacts.opnfv.org/samplevnf/jerma/prox_jerma.qcow2
+This image can also be created mannualy by following instructions in https://wiki.opnfv.org/display/SAM/Rapid+scripting,
+in the section "Creating an image"
+Now upload this image to Openstack:
+ ::
+ openstack image` create --disk-format qcow2 --container-format bare --file prox_jerma.qcow2 rapidVM
+Now run createrapid.sh to create the stack. This process takes the config_file as input. Details can be found in
+https://wiki.opnfv.org/display/SAM/Rapid+scripting, in the section "Deploying the VMs"
+ ::
+ ./createrapid.sh
+At the end of this step, VMs should be running and the rapid.env and rapid_key.pem files should be available.
+
+Step 4: Deploy your own Xtesting toolchain
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Install Xtesting as described in https://xtesting.readthedocs.io/en/latest/
+First goto the xtesting directory in samplevnf/VNFs/DPPD-PROX/helper-scripts/rapid/xtesting (this was cloned
+in step 2)
+ ::
+ virtualenv xtesting
+ . xtesting/bin/activate
+ pip install ansible
+ ansible-galaxy install collivier.xtesting
+ ansible-playbook site.yaml
+ deactivate
+ rm -r xtesting
+
+Step 5: Build the test container that will drive the TST009 testing
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ ::
+ docker build -t 127.0.0.1:5000/rapidxt .
+
+Step 6: Publish your container on your local repository
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ ::
+ docker push 127.0.0.1:5000/rapidxt
+
+You are now ready to execute the testing
+++ /dev/null
-.. This work is licensed under a Creative Commons Attribution 4.0 International
-.. License.
-.. http://creativecommons.org/licenses/by/4.0
-.. (c) OPNFV, Intel Corporation and others.
-
-SampleVNF Installation
-======================
-
-Abstract
---------
-
-This project provides a placeholder for various sample VNF
-(Virtual Network Function (:term:`VNF`)) development which includes example
-reference architecture and optimization methods related to VNF/Network service
-for high performance VNFs.
-The sample VNFs are Open Source approximations* of Telco grade VNF’s using
-optimized VNF + NFVi Infrastructure libraries, with Performance Characterization
-of Sample† Traffic Flows.
-
-::
-
- * Not a commercial product. Encourage the community to contribute and close the feature gaps.
- † No Vendor/Proprietary Workloads
-
-SampleVNF supports installation directly in Ubuntu. The installation procedure
-are detailed in the sections below.
-
-The steps needed to run SampleVNF are:
- 1) Install and Build SampleVNF.
- 2) Deploy the VNF on the target and modify the config based on the Network under test
- 3) Run the traffic generator to generate the traffic.
-
-Prerequisites
--------------
-
-Supported Test setup
-^^^^^^^^^^^^^^^^^^^^^
-The device under test (DUT) consists of a system following;
- * A single or dual processor and PCH chip, except for System on Chip (SoC) cases
- * DRAM memory size and frequency (normally single DIMM per channel)
- * Specific Intel Network Interface Cards (NICs)
- * BIOS settings noting those that updated from the basic settings
- * DPDK build configuration settings, and commands used for tests
-Connected to the DUT is an IXIA* or Software Traffic generator like pktgen or TRex,
-simulation platform to generate packet traffic to the DUT ports and
-determine the throughput/latency at the tester side.
-
-Below are the supported/tested (:term:`VNF`) deployment type.
-
-.. image:: images/deploy_type.png
- :width: 800px
- :alt: SampleVNF supported topology
-
-Hardware & Software Ingredients
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-SUT requirements:
-
-::
-
- +-----------+------------------+
- | Item | Description |
- +-----------+------------------+
- | Memory | Min 20GB |
- +-----------+------------------+
- | NICs | 2 x 10G |
- +-----------+------------------+
- | OS | Ubuntu 16.04 LTS |
- +-----------+------------------+
- | kernel | 4.4.0-34-generic|
- +-----------+------------------+
- | DPDK | 17.02 |
- +-----------+------------------+
-
-Boot and BIOS settings:
-
-::
-
- +------------------+---------------------------------------------------+
- | Boot settings | default_hugepagesz=1G hugepagesz=1G hugepages=16 |
- | | hugepagesz=2M hugepages=2048 isolcpus=1-11,22-33 |
- | | nohz_full=1-11,22-33 rcu_nocbs=1-11,22-33 |
- | | Note: nohz_full and rcu_nocbs is to disable Linux*|
- | | kernel interrupts, and it’s import |
- +------------------+---------------------------------------------------+
- |BIOS | CPU Power and Performance Policy <Performance> |
- | | CPU C-state Disabled |
- | | CPU P-state Disabled |
- | | Enhanced Intel® Speedstep® Tech Disabled |
- | | Hyper-Threading Technology (If supported) Enable |
- | | Virtualization Techology Enable |
- | | Coherency Enable |
- | | Turbo Boost Disabled |
- +------------------+---------------------------------------------------+
-
-Network Topology for testing VNFs
----------------------------------
-The ethernet cables should be connected between traffic generator and the VNF server (BM,
-SRIOV or OVS) setup based on the test profile.
-
-The connectivity could be
-
-1) Single port pair : One pair ports used for traffic
-
-::
-
- e.g. Single port pair link0 and link1 of VNF are used
- TG:port 0 <------> VNF:Port 0
- TG:port 1 <------> VNF:Port 1
-
- For correalted traffic, use below configuration
- TG_1:port 0 <------> VNF:Port 0
- VNF:Port 1 <------> TG_2:port 0 (UDP Replay)
- (TG_2(UDP_Replay) reflects all the traffic on the given port)
-
-2) Multi port pair : More than one pair of traffic
-
-::
-
- e.g. Two port pair link 0, link1, link2 and link3 of VNF are used
- TG:port 0 <------> VNF:Port 0
- TG:port 1 <------> VNF:Port 1
- TG:port 2 <------> VNF:Port 2
- TG:port 3 <------> VNF:Port 3
-
- For correalted traffic, use below configuration
- TG_1:port 0 <------> VNF:Port 0
- VNF:Port 1 <------> TG_2:port 0 (UDP Replay)
- TG_1:port 1 <------> VNF:Port 2
- VNF:Port 3 <------> TG_2:port 1 (UDP Replay)
- (TG_2(UDP_Replay) reflects all the traffic on the given port)
-
-* Bare-Metal
- Refer: http://fast.dpdk.org/doc/pdf-guides/ to setup the DUT for VNF to run
-
-* Standalone Virtualization - PHY-VM-PHY
- * SRIOV
- Refer below link to setup sriov
- https://software.intel.com/en-us/articles/using-sr-iov-to-share-an-ethernet-port-among-multiple-vms
-
- * OVS_DPDK
- Refer below link to setup ovs-dpdk
- http://docs.openvswitch.org/en/latest/intro/install/general/
- http://docs.openvswitch.org/en/latest/intro/install/dpdk/
-
- * Openstack
- Use any OPNFV installer to deploy the openstack.
-
-
-Build VNFs on the DUT:
-----------------------
-
-1) Clone sampleVNF project repository - git clone https://git.opnfv.org/samplevnf
-
-Auto Build - Using script to build VNFs
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- * Interactive options:
- ::
-
- ./tools/vnf_build.sh -i
- Follow the steps in the screen from option [1] –> [10] and
- select option [9] to build the vnfs.
- It will automatically download selected DPDK version and any
- required patches and will setup everything and build VNFs.
-
- Options [8], If RestAPI feature is needed install 'civetweb'
-
- Following are the options for setup:
- ----------------------------------------------------------
- Step 1: Environment setup.
- ----------------------------------------------------------
- [1] Check OS and network connection
- [2] Select DPDK RTE version
-
- ----------------------------------------------------------
- Step 2: Download and Install
- ----------------------------------------------------------
- [3] Agree to download
- [4] Download packages
- [5] Download DPDK zip
- [6] Build and Install DPDK
- [7] Setup hugepages
- [8] Download and Build civetweb
-
- ----------------------------------------------------------
- Step 3: Build VNFs
- ----------------------------------------------------------
- [9] Build all VNFs (vACL, vCGNAPT, vFW, UDP_Replay, DPPD-PROX)
-
- [10] Exit Script
-
- * non-Interactive options:
- ::
- ./tools/vnf_build.sh -s -d=<dpdk version eg 17.02>
-
-Manual Build
-^^^^^^^^^^^^
-
- ::
-
- 1. Download DPDK supported version from dpdk.org
- * http://dpdk.org/browse/dpdk/snapshot/dpdk-$DPDK_RTE_VER.zip
- * unzip dpdk-$DPDK_RTE_VER.zip and apply dpdk patches only in case of 16.04 (Not required for other DPDK versions)
- * cd dpdk
- * make config T=x86_64-native-linuxapp-gcc O=x86_64-native-linuxapp-gcc
- * cd x86_64-native-linuxapp-gcc
- * make -j
- 2. Add this to Go to /etc/default/grub configuration file to setup hugepages.
- * Append “default_hugepagesz=1G hugepagesz=1G hugepages=8 hugepagesz=2M hugepages=2048” to the GRUB_CMDLINE_LINUX entry.
- 3. Setup Environment Variable
- * export RTE_SDK=<samplevnf>/dpdk
- * export RTE_TARGET=x86_64-native-linuxapp-gcc
- * export VNF_CORE=<samplevnf> or using ./tools/setenv.sh
- 4. Build SampleVNFs e.g, vACL
- * cd <samplevnf>/VNFs/vACL
- * make clean
- * make
- * The vACL executable will be created at the following location
- <samplevnf>/VNFs/vACL/build/vACL
-
-2) Standalone virtualization/Openstack:
-
- Build VM image from script in yardstick
- ::
- 1) git clone https://git.opnfv.org/samplevnf
- 2) cd samplevnf and run
- ./tools/samplevnf-img-dpdk-samplevnf-modify tools/ubuntu-server-cloudimg-samplevnf-modify.sh
- Image available in: /tmp/workspace/samplevnf/xenial-server-cloudimg-amd64-disk1.img
-
-To run VNFs. Please refer chapter `05-How_to_run_SampleVNFs.rst`
:maxdepth: 4
:numbered:
- 01-prox_documentation
+ 01-introduction.rst
+ 02-methodology.rst
+ 03-installation.rst
Code Review / samplevnf.git / commitdiff
