This repo will build two centos 7 images with:
- testpmd and VPP installed for loop VM use case
- NFVbench and TRex installed for generator VM use case
+
These VMs will come with a pre-canned user/password: nfvbench/nfvbench
BUILD INSTRUCTIONS
--------------
- must run on Linux
- the following packages must be installed prior to using this script:
+ - python3 (+ python3-venv on Ubuntu)
+ - python3-pip
- git
- - qemu-utils
+ - qemu-img (CentOs) or qemu-utils (Ubuntu)
- kpartx
+.. note:: The image build process is based on `diskimage-builder
+ <https://docs.openstack.org/diskimage-builder/latest/index.html>`_
+ that will be installed in a Python virtual environment by nfvbenchvm
+ build script build-image.sh.
+
+.. note:: build-image.sh uses the `gsutil <https://pypi.org/project/gsutil/>`_
+ tool to interact with Google cloud storage (to check if the images
+ exist and to upload the images). This is normally only needed in the
+ context of OPNFV build infrastructure, and build-image.sh can be used
+ without that tool in development environments.
+
Build the image
---------------
- cd dib
- update the version number for the image (if needed) by modifying __version__ in build-image.sh
- setup your http_proxy if needed
-- to build loop VM image only:
- - `bash build-image.sh -l`
-- to build generator VM image only:
- - `bash build-image.sh -g`
-- to build both images only:
- - `bash build-image.sh`
+- run ``build-image.sh`` to build the images. A few examples:
+
+ - to build all the images and publish the code to Google cloud storage:
+ - ``bash build-image.sh``
+ - to build and publish only the loop VM:
+ - ``bash build-image.sh -l``
+ - to build and publish only the generator VM:
+ - ``bash build-image.sh -g``
+ - to build the generator VM without publishing it:
+ - ``bash build-image.sh -gv``
+
+.. note:: Run ``bash build-image.sh`` -h to see all options available.
+
+.. note:: By default, the generator VM image embeds the latest nfvbench version
+ found on the master branch of OPNFV Gerrit repository
+ https://gerrit.opnfv.org/gerrit/nfvbench.
+
+ During development phases, it is also possible to build the image with
+ all the committed changes found in the current working copy of
+ nfvbench (local code). To do that, run the image build with the ``-s``
+ option, for instance: ``bash build-image.sh -gvs``.
+
+ In that case, the version of the generator VM image will be extended
+ with nfvbench development version number to be able to distinguish the
+ development images from the latest published image.
LOOP VM IMAGE INSTANCE AND CONFIG
=================================
GENERATOR IMAGE INSTANCE AND CONFIG
===================================
+Pre-requisites
+--------------
+To use openstack APIs, NFVbench generator VM will use `clouds.yaml` file as openstack configuration.
+The OpenStack clouds configuration from clouds.yaml file to use.
+clouds.yaml file must be in one of the following paths:
+- ~/.config/openstack
+- /etc/openstack
+
+Example of `clouds.yaml`:
+
+.. code-block:: yaml
+
+ clouds:
+ devstack:
+ auth:
+ auth_url: http://192.168.122.10:35357/
+ project_name: demo
+ username: demo
+ password: 0penstack
+ region_name: RegionOne
+
+.. note:: Add `CLOUD_DETAIL` property with the accurate value for your openstack configuration (`devstack` in the above example) in ``/etc/nfvbenchvm.conf``
+
Interface Requirements
----------------------
The instance must be launched using OpenStack with 2 network interfaces for dataplane traffic (using SR-IOV function) and 1 management interface to control nfvbench.
pci: "{{PCI_ADDRESS_2}}"
switch:
intf_speed:
+
.. note:: `CORE_THREADS` value is determined automatically based on the cores available on the VM starting from 2 to last worker core available.
Auto-configuration
LOOPBACK_INTF_MAC2=FA:16:3E:10:DA:10
E2E_INTF_MAC1=FA:16:3E:B0:E2:43
E2E_INTF_MAC2=FA:16:3E:D3:6A:FC
+
.. note:: `ACTION` parameter is not mandatory but will permit to start NFVbench with the accurate ports (loopback or e2e).
.. note:: Set of MAC parameters cannot be used in parallel as only one NFVbench/TRex process is running.
.. note:: Switching from `loopback` to `e2e` action can be done manually using `/nfvbench/start-nfvbench.sh <action>` with the accurate keyword for `action` parameter. This script will restart NFVbench with the good set of MAC.
INTF_MAC_MGMT=FA:16:3E:06:11:8A
INTF_MGMT_CIDR=172.20.56.228/2
INTF_MGMT_IP_GW=172.20.56.225
+ INTF_MGMT_MTU=1500
.. note:: `INTF_MGMT_IP_GW` and `INTF_MGMT_CIDR` parameters are used by the VM to automatically configure virtual interface and route to allow an external access through SSH.
+.. note:: ``INTF_MGMT_MTU`` allows to specify the MTU of the management
+ interface in bytes.
+
+ If ``INTF_MGMT_MTU`` is not specified, the MTU will be configured to
+ the conservative value of 1500: this will reduce the risk to get an
+ unmanageable VM.
+
+ ``INTF_MGMT_MTU`` can also be set to the special value ``auto``: in
+ that case, the MTU will not be configured and it will keep the value
+ set by the hypervisor (default nfvbench behavior up to version
+ 5.0.3).
Using pre-created direct-physical ports on openstack, mac addresses value are only known when VM is deployed. In this case, you can pass the port name in config:
INTF_MGMT_CIDR=172.20.56.228/2
INTF_MGMT_IP_GW=172.20.56.225
DNS_SERVERS=8.8.8.8,dns.server.com
+
.. note:: A management interface is required to automatically find the virtual interface to use according to the MAC address provided (see `INTF_MAC_MGMT` parameter).
.. note:: NFVbench VM will call openstack API through the management interface to retrieve mac address for these ports
.. note:: If openstack API required a host name resolution, add the parameter DNS_SERVERS to add IP or DNS server names (multiple servers can be added separated by a `,`)
.. code-block:: bash
-curl -XGET '<management_ip>:<port>/status'
+ curl -XGET '<management_ip>:<port>/status'
Example of answer:
.. code-block:: bash
-curl -XPOST '<management_ip>:<port>/start_run' -H "Content-Type: application/json" -d @nfvbenchconfig.json
+ curl -XPOST '<management_ip>:<port>/start_run' -H "Content-Type: application/json" -d @nfvbenchconfig.json
Example of return when the submission is successful:
.. code-block:: bash
-run_tests -t nfvbench-demo
+ run_tests -t nfvbench-demo
.. note:: `-t` option determine which test case to be runned by Xtesting
(see `xtesting/testcases.yaml` file content to see available list of test cases)