nfvbenchvm/README.rst

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