summaryrefslogtreecommitdiffstats
path: root/docs/testing/user/userguide/quickstart_docker.rst
blob: ae277de44f0ff9fc94d6b5199a7e1fcd978c36c5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. SPDX-License-Identifier: CC-BY-4.0
.. (c) Cisco Systems, Inc

===========================================
NFVbench Installation and Quick Start Guide
===========================================

.. _docker_installation:

Make sure you satisfy the `hardware and software requirements <requirements>` before you start .


NFVbench can be used in CLI mode or in REST server mode.
The CLI mode allows to run NFVbench benchmarks from the CLI. The REST server mode allows to run NFVbench benchmarks through a REST interface.

1. Container installation
-------------------------

To pull the latest NFVbench container image:

.. code-block:: bash

    docker pull opnfv/nfvbench

2. NFVbench configuration file
------------------------------

Create a directory under $HOME called nfvbench to store the minimal configuration file:

.. code-block:: bash

    mkdir $HOME/nfvbench

Create a new file containing the minimal configuration for NFVbench, we can call it any name, for example "nfvbench.cfg" and paste the following yaml template in the file:

.. code-block:: bash

  openrc_file: /tmp/nfvbench/openrc
  traffic_generator:
      generator_profile:
          - name: trex-local
            tool: TRex
            ip: 127.0.0.1
            cores: 3
            software_mode: false
            interfaces:
              - port: 0
                pci: "0a:00.0"
              - port: 1
                pci: "0a:00.1"
            intf_speed:

If OpenStack is not used, the openrc_file property can be removed.

If OpenStack is used, the openrc_file property must contain a valid container pathname of the OpenStack ``openrc`` file to connect to OpenStack using the OpenStack API.
This file can be downloaded from the OpenStack Horizon dashboard (refer to the OpenStack documentation on how to
retrieve the openrc file). This property must point to a valid pathname in the container (/tmp/nfvbench/openrc).
We will map the host $HOME/nfvbench directory to the container /tmp/nfvbench directory and name the file "openrc".
The file name viewed from the container will be "/tmp/nfvbench/openrc" (see container file pathname mapping in the next sections).

The PCI address of the 2 physical interfaces that will be used by the traffic generator must be configured.
The PCI address can be obtained for example by using the "lspci" Linux command. For example:

.. code-block:: bash

    [root@sjc04-pod6-build ~]# lspci | grep 710
    0a:00.0 Ethernet controller: Intel Corporation Ethernet Controller X710 for 10GbE SFP+ (rev 01)
    0a:00.1 Ethernet controller: Intel Corporation Ethernet Controller X710 for 10GbE SFP+ (rev 01)
    0a:00.2 Ethernet controller: Intel Corporation Ethernet Controller X710 for 10GbE SFP+ (rev 01)
    0a:00.3 Ethernet controller: Intel Corporation Ethernet Controller X710 for 10GbE SFP+ (rev 01)

In the above example, the PCI addresses "0a:00.0" and "0a:00.1" (first 2 ports of the quad port NIC) are used.

.. warning::

    You have to put quotes around the pci addresses as shown in the above example, otherwise TRex will read it wrong.
    The other fields in the minimal configuration must be present and must have the same values as above.


3. Starting NFVbench in CLI mode
--------------------------------

In this mode, the NFVbench code will reside in a container running in the background. This container will not run anything in the background.
An alias is then used to invoke a new NFVbench benchmark run using docker exec.
The $HOME/nfvbench directory on the host is mapped on the /tmp/nfvbench in the container to facilitate file sharing between the 2 environments.

Start NFVbench container
~~~~~~~~~~~~~~~~~~~~~~~~
The NFVbench container can be started using docker run command or using docker compose.

To run NFVBench in CLI mode using docker run:

.. code-block:: bash

    docker run --name nfvbench --detach --privileged -v /lib/modules/$(uname -r):/lib/modules/$(uname -r) -v /usr/src/kernels:/usr/src/kernels -v /dev:/dev -v $HOME/nfvbench:/tmp/nfvbench opnfv/nfvbench

+-------------------------------------------------------+-------------------------------------------------------+
| Docker options                                        | Description                                           |
+=======================================================+=======================================================+
| --name nfvbench                                       | container name is "nfvbench"                          |
+-------------------------------------------------------+-------------------------------------------------------+
| --detach                                              | run container in background                           |
+-------------------------------------------------------+-------------------------------------------------------+
| --privileged                                          | (optional) required if SELinux is enabled on the host |
+-------------------------------------------------------+-------------------------------------------------------+
| -v /lib/modules:/lib/modules                          | needed by kernel modules in the container             |
+-------------------------------------------------------+-------------------------------------------------------+
| -v /usr/src/kernels:/usr/src/kernels                  | needed by TRex to build kernel modules when needed    |
+-------------------------------------------------------+-------------------------------------------------------+
| -v /dev:/dev                                          | needed by kernel modules in the container             |
+-------------------------------------------------------+-------------------------------------------------------+
| -v $HOME/nfvbench:/tmp/nfvbench                       | folder mapping to pass files between the              |
|                                                       | host and the docker space (see examples below)        |
|                                                       | Here we map the $HOME/nfvbench directory on the host  |
|                                                       | to the /tmp/nfvbench director in the container.       |
|                                                       | Any other mapping can work as well                    |
+-------------------------------------------------------+-------------------------------------------------------+
| opnfv/nfvbench                                        | container image name                                  |
+-------------------------------------------------------+-------------------------------------------------------+

To run NFVbench using docker compose, create the docker-compose.yml file and paste the following content:

.. code-block:: bash

    version: '3'
    services:
        nfvbench:
            image: "opnfv/nfvbench"
            container_name: "nfvbench"
            volumes:
                - /dev:/dev
                - /usr/src/kernels:/usr/src/kernels
                - /lib/modules:/lib/modules
                - ${HOME}/nfvbench:/tmp/nfvbench
            network_mode: "host"
            privileged: true

Then start the container in detached mode:

.. code-block:: bash

    docker-compose up -d

Requesting an NFVbench benchmark run
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Create an alias to make it easy to execute nfvbench commands directly from the host shell prompt:

.. code-block:: bash

    alias nfvbench='docker exec -it nfvbench nfvbench'

The next to last "nfvbench" refers to the name of the container while the last "nfvbench" refers to the NFVbench binary that is available to run inside the container.

Once the alias is set, NFVbench runs can simply be requested from teh command line using "nfvbench <options>".

To verify it is working:

.. code-block:: bash

    nfvbench --version
    nfvbench --help

Example of run
~~~~~~~~~~~~~~

To do a single run at 10,000pps bi-directional (or 5kpps in each direction) using the PVP packet path:

.. code-block:: bash

   nfvbench -c /tmp/nfvbench/nfvbench.cfg --rate 10kpps

NFVbench options used:

* ``-c /tmp/nfvbench/nfvbench.cfg`` : specify the config file to use
* ``--rate 10kpps`` : specify rate of packets for test for both directions using the kpps unit (thousands of packets per second)


Retrieve complete configuration file as template
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The full configuration file template with comments (yaml format) can be obtained using the --show-default-config option in order to use more advanced configuration options:

.. code-block:: bash

    nfvbench --show-default-config > $HOME/nfvbench/full_nfvbench.cfg

Edit the full_nfvbench.cfg file to only keep those properties that need to be modified (preserving the nesting).


4. Start NFVbench in REST server mode
-------------------------------------
In this mode, the NFVbench REST server will run in the container.
The $HOME/nfvbench directory on the host is mapped on the /tmp/nfvbench in the container to facilitate file sharing between the 2 environments.

Start NFVbench container
~~~~~~~~~~~~~~~~~~~~~~~~

To start the NFVbench container with REST server using docker run cli:

.. code-block:: bash

    docker run --name nfvbench --detach --privileged --net=host -e CONFIG_FILE="/tmp/nfvbench/nfvbench.cfg" -v /lib/modules/$(uname -r):/lib/modules/$(uname -r) -v /usr/src/kernels:/usr/src/kernels -v /dev:/dev -v $HOME/nfvbench:/tmp/nfvbench opnfv/nfvbench start_rest_server

REST mode requires the same arguments as CLI mode and adds the following options:
+-------------------------------------------------------+-------------------------------------------------------+
| Docker options                                        | Description                                           |
+=======================================================+=======================================================+
| --net=host                                            | use "host" docker networking mode                     |
|                                                       | Other modes (such as NAT) could be used if required   |
|                                                       | with proper adjustment of the port to use for REST    |
+-------------------------------------------------------+-------------------------------------------------------+
| -e CONFIG_FILE="/tmp/nfvbench/nfvbench.cfg"           | (optional)                                            |
|                                                       | specify the initial NFVbench config file to use.      |
|                                                       | defaults to none                                      |
+-------------------------------------------------------+-------------------------------------------------------+
| start_rest_server                                     | to request a REST server to run in background in the  |
|                                                       | container                                             |
+-------------------------------------------------------+-------------------------------------------------------+
| -e HOST="127.0.0.1"                                   | (optional)                                            |
|                                                       | specify the IP address to listen to.                  |
|                                                       | defaults to 127.0.0.1                                 |
+-------------------------------------------------------+-------------------------------------------------------+
| -e PORT=7555                                          | (optional)                                            |
|                                                       | specify the port address to listen to.                |
|                                                       | defaults to 7555                                      |
+-------------------------------------------------------+-------------------------------------------------------+


The initial configuration file is optional but is handy to define mandatory deployment parameters that are common to all subsequent REST requests.
If this initial configuration file is not passed at container start time, it must be included in every REST request.

To start the NFVbench container with REST server using docker compose, use the following compose file:

.. code-block:: bash

    version: '3'
    services:
        nfvbench:
            image: "opnfv/nfvbench"
            container_name: "nfvbench_server"
            command: start_rest_server
            volumes:
                - /dev:/dev
                - /usr/src/kernels:/usr/src/kernels
                - /lib/modules:/lib/modules
                - ${HOME}/nfvbench:/tmp/nfvbench
            network_mode: "host"
            environment:
                - HOST="127.0.0.1"
                - PORT=7555
            privileged: true

Requesting an NFVbench benchmark run
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To request a benchmark run, you must create a JSON document that describes the benchmark and send it to the NFVbench server in the body of a POST request.


Examples of REST requests
~~~~~~~~~~~~~~~~~~~~~~~~~
In this example, we will use curl to interact with the NFVbench REST server.

Query the NFVbench version:

.. code-block:: bash

    [root@sjc04-pod3-mgmt ~]# curl -G http://127.0.0.1:7555/version
    3.1.1

This is the JSON for a fixed rate run at 10,000pps bi-directional (or 5kpps in each direction) using the PVP packet path:

.. code-block:: bash

    {"rate": "10kpps"}

This is the curl request to send this benchmark request to the NFVbench server:

.. code-block:: bash

    [root@sjc04-pod3-mgmt ~]# curl -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"rate": "10kpps"}' http://127.0.0.1:7555/start_run
    {
      "error_message": "nfvbench run still pending",
      "status": "PENDING"
    }
    [root@sjc04-pod3-mgmt ~]#

This request will return immediately with status set to "PENDING" if the request was started successfully.

The status can be polled until the run completes. Here the poll returns a "PENDING" status, indicating the run is still not completed:

.. code-block:: bash

    [root@sjc04-pod3-mgmt ~]# curl -G http://127.0.0.1:7555/status
    {
      "error_message": "nfvbench run still pending",
      "status": "PENDING"
    }
    [root@sjc04-pod3-mgmt ~]#

Finally, the status request returns a "OK" status along with the full results (truncated here):

.. code-block:: bash

    [root@sjc04-pod3-mgmt ~]# curl -G http://127.0.0.1:7555/status
    {
      "result": {
        "benchmarks": {
          "network": {
            "service_chain": {
              "PVP": {
                "result": {
                  "bidirectional": true,

    ...

      "status": "OK"
    }
    [root@sjc04-pod3-mgmt ~]#


Retrieve complete configuration file as template
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


7. Terminating the NFVbench container
-------------------------------------
When no longer needed, the container can be terminated using the usual docker commands:

.. code-block:: bash

    docker kill nfvbench
    docker rm nfvbench