1 .. This work is licensed under a Creative Commons Attribution 4.0 International
3 .. http://creativecommons.org/licenses/by/4.0
4 .. (c) OPNFV, 2016-2017 Intel Corporation.
6 Yardstick - NSB Testing -Installation
7 =====================================
12 The Network Service Benchmarking (NSB) extends the yardstick framework to do
13 VNF characterization and benchmarking in three different execution
14 environments viz., bare metal i.e. native Linux environment, standalone virtual
15 environment and managed virtualized environment (e.g. Open stack etc.).
16 It also brings in the capability to interact with external traffic generators
17 both hardware & software based for triggering and validating the traffic
18 according to user defined profiles.
20 The steps needed to run Yardstick with NSB testing are:
22 * Install Yardstick (NSB Testing).
23 * Setup pod.yaml describing Test topology
24 * Create the test configuration yaml file.
31 Refer chapter Yardstick Instalaltion for more information on yardstick
34 Several prerequisites are needed for Yardstick(VNF testing):
36 - Python Modules: pyzmq, pika.
56 Install Yardstick (NSB Testing)
57 -------------------------------
61 Refer chapter :doc:`04-installation` for more on docker **Install Yardstick using Docker (**recommended**)**
63 Install directly in Ubuntu
64 --------------------------
65 .. _install-framework:
67 Alternatively you can install Yardstick framework directly in Ubuntu or in an Ubuntu Docker image. No matter which way you choose to install Yardstick, the following installation steps are identical.
69 If you choose to use the Ubuntu Docker image, you can pull the Ubuntu
70 Docker image from Docker hub::
72 docker pull ubuntu:16.04
77 Prerequisite preparation::
79 apt-get update && apt-get install -y git python-setuptools python-pip
80 easy_install -U setuptools==30.0.0
81 pip install appdirs==1.4.0
82 pip install virtualenv
84 Create a virtual environment::
86 virtualenv ~/yardstick_venv
87 export YARDSTICK_VENV=~/yardstick_venv
88 source ~/yardstick_venv/bin/activate
90 Download the source code and install Yardstick from it::
92 git clone https://gerrit.opnfv.org/gerrit/yardstick
93 export YARDSTICK_REPO_DIR=~/yardstick
98 After *Yardstick* is installed, executing the "nsb_setup.sh" script to setup
103 It will also automatically download all the packages needed for NSB Testing setup.
108 .. code-block:: console
110 +----------+ +----------+
116 +----------+ +----------+
120 Environment parameters and credentials
121 --------------------------------------
123 Environment variables
124 ^^^^^^^^^^^^^^^^^^^^^
126 Before running Yardstick (NSB Testing) it is necessary to export traffic
127 generator libraries.::
129 source ~/.bash_profile
131 Config yardstick conf
132 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
135 cp ./etc/yardstick/yardstick.conf.sample /etc/yardstick/yardstick.conf
136 vi /etc/yardstick/yardstick.conf
138 Add trex_path, trex_client_lib and bin_path in 'nsb' section.
144 dispatcher = file, influxdb
146 [dispatcher_influxdb]
148 target = http://{YOUR_IP_HERE}:8086
154 trex_path=/opt/nsb_bin/trex/scripts
155 bin_path=/opt/nsb_bin
156 trex_client_lib=/opt/nsb_bin/trex_client/stl
158 Network Service Benchmarking - Bare-Metal
159 -----------------------------------------
161 Config pod.yaml describing Topology
162 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
166 .. code-block:: console
167 +----------+ +----------+
173 +----------+ +----------+
176 3-Node setup - Correlated Traffic
177 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
178 .. code-block:: console
179 +----------+ +----------+ +------------+
182 | | (0)----->(0) | | | UDP |
183 | TG1 | | DUT | | Replay |
185 | | | |(1)<---->(0)| |
186 +----------+ +----------+ +------------+
187 trafficgen_1 vnf trafficgen_2
189 Before executing Yardstick test cases, make sure that pod.yaml reflects the
190 topology and update all the required fields.::
192 cp /etc/yardstick/nodes/pod.yaml.nsb.sample /etc/yardstick/nodes/pod.yaml
204 xe0: # logical name from topology.yaml and vnfd.yaml
206 driver: i40e # default kernel driver
208 local_ip: "152.16.100.20"
209 netmask: "255.255.255.0"
210 local_mac: "00:00:00:00:00:01"
211 xe1: # logical name from topology.yaml and vnfd.yaml
213 driver: i40e # default kernel driver
215 local_ip: "152.16.40.20"
216 netmask: "255.255.255.0"
217 local_mac: "00:00.00:00:00:02"
225 host: 1.1.1.2 #BM - host == ip, virtualized env - Host - compute node
227 xe0: # logical name from topology.yaml and vnfd.yaml
229 driver: i40e # default kernel driver
231 local_ip: "152.16.100.19"
232 netmask: "255.255.255.0"
233 local_mac: "00:00:00:00:00:03"
235 xe1: # logical name from topology.yaml and vnfd.yaml
237 driver: i40e # default kernel driver
239 local_ip: "152.16.40.19"
240 netmask: "255.255.255.0"
241 local_mac: "00:00:00:00:00:04"
243 - network: "152.16.100.20"
244 netmask: "255.255.255.0"
245 gateway: "152.16.100.20"
247 - network: "152.16.40.20"
248 netmask: "255.255.255.0"
249 gateway: "152.16.40.20"
252 - network: "0064:ff9b:0:0:0:0:9810:6414"
254 gateway: "0064:ff9b:0:0:0:0:9810:6414"
256 - network: "0064:ff9b:0:0:0:0:9810:2814"
258 gateway: "0064:ff9b:0:0:0:0:9810:2814"
261 Enable yardstick virtual environment
262 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
264 Before executing yardstick test cases, make sure to activate yardstick
265 python virtual environment if runnin on ubuntu without docker::
267 source /opt/nsb_bin/yardstick_venv/bin/activate
269 On docker, virtual env is in main path.
271 Run Yardstick - Network Service Testcases
272 -----------------------------------------
274 NS testing - using NSBperf CLI
275 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
278 PYTHONPATH: ". ~/.bash_profile"
279 cd <yardstick_repo>/yardstick/cmd
281 Execute command: ./NSPerf.py -h
282 ./NSBperf.py --vnf <selected vnf> --test <rfc test>
283 eg: ./NSBperf.py --vnf vpe --test tc_baremetal_rfc2544_ipv4_1flow_64B.yaml
285 NS testing - using yardstick CLI
286 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
288 PYTHONPATH: ". ~/.bash_profile"
290 Go to test case forlder type we want to execute.
291 e.g. <yardstick repo>/samples/vnf_samples/nsut/<vnf>/
292 run: yardstick --debug task start <test_case.yaml>
294 Network Service Benchmarking - Standalone Virtualization
295 --------------------------------------------------------
304 a) Create a bridge for VM to connect to external network
306 brctl addif br-int <interface_name> #This interface is connected to internet
308 b) Build guest image for VNF to run.
309 Most of the sample test cases in Yardstick are using a guest image called
310 ``yardstick-image`` which deviates from an Ubuntu Cloud Server image
311 Yardstick has a tool for building this custom image with samplevnf.
312 It is necessary to have ``sudo`` rights to use this tool.
314 Also you may need to install several additional packages to use this tool, by
315 follwing the commands below::
317 sudo apt-get update && sudo apt-get install -y qemu-utils kpartx
319 This image can be built using the following command in the directory where Yardstick is installed::
321 export YARD_IMG_ARCH='amd64'
322 sudo echo "Defaults env_keep += \'YARD_IMG_ARCH\'" >> /etc/sudoers
323 sudo tools/yardstick-img-dpdk-modify tools/ubuntu-server-cloudimg-samplevnf-modify.sh
325 for more details refer chapter :doc:`04-installation``
327 Note: VM should be build with static IP and should be accessiable from yardstick host.
329 Config pod.yaml describing Topology
330 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
334 .. code-block:: console
335 +--------------------+
341 +--------------------+
342 | VF NIC | | VF NIC |
343 +--------+ +--------+
347 +--------+ +--------+
348 - PF NIC - - PF NIC -
349 +----------+ +-------------------------+
352 | | (0)<----->(0) | ------ | |
355 | | (n)<----->(n) |------------------ |
356 +----------+ +-------------------------+
360 3-Node setup - Correlated Traffic
361 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
362 .. code-block:: console
364 +--------------------+
370 +--------------------+
371 | VF NIC | | VF NIC |
372 +--------+ +--------+
376 +--------+ +--------+
377 | PF NIC - - PF NIC -
378 +----------+ +-------------------------+ +------------+
381 | | (0)<----->(0) | ------ | | | TG2 |
382 | TG1 | | SUT | | |(UDP Replay)|
384 | | (n)<----->(n) | ------ |(n)<-->(n)| |
385 +----------+ +-------------------------+ +------------+
386 trafficgen_1 host trafficgen_2
388 Before executing Yardstick test cases, make sure that pod.yaml reflects the
389 topology and update all the required fields.
393 cp /etc/yardstick/nodes/pod.yaml.nsb.sriov.sample /etc/yardstick/nodes/pod.yaml
405 xe0: # logical name from topology.yaml and vnfd.yaml
407 driver: i40e # default kernel driver
409 local_ip: "152.16.100.20"
410 netmask: "255.255.255.0"
411 local_mac: "00:00:00:00:00:01"
412 xe1: # logical name from topology.yaml and vnfd.yaml
414 driver: i40e # default kernel driver
416 local_ip: "152.16.40.20"
417 netmask: "255.255.255.0"
418 local_mac: "00:00.00:00:00:02"
428 - "00:00:00:00:00:03"
429 - "00:00:00:00:00:04"
430 phy_ports: # Physical ports to configure sriov
433 phy_driver: i40e # kernel driver
434 images: "/var/lib/libvirt/images/ubuntu1.img"
442 host: 2.2.2.2 #BM - host == ip, virtualized env - Host - compute node
444 xe0: # logical name from topology.yaml and vnfd.yaml
446 driver: i40evf # default kernel driver
448 local_ip: "152.16.100.10"
449 netmask: "255.255.255.0"
450 local_mac: "00:00:00:00:00:03"
452 xe1: # logical name from topology.yaml and vnfd.yaml
454 driver: i40evf # default kernel driver
456 local_ip: "152.16.40.10"
457 netmask: "255.255.255.0"
458 local_mac: "00:00:00:00:00:04"
460 - network: "152.16.100.10"
461 netmask: "255.255.255.0"
462 gateway: "152.16.100.20"
464 - network: "152.16.40.10"
465 netmask: "255.255.255.0"
466 gateway: "152.16.40.20"
469 - network: "0064:ff9b:0:0:0:0:9810:6414"
471 gateway: "0064:ff9b:0:0:0:0:9810:6414"
473 - network: "0064:ff9b:0:0:0:0:9810:2814"
475 gateway: "0064:ff9b:0:0:0:0:9810:2814"
478 Enable yardstick virtual environment
479 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
481 Before executing yardstick test cases, make sure to activate yardstick
482 python virtual environment if runnin on ubuntu without docker::
484 source /opt/nsb_bin/yardstick_venv/bin/activate
486 On docker, virtual env is in main path.
488 Run Yardstick - Network Service Testcases
489 -----------------------------------------
491 NS testing - using NSBperf CLI
492 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
495 PYTHONPATH: ". ~/.bash_profile"
496 cd <yardstick_repo>/yardstick/cmd
498 Execute command: ./NSPerf.py -h
499 ./NSBperf.py --vnf <selected vnf> --test <rfc test>
500 eg: ./NSBperf.py --vnf vfw --test tc_sriov_rfc2544_ipv4_1flow_64B.yaml
502 NS testing - using yardstick CLI
503 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
505 PYTHONPATH: ". ~/.bash_profile"
507 Go to test case forlder type we want to execute.
508 e.g. <yardstick repo>/samples/vnf_samples/nsut/<vnf>/
509 run: yardstick --debug task start <test_case.yaml>
518 a) Create a bridge for VM to connect to external network
520 brctl addif br-int <interface_name> #This interface is connected to internet
522 b) Build guest image for VNF to run.
523 Most of the sample test cases in Yardstick are using a guest image called
524 ``yardstick-image`` which deviates from an Ubuntu Cloud Server image
525 Yardstick has a tool for building this custom image with samplevnf.
526 It is necessary to have ``sudo`` rights to use this tool.
528 Also you may need to install several additional packages to use this tool, by
529 follwing the commands below::
531 sudo apt-get update && sudo apt-get install -y qemu-utils kpartx
533 This image can be built using the following command in the directory where Yardstick is installed::
535 export YARD_IMG_ARCH='amd64'
536 sudo echo "Defaults env_keep += \'YARD_IMG_ARCH\'" >> /etc/sudoers
537 sudo tools/yardstick-img-dpdk-modify tools/ubuntu-server-cloudimg-samplevnf-modify.sh
539 for more details refer chapter :doc:`04-installation``
541 Note: VM should be build with static IP and should be accessiable from yardstick host.
543 c) OVS & DPDK version.
544 - OVS 2.7 and DPDK 16.11.1 above version is supported
546 d) Setup OVS/DPDK on host.
547 Please refer below link on how to setup .. _ovs-dpdk: http://docs.openvswitch.org/en/latest/intro/install/dpdk/
549 Config pod.yaml describing Topology
550 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
554 .. code-block:: console
555 +--------------------+
561 +--------------------+
562 | virtio | | virtio |
563 +--------+ +--------+
567 +--------+ +--------+
568 | vHOST0 | | vHOST1 |
569 +----------+ +-------------------------+
572 | | (0)<----->(0) | ------ | |
575 | | (n)<----->(n) |------------------ |
576 +----------+ +-------------------------+
580 3-Node setup - Correlated Traffic
581 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
582 .. code-block:: console
584 +--------------------+
590 +--------------------+
591 | virtio | | virtio |
592 +--------+ +--------+
596 +--------+ +--------+
597 | vHOST0 | | vHOST1 |
598 +----------+ +-------------------------+ +------------+
601 | | (0)<----->(0) | ------ | | | TG2 |
602 | TG1 | | SUT | | |(UDP Replay)|
603 | | | (ovs-dpdk) | | | |
604 | | (n)<----->(n) | ------ |(n)<-->(n)| |
605 +----------+ +-------------------------+ +------------+
606 trafficgen_1 host trafficgen_2
609 Before executing Yardstick test cases, make sure that pod.yaml reflects the
610 topology and update all the required fields.::
612 cp /etc/yardstick/nodes/pod.yaml.nsb.ovs.sample /etc/yardstick/nodes/pod.yaml
624 xe0: # logical name from topology.yaml and vnfd.yaml
626 driver: i40e # default kernel driver
628 local_ip: "152.16.100.20"
629 netmask: "255.255.255.0"
630 local_mac: "00:00:00:00:00:01"
631 xe1: # logical name from topology.yaml and vnfd.yaml
633 driver: i40e # default kernel driver
635 local_ip: "152.16.40.20"
636 netmask: "255.255.255.0"
637 local_mac: "00:00.00:00:00:02"
651 - "00:00:00:00:00:03"
652 - "00:00:00:00:00:04"
653 phy_ports: # Physical ports to configure ovs
657 - ovs-ofctl add-flow br0 in_port=1,action=output:3
658 - ovs-ofctl add-flow br0 in_port=3,action=output:1
659 - ovs-ofctl add-flow br0 in_port=4,action=output:2
660 - ovs-ofctl add-flow br0 in_port=2,action=output:4
661 phy_driver: i40e # kernel driver
662 images: "/var/lib/libvirt/images/ubuntu1.img"
670 host: 2.2.2.2 #BM - host == ip, virtualized env - Host - compute node
672 xe0: # logical name from topology.yaml and vnfd.yaml
674 driver: virtio-pci # default kernel driver
676 local_ip: "152.16.100.10"
677 netmask: "255.255.255.0"
678 local_mac: "00:00:00:00:00:03"
680 xe1: # logical name from topology.yaml and vnfd.yaml
682 driver: virtio-pci # default kernel driver
684 local_ip: "152.16.40.10"
685 netmask: "255.255.255.0"
686 local_mac: "00:00:00:00:00:04"
688 - network: "152.16.100.10"
689 netmask: "255.255.255.0"
690 gateway: "152.16.100.20"
692 - network: "152.16.40.10"
693 netmask: "255.255.255.0"
694 gateway: "152.16.40.20"
697 - network: "0064:ff9b:0:0:0:0:9810:6414"
699 gateway: "0064:ff9b:0:0:0:0:9810:6414"
701 - network: "0064:ff9b:0:0:0:0:9810:2814"
703 gateway: "0064:ff9b:0:0:0:0:9810:2814"
706 Enable yardstick virtual environment
707 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
709 Before executing yardstick test cases, make sure to activate yardstick
710 python virtual environment if runnin on ubuntu without docker::
712 source /opt/nsb_bin/yardstick_venv/bin/activate
714 On docker, virtual env is in main path.
716 Run Yardstick - Network Service Testcases
717 -----------------------------------------
719 NS testing - using NSBperf CLI
720 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
723 PYTHONPATH: ". ~/.bash_profile"
724 cd <yardstick_repo>/yardstick/cmd
726 Execute command: ./NSPerf.py -h
727 ./NSBperf.py --vnf <selected vnf> --test <rfc test>
728 eg: ./NSBperf.py --vnf vfw --test tc_ovs_rfc2544_ipv4_1flow_64B.yaml
730 NS testing - using yardstick CLI
731 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
733 PYTHONPATH: ". ~/.bash_profile"
735 Go to test case forlder type we want to execute.
736 e.g. <yardstick repo>/samples/vnf_samples/nsut/<vnf>/
737 run: yardstick --debug task start <test_case.yaml>