docs/developer/nfvbenchvm.rst

   1 .. Copyright 2016 - 2023, Cisco Systems, Inc. and the NFVbench project contributors
   2 .. SPDX-License-Identifier: CC-BY-4.0
   3
   4 NFVBENCH VM IMAGES FOR OPENSTACK
   5 ++++++++++++++++++++++++++++++++
   6
   7 This repo will build two centos 7 images with:
   8     - testpmd and VPP installed for loop VM use case
   9     - NFVbench and TRex installed for generator VM use case
  10
  11 These VMs will come with a pre-canned user/password: nfvbench/nfvbench
  12
  13 BUILD INSTRUCTIONS
  14 ==================
  15
  16 Pre-requisites
  17 --------------
  18 - must run on Linux
  19 - the following packages must be installed prior to using this script:
  20     - python3 (+ python3-venv on Ubuntu)
  21     - python3-pip
  22     - git
  23     - qemu-img (CentOs) or qemu-utils (Ubuntu)
  24     - kpartx
  25
  26 .. note:: The image build process is based on `diskimage-builder
  27           <https://docs.openstack.org/diskimage-builder/latest/index.html>`_
  28           that will be installed in a Python virtual environment by nfvbenchvm
  29           build script build-image.sh.
  30
  31 .. note:: build-image.sh uses the `gsutil <https://pypi.org/project/gsutil/>`_
  32           tool to interact with Google cloud storage (to check if the images
  33           exist and to upload the images).  This is normally only needed in the
  34           context of OPNFV build infrastructure, and build-image.sh can be used
  35           without that tool in development environments.
  36
  37 Build the image
  38 ---------------
  39 - cd dib
  40 - update the version number for the image (if needed) by modifying __version__ in build-image.sh
  41 - setup your http_proxy if needed
  42 - run ``build-image.sh`` to build the images.  A few examples:
  43
  44     - to build all the images and publish the code to Google cloud storage:
  45         - ``bash build-image.sh``
  46     - to build and publish only the loop VM:
  47         - ``bash build-image.sh -l``
  48     - to build and publish only the generator VM:
  49         - ``bash build-image.sh -g``
  50     - to build the generator VM without publishing it:
  51         - ``bash build-image.sh -gv``
  52
  53 .. note:: Run ``bash build-image.sh`` -h to see all options available.
  54
  55 .. note:: By default, the generator VM image embeds the latest nfvbench code
  56           found at the time of the build on the master branch of NFVbench Git
  57           repository on OPNFV Gerrit instance (latest commit).
  58
  59           During development phases, it is also possible to build the image with
  60           all the committed changes found in the current working copy of
  61           nfvbench (local code).  To do that, run the image build with the ``-s``
  62           option, for instance: ``bash build-image.sh -gvs``.
  63
  64           In that case, the version of the generator VM image will be extended
  65           with nfvbench development version number to be able to distinguish the
  66           development images from the latest published image.
  67
  68 LOOP VM IMAGE INSTANCE AND CONFIG
  69 =================================
  70
  71 Interface Requirements
  72 ----------------------
  73 The instance must be launched using OpenStack with 2 network interfaces.
  74 For best performance, it should use a flavor with:
  75
  76 - 2 vCPU
  77 - 4 GB RAM
  78 - cpu pinning set to exclusive
  79
  80 Auto-configuration
  81 ------------------
  82 nfvbench VM will automatically find the two virtual interfaces to use, and use the forwarder specifed in the config file.
  83
  84 In the case testpmd is used, testpmd will be launched with mac forwarding mode where the destination macs rewritten according to the config file.
  85
  86 In the case VPP is used, VPP will set up a L3 router, and forwarding traffic from one port to the other.
  87
  88 nfvbenchvm Config
  89 -----------------
  90 nfvbenchvm config file is located at ``/etc/nfvbenchvm.conf``.
  91
  92 .. code-block:: bash
  93
  94     FORWARDER=testpmd
  95     INTF_MAC1=FA:16:3E:A2:30:41
  96     INTF_MAC2=FA:16:3E:10:DA:10
  97     TG_MAC1=00:10:94:00:0A:00
  98     TG_MAC2=00:11:94:00:0A:00
  99     VNF_GATEWAY1_CIDR=1.1.0.2/8
 100     VNF_GATEWAY2_CIDR=2.2.0.2/8
 101     TG_NET1=10.0.0.0/8
 102     TG_NET2=20.0.0.0/8
 103     TG_GATEWAY1_IP=1.1.0.100
 104     TG_GATEWAY2_IP=2.2.0.100
 105
 106
 107 Launching nfvbenchvm VM
 108 -----------------------
 109
 110 Normally this image will be used together with NFVBench, and the required configurations will be automatically generated and pushed to VM by NFVBench. If launched manually, no forwarder will be run. Users will have the full control to run either testpmd or VPP via VNC console.
 111
 112 To check if testpmd is running, you can run this command in VNC console:
 113
 114 .. code-block:: bash
 115
 116     sudo screen -r testpmd
 117
 118 To check if VPP is running, you can run this command in VNC console:
 119
 120 .. code-block:: bash
 121
 122     service vpp status
 123
 124
 125 Hardcoded Username and Password
 126 --------------------------------
 127 - Username: nfvbench
 128 - Password: nfvbench
 129
 130
 131 GENERATOR IMAGE INSTANCE AND CONFIG
 132 ===================================
 133
 134 Pre-requisites
 135 --------------
 136 To use openstack APIs, NFVbench generator VM will use `clouds.yaml` file as openstack configuration.
 137 The OpenStack clouds configuration from clouds.yaml file to use.
 138 clouds.yaml file must be in one of the following paths:
 139 - ~/.config/openstack
 140 - /etc/openstack
 141
 142 Example of `clouds.yaml`:
 143
 144 .. code-block:: yaml
 145
 146     clouds:
 147       devstack:
 148         auth:
 149           auth_url: http://192.168.122.10:35357/
 150           project_name: demo
 151           username: demo
 152           password: 0penstack
 153         region_name: RegionOne
 154
 155 .. note:: Add `CLOUD_DETAIL` property with the accurate value for your openstack configuration (`devstack` in the above example) in ``/etc/nfvbenchvm.conf``
 156
 157 Interface Requirements
 158 ----------------------
 159 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.
 160 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)
 161 and a flavor with:
 162
 163 - 6 vCPU
 164 - 8 GB RAM
 165 - cpu pinning set to exclusive
 166
 167 .. 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.
 168 .. note:: CPU pinning: 1 core dedicated for guest OS and NFVbench process, other provided cores are used by TRex
 169
 170 Template of a genarator profile using CPU pinning:
 171
 172 .. code-block:: bash
 173
 174     generator_profile:
 175         - name: {{name}}
 176           tool: {{tool}}
 177           ip: {{ip}}
 178           zmq_pub_port: {{zmq_pub_port}}
 179           zmq_rpc_port: {{zmq_rpc_port}}
 180           software_mode: {{software_mode}}
 181           cores: {{CORES}}
 182           platform:
 183             master_thread_id: '0'
 184             latency_thread_id: '1'
 185             dual_if:
 186               - socket: 0
 187                 threads: [{{CORE_THREADS}}]
 188
 189           interfaces:
 190             - port: 0
 191               pci: "{{PCI_ADDRESS_1}}"
 192               switch:
 193             - port: 1
 194               pci: "{{PCI_ADDRESS_2}}"
 195               switch:
 196           intf_speed:
 197
 198 .. note:: `CORE_THREADS` value is determined automatically based on the cores available on the VM starting from 2 to last worker core available.
 199
 200 Auto-configuration
 201 ------------------
 202 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).
 203 This applies to the management interface as well.
 204
 205 nfvbenchvm Config
 206 -----------------
 207 nfvbenchvm config file is located at ``/etc/nfvbenchvm.conf``.
 208
 209 Example of configuration:
 210
 211 .. code-block:: bash
 212
 213     ACTION=e2e
 214     LOOPBACK_INTF_MAC1=FA:16:3E:A2:30:41
 215     LOOPBACK_INTF_MAC2=FA:16:3E:10:DA:10
 216     E2E_INTF_MAC1=FA:16:3E:B0:E2:43
 217     E2E_INTF_MAC2=FA:16:3E:D3:6A:FC
 218
 219 .. note:: `ACTION` parameter is not mandatory but will permit to start NFVbench with the accurate ports (loopback or e2e).
 220 .. note:: Set of MAC parameters cannot be used in parallel as only one NFVbench/TRex process is running.
 221 .. 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.
 222
 223 nfvbenchvm config file with management interface:
 224
 225 .. code-block:: bash
 226
 227     ACTION=e2e
 228     LOOPBACK_INTF_MAC1=FA:16:3E:A2:30:41
 229     LOOPBACK_INTF_MAC2=FA:16:3E:10:DA:10
 230     INTF_MAC_MGMT=FA:16:3E:06:11:8A
 231     INTF_MGMT_CIDR=172.20.56.228/2
 232     INTF_MGMT_IP_GW=172.20.56.225
 233     INTF_MGMT_MTU=1500
 234
 235 .. 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.
 236
 237 .. note:: ``INTF_MGMT_MTU`` allows to specify the MTU of the management
 238           interface in bytes.
 239
 240           If ``INTF_MGMT_MTU`` is not specified, the MTU will be configured to
 241           the conservative value of 1500: this will reduce the risk to get an
 242           unmanageable VM.
 243
 244           ``INTF_MGMT_MTU`` can also be set to the special value ``auto``: in
 245           that case, the MTU will not be configured and it will keep the value
 246           set by the hypervisor (default nfvbench behavior up to version
 247           5.0.3).
 248
 249 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:
 250
 251 .. code-block:: bash
 252
 253     LOOPBACK_PORT_NAME1=nfvbench-pf1
 254     LOOPBACK_PORT_NAME2=nfvbench-pf2
 255     E2E_PORT_NAME1=nfvbench-pf1
 256     E2E_PORT_NAME1=nfvbench-pf3
 257     INTF_MAC_MGMT=FA:16:3E:06:11:8A
 258     INTF_MGMT_CIDR=172.20.56.228/2
 259     INTF_MGMT_IP_GW=172.20.56.225
 260     DNS_SERVERS=8.8.8.8,dns.server.com
 261
 262 .. 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).
 263 .. note:: NFVbench VM will call openstack API through the management interface to retrieve mac address for these ports
 264 .. 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 `,`)
 265
 266 Control nfvbenchvm VM and run test
 267 ----------------------------------
 268
 269 By default, NFVbench will be started in server mode (`--server`) and will act as an API.
 270
 271 NFVbench VM will be accessible through SSH or HTTP using the management interface IP.
 272
 273 NFVbench API endpoint is : `http://<management_ip>:<port>`
 274
 275 .. note:: by default port value is 7555
 276
 277 Get NFVbench status
 278 ^^^^^^^^^^^^^^^^^^^
 279
 280 To check NFVbench is up and running use REST request:
 281
 282 .. code-block:: bash
 283
 284     curl -XGET '<management_ip>:<port>/status'
 285
 286 Example of answer:
 287
 288 .. code-block:: bash
 289
 290     {
 291       "error_message": "nfvbench run still pending",
 292       "status": "PENDING"
 293     }
 294
 295 Start NFVbench test
 296 ^^^^^^^^^^^^^^^^^^^
 297
 298 To start a test run using NFVbench API use this type of REST request:
 299
 300 .. code-block:: bash
 301
 302     curl -XPOST '<management_ip>:<port>/start_run' -H "Content-Type: application/json" -d @nfvbenchconfig.json
 303
 304 Example of return when the submission is successful:
 305
 306 .. code-block:: bash
 307
 308     {
 309       "error_message": "NFVbench run still pending",
 310       "request_id": "42cccb7effdc43caa47f722f0ca8ec96",
 311       "status": "PENDING"
 312     }
 313
 314
 315 Start NFVbench test using Xtesting
 316 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 317
 318 To start a test run using Xtesting python library and NFVbench API use this type of command on the VM:
 319
 320 .. code-block:: bash
 321
 322     run_tests -t nfvbench-demo
 323
 324 .. note:: `-t` option determine which test case to be runned by Xtesting
 325  (see `xtesting/testcases.yaml` file content to see available list of test cases)
 326
 327
 328 Connect to the VM using SSH keypair
 329 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 330
 331 If a key is provided at VM creation you can use it to log on the VM using `cloud-user` username:
 332
 333 .. code-block:: bash
 334
 335     ssh -i key.pem cloud-user@<management_ip>
 336
 337
 338 Connect to VM using SSH username/password
 339 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 340
 341 VM is accessible over SSH using the hardcoded username and password (see below):
 342
 343 .. code-block:: bash
 344
 345     ssh nfvbench@<management_ip>
 346
 347
 348 Launching nfvbenchvm VM
 349 -----------------------
 350
 351 Normally this image will be deployed using Ansible role, and the required configurations will be automatically generated and pushed to VM by Ansible.
 352 If launched manually, users will have the full control to configure and run NFVbench via VNC console.
 353
 354 To check if NFVbench is running, you can run this command in VNC console:
 355
 356 .. code-block:: bash
 357
 358     sudo screen -r nfvbench
 359
 360
 361 Hardcoded Username and Password
 362 --------------------------------
 363 - Username: nfvbench
 364 - Password: nfvbench
 365