X-Git-Url: https://gerrit.opnfv.org/gerrit/gitweb?a=blobdiff_plain;f=nfvbenchvm%2FREADME.rst;h=29215c1ab5c195ab36b15bb0c8a06828e2be7e6e;hb=1e6a2788ca3118885c64276dc862f98d53d4ac99;hp=1bf0bbf97e3ee15cb84ebf60e3d12e1e9e9304ab;hpb=1ce98c7510f810a5ee790523a0dcbf429961adda;p=nfvbench.git diff --git a/nfvbenchvm/README.rst b/nfvbenchvm/README.rst index 1bf0bbf..29215c1 100644 --- a/nfvbenchvm/README.rst +++ b/nfvbenchvm/README.rst @@ -1,8 +1,11 @@ -NFVBENCH VM IMAGE FOR OPENSTACK -+++++++++++++++++++++++++++++++ +NFVBENCH VM IMAGES FOR OPENSTACK +++++++++++++++++++++++++++++++++ -This repo will build a centos 7 image with testpmd and VPP installed. -The VM will come with a pre-canned user/password: nfvbench/nfvbench +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 ================== @@ -11,19 +14,56 @@ 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 -- 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``. -IMAGE INSTANCE AND CONFIG -========================= + 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 +================================= Interface Requirements ---------------------- @@ -84,3 +124,238 @@ Hardcoded Username and Password - Username: nfvbench - Password: nfvbench + +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. +For best performance, it should use network interfaces for dataplane traffic with a `vnic_type` to `direct-physical` (or `direct` if physical function is not possible) +and a flavor with: + +- 6 vCPU +- 8 GB RAM +- cpu pinning set to exclusive + +.. note:: For the management interface: any interface type can be used. This interface required a routable IP (through floating IP or direct) and an access to the openstack APIs. +.. note:: CPU pinning: 1 core dedicated for guest OS and NFVbench process, other provided cores are used by TRex + +Template of a genarator profile using CPU pinning: + +.. code-block:: bash + + generator_profile: + - name: {{name}} + tool: {{tool}} + ip: {{ip}} + zmq_pub_port: {{zmq_pub_port}} + zmq_rpc_port: {{zmq_rpc_port}} + software_mode: {{software_mode}} + cores: {{CORES}} + platform: + master_thread_id: '0' + latency_thread_id: '1' + dual_if: + - socket: 0 + threads: [{{CORE_THREADS}}] + + interfaces: + - port: 0 + pci: "{{PCI_ADDRESS_1}}" + switch: + - port: 1 + 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 +------------------ +nfvbench VM will automatically find the two virtual interfaces to use for dataplane based on MAC addresses or openstack port name (see config part below). +This applies to the management interface as well. + +nfvbenchvm Config +----------------- +nfvbenchvm config file is located at ``/etc/nfvbenchvm.conf``. + +Example of configuration: + +.. code-block:: bash + + ACTION=e2e + LOOPBACK_INTF_MAC1=FA:16:3E:A2:30:41 + 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. + +nfvbenchvm config file with management interface: + +.. code-block:: bash + + ACTION=e2e + LOOPBACK_INTF_MAC1=FA:16:3E:A2:30:41 + LOOPBACK_INTF_MAC2=FA:16:3E:10:DA:10 + 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: + +.. code-block:: bash + + LOOPBACK_PORT_NAME1=nfvbench-pf1 + LOOPBACK_PORT_NAME2=nfvbench-pf2 + E2E_PORT_NAME1=nfvbench-pf1 + E2E_PORT_NAME1=nfvbench-pf3 + 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 + 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 `,`) + +Control nfvbenchvm VM and run test +---------------------------------- + +By default, NFVbench will be started in server mode (`--server`) and will act as an API. + +NFVbench VM will be accessible through SSH or HTTP using the management interface IP. + +NFVbench API endpoint is : `http://:` +.. note:: by default port value is 7555 + +Get NFVbench status +^^^^^^^^^^^^^^^^^^^ + +To check NFVbench is up and running use REST request: + +.. code-block:: bash + + curl -XGET ':/status' + +Example of answer: + +.. code-block:: bash + + { + "error_message": "nfvbench run still pending", + "status": "PENDING" + } + +Start NFVbench test +^^^^^^^^^^^^^^^^^^^ + +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 + +Example of return when the submission is successful: + +.. code-block:: bash + + { + "error_message": "NFVbench run still pending", + "request_id": "42cccb7effdc43caa47f722f0ca8ec96", + "status": "PENDING" + } + + +Start NFVbench test using Xtesting +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To start a test run using Xtesting python library and NFVbench API use this type of command on the VM: + +.. code-block:: bash + + 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) + + +Connect to the VM using SSH keypair +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If a key is provided at VM creation you can use it to log on the VM using `cloud-user` username: + +.. code-block:: bash + + ssh -i key.pem cloud-user@ + + +Connect to VM using SSH username/password +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +VM is accessible over SSH using the hardcoded username and password (see below): + +.. code-block:: bash + + ssh nfvbench@ + + +Launching nfvbenchvm VM +----------------------- + +Normally this image will be deployed using Ansible role, and the required configurations will be automatically generated and pushed to VM by Ansible. +If launched manually, users will have the full control to configure and run NFVbench via VNC console. + +To check if NFVbench is running, you can run this command in VNC console: + +.. code-block:: bash + + sudo screen -r nfvbench + + +Hardcoded Username and Password +-------------------------------- +- Username: nfvbench +- Password: nfvbench +