diff options
| -rwxr-xr-x | docs/testing/user/userguide/01-introduction.rst | 31 | ||||
| -rw-r--r-- | docs/testing/user/userguide/02-methodology.rst | 96 | ||||
| -rw-r--r-- | docs/testing/user/userguide/03-installation.rst | 135 | ||||
| -rw-r--r-- | docs/testing/user/userguide/04-installation.rst | 230 | ||||
| -rw-r--r-- | docs/testing/user/userguide/images/rapid.png | bin | 0 -> 34588 bytes | |||
| -rw-r--r-- | docs/testing/user/userguide/index.rst | 4 |
6 files changed, 190 insertions, 306 deletions
diff --git a/docs/testing/user/userguide/01-introduction.rst b/docs/testing/user/userguide/01-introduction.rst index 10c0161f..c2d28d04 100755 --- a/docs/testing/user/userguide/01-introduction.rst +++ b/docs/testing/user/userguide/01-introduction.rst @@ -9,30 +9,22 @@ Introduction **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 @@ -44,12 +36,9 @@ This document consists of the following chapters: 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*. diff --git a/docs/testing/user/userguide/02-methodology.rst b/docs/testing/user/userguide/02-methodology.rst index 01cbb276..30efe79f 100644 --- a/docs/testing/user/userguide/02-methodology.rst +++ b/docs/testing/user/userguide/02-methodology.rst @@ -6,81 +6,69 @@ =========== 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. - diff --git a/docs/testing/user/userguide/03-installation.rst b/docs/testing/user/userguide/03-installation.rst new file mode 100644 index 00000000..dc40e8e0 --- /dev/null +++ b/docs/testing/user/userguide/03-installation.rst @@ -0,0 +1,135 @@ +.. 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 diff --git a/docs/testing/user/userguide/04-installation.rst b/docs/testing/user/userguide/04-installation.rst deleted file mode 100644 index e54243cb..00000000 --- a/docs/testing/user/userguide/04-installation.rst +++ /dev/null @@ -1,230 +0,0 @@ -.. 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` diff --git a/docs/testing/user/userguide/images/rapid.png b/docs/testing/user/userguide/images/rapid.png Binary files differnew file mode 100644 index 00000000..1c9b05bd --- /dev/null +++ b/docs/testing/user/userguide/images/rapid.png diff --git a/docs/testing/user/userguide/index.rst b/docs/testing/user/userguide/index.rst index 9ce85382..ab4fb8b4 100644 --- a/docs/testing/user/userguide/index.rst +++ b/docs/testing/user/userguide/index.rst @@ -12,4 +12,6 @@ SampleVNF User Guide :maxdepth: 4 :numbered: - 01-prox_documentation + 01-introduction.rst + 02-methodology.rst + 03-installation.rst |
