X-Git-Url: https://gerrit.opnfv.org/gerrit/gitweb?a=blobdiff_plain;f=nfvbenchvm%2FREADME.rst;h=29215c1ab5c195ab36b15bb0c8a06828e2be7e6e;hb=a055c1555e0a8c0cfb8c6308990a23eb8db59d13;hp=0274c75160937f61c4dd06923c5a701d93cc5079;hpb=1e262c6d86f105fc73739f623f6d97ee2aae8eb2;p=nfvbench.git diff --git a/nfvbenchvm/README.rst b/nfvbenchvm/README.rst index 0274c75..29215c1 100644 --- a/nfvbenchvm/README.rst +++ b/nfvbenchvm/README.rst @@ -4,6 +4,7 @@ NFVBENCH VM IMAGES FOR OPENSTACK 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 @@ -13,21 +14,53 @@ Pre-requisites -------------- - 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 + `_ + that will be installed in a Python virtual environment by nfvbenchvm + build script build-image.sh. + +.. note:: build-image.sh uses the `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 ================================= @@ -95,6 +128,29 @@ Hardcoded Username and Password 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. @@ -135,6 +191,7 @@ Template of a genarator profile using CPU pinning: 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 @@ -155,6 +212,7 @@ Example of 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 ` with the accurate keyword for `action` parameter. This script will restart NFVbench with the good set of MAC. @@ -169,9 +227,21 @@ nfvbenchvm config file with management interface: 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: @@ -185,6 +255,7 @@ Using pre-created direct-physical ports on openstack, mac addresses value are on 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 `,`) @@ -206,7 +277,7 @@ To check NFVbench is up and running use REST request: .. code-block:: bash -curl -XGET ':/status' + curl -XGET ':/status' Example of answer: @@ -224,7 +295,7 @@ To start a test run using NFVbench API use this type of REST request: .. code-block:: bash -curl -XPOST ':/start_run' -H "Content-Type: application/json" -d @nfvbenchconfig.json + curl -XPOST ':/start_run' -H "Content-Type: application/json" -d @nfvbenchconfig.json Example of return when the submission is successful: @@ -244,7 +315,7 @@ To start a test run using Xtesting python library and NFVbench API use this type .. 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)