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