FIX: Hardware sections - report
[csit.git] / docs / vpp-device.rst
1 Integration Tests
2 =================
3
4 Abstract
5 --------
6
7 FD.io VPP software data plane technology has become very popular across
8 a wide range of VPP eco-system use cases, putting higher pressure on
9 continuous verification of VPP software quality.
10
11 This document describes a proposal for design and implementation of extended
12 continuous VPP testing by extending existing test environments.
13 Furthermore it describes and summarizes implementation details of Integration
14 and System tests platform *1-Node VPP_Device*. It aims to provide a complete
15 end-to-end view of *1-Node VPP_Device* environment in order to improve
16 extendability and maintenance, under the guideline of VPP core team.
17
18 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
19 "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this document are to be
20 interpreted as described in :rfc:`8174`.
21
22 Overview
23 --------
24
25 .. only:: latex
26
27     .. raw:: latex
28
29         \begin{figure}[H]
30             \centering
31                 \graphicspath{{../_tmp/src/vpp_device_tests/}}
32                 \includegraphics[width=0.90\textwidth]{vpp_device}
33                 \label{fig:vpp_device}
34         \end{figure}
35
36 .. only:: html
37
38     .. figure:: vpp_device.svg
39         :alt: vpp_device
40         :align: center
41
42 Physical Testbeds
43 -----------------
44
45 All :abbr:`FD.io (Fast Data Input/Ouput)` :abbr:`CSIT (Continuous System
46 Integration and Testing)` vpp-device tests are executed on physical testbeds
47 built with bare-metal servers hosted by :abbr:`LF (Linux Foundation)` FD.io
48 project. Two 1-node testbed topologies are used:
49
50 - **2-Container Topology**: Consisting of one Docker container acting as SUT
51   (System Under Test) and one Docker container as TG (Traffic Generator), both
52   connected in ring topology via physical NIC cross-connecting.
53
54 Current FD.io production testbeds are built with servers based on one
55 processor generation of Intel Xeons: Skylake (Platinum 8180). Testbeds built
56 with servers based on Arm processors are in the process of being added to FD.io
57 production.
58
59 Following section describe existing production 1n-skx testbed.
60
61 1-Node Xeon Skylake (1n-skx)
62 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
63
64 1n-skx testbed is based on single SuperMicro SYS-7049GP-TRT server equipped with
65 two Intel Xeon Skylake Platinum 8180 2.5 GHz 28 core processors. Physical
66 testbed topology is depicted in a figure below.
67
68 .. only:: latex
69
70     .. raw:: latex
71
72         \begin{figure}[H]
73             \centering
74                 \graphicspath{{../_tmp/src/vpp_device_tests/}}
75                 \includegraphics[width=0.90\textwidth]{vf-2n-nic2nic}
76                 \label{fig:vf-2n-nic2nic}
77         \end{figure}
78
79 .. only:: html
80
81     .. figure:: vf-2n-nic2nic.svg
82         :alt: vf-2n-nic2nic
83         :align: center
84
85 Server is populated with the following NIC models:
86
87 #. NIC-1: x710-da4 4p10GE Intel.
88 #. NIC-2: x710-da4 4p10GE Intel.
89
90 All Intel Xeon Skylake servers run with Intel Hyper-Threading enabled,
91 doubling the number of logical cores exposed to Linux, with 56 logical
92 cores and 28 physical cores per processor socket.
93
94 NIC interfaces are shared using Linux vfio_pci and VPP VF drivers:
95
96 - DPDK VF driver,
97 - Fortville AVF driver.
98
99 Provided Intel x710-da4 4p10GE NICs support 32 VFs per interface, 128 per NIC.
100
101 Complete 1n-skx testbeds specification is available on `CSIT LF Testbeds
102 <https://wiki.fd.io/view/CSIT/Testbeds:_Xeon_Skx,_Arm,_Atom.>`_ wiki page.
103
104 Total of two 1n-skx testbeds are in operation in FD.io labs.
105
106 1-Node Virtualbox (1n-vbox)
107 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
108
109 1n-skx testbed can run in single VirtualBox VM machine. This solution replaces
110 the previously used Vagrant environment based on 3 VMs.
111
112 VirtualBox VM MAY be created by Vagrant and MUST have additional 4 virtio NICs
113 each pair attached to separate private networks to simulate back-to-back
114 connections. It SHOULD be 82545EM device model (otherwise can be changed in
115 boostrap scripts). Example of Vagrant configuration:
116
117 ::
118
119     Vagrant.configure(2) do |c|
120       c.vm.network "private_network", type: "dhcp", auto_config: false,
121           virtualbox__intnet: "port1", nic_type: "82545EM"
122       c.vm.network "private_network", type: "dhcp", auto_config: false,
123           virtualbox__intnet: "port2", nic_type: "82545EM"
124
125       c.vm.provider :virtualbox do |v|
126         v.customize ["modifyvm", :id, "--nicpromisc2", "allow-all"]
127         v.customize ["modifyvm", :id, "--nicpromisc3", "allow-all"]
128         v.customize ["modifyvm", :id, "--nicpromisc4", "allow-all"]
129         v.customize ["modifyvm", :id, "--nicpromisc5", "allow-all"]
130
131 Vagrant VM is populated with the following NIC models:
132
133 #. NIC-1: 82545EM Intel.
134 #. NIC-2: 82545EM Intel.
135 #. NIC-3: 82545EM Intel.
136 #. NIC-4: 82545EM Intel.
137
138 Containers
139 ----------
140
141 It was agreed on :abbr:`TWS (Technical Work Stream)` call to continue with
142 Ubuntu 18.04 LTS as a baseline system with OPTIONAL extend to Centos 7 and
143 SuSE per demand [TWSLink]_.
144
145 All :abbr:`DCR (Docker container)` images are REQUIRED to be hosted on Docker
146 registry available from LF network, publicly available and trackable. For
147 backup, tracking and contributing purposes all Dockerfiles (including files
148 needed for building container) MUST be available and stored in [fdiocsitgerrit]_
149 repository under appropriate folders. This allows the peer review process to be
150 done for every change of infrastructure related to scope of this document.
151 Currently only **csit-shim-dcr** and **csit-sut-dcr** containers will be stored
152 and maintained under CSIT repository by CSIT contributors.
153
154 At the time of designing solution described in this document the interconnection
155 between [dockerhub]_ and  [fdiocsitgerrit]_ for automated build purposes and
156 image hosting cannot be established with the trust and respectful to
157 security of FD.io project. Unless adressed, :abbr:`DCR` images will be placed in
158 custom registry service [fdioregistry]_. Automated Jenkins jobs will be created
159 in align of long term solution for container lifecycle and ability to build
160 new version of docker images.
161
162 In parallel, the effort is started to find the outsourced Docker registry
163 service.
164
165 Versioning
166 ~~~~~~~~~~
167
168 As of initial version of vpp-device, we do have only single latest version of
169 Docker image hosted on [dockerhub]_. This will be addressed as further
170 improvement with proper semantic versioning.
171
172 jenkins-slave-dcr
173 ~~~~~~~~~~~~~~~~~
174
175 This :abbr:`DCR` acts as the Jenkins slave (known also as jenkins minion). It
176 can connect over SSH protocol to TCP port 6022 of **csit-shim-dcr** and executes
177 non-interactive reservation script. Nomad is responsible for scheduling this
178 container execution onto specific **1-Node VPP_Device** testbed. It executes
179 :abbr:`CSIT` environment including :abbr:`CSIT` framework.
180
181 All software dependencies including VPP/DPDK that are not present in
182 **csit-sut-dcr** container image and/or needs to be compiled prior running on
183 **csit-sut-dcr** SHOULD be compiled in this container.
184
185 - *Container Image Location*: Docker image at snergster/vpp-ubuntu18.
186
187 - *Container Definition*: Docker file specified at [JenkinsSlaveDcrFile]_.
188
189 - *Initializing*: Container is initialized from within *Consul by HashiCorp*
190   and *Nomad by HashiCorp*.
191
192 csit-shim-dcr
193 ~~~~~~~~~~~~~
194
195 This :abbr:`DCR` acts as an intermediate layer running script responsible for
196 orchestrating topologies under test and reservation. Responsible for managing VF
197 resources and allocation to :abbr:`DUT (Device Under Test)`, :abbr:`TG
198 (Traffic Generator)` containers. This MUST to be done on **csit-shim-dcr**.
199 This image also acts as the generic reservation mechanics arbiter to make sure
200 that only Y number of simulations are spawned on any given HW node.
201
202 - *Container Image Location*: Docker image at snergster/csit-shim.
203
204 - *Container Definition*: Docker file specified at [CsitShimDcrFile]_.
205
206 - *Initializing*: Container is initialized from within *Consul by HashiCorp*
207   and *Nomad by HashiCorp*. Required docker parameters, to be able to run
208   nested containers with VF reservation system are: privileged, net=host,
209   pid=host.
210
211 - *Connectivity*: Over SSH only, using <host>:6022 format. Currently using
212   *root* user account as primary. From the jenkins slave it will be able to
213   connect via env variable, since the jenkins slave doesn't actually know what
214   host its running on.
215
216   ::
217
218       ssh -p 6022 root@10.30.51.node
219
220 csit-sut-dcr
221 ~~~~~~~~~~~~
222
223 This :abbr:`DCR` acts as an :abbr:`SUT (System Under Test)`. Any :abbr:`DUT` or
224 :abbr:`TG` application is installed there. It is RECOMMENDED to install DUT and
225 all DUT dependencies via commands ``rpm -ihv`` on RedHat based OS or ``dpkg -i``
226 on Debian based OS.
227
228 Container is designed to be a very lightweight Docker image that only installs
229 packages and execute binaries (previously built or downloaded on
230 **jenkins-slave-dcr**) and contains libraries necessary to run CSIT framework
231 including those required by DUT/TG.
232
233 - *Container Image Location*: Docker image at snergster/csit-sut.
234
235 - *Container Definition*: Docker file specified at [CsitSutDcrFile]_.
236
237 - *Initializing*:
238   ::
239
240     docker run
241     # Run the container in the background and print the new container ID.
242     --detach=true
243     # Give extended privileges to this container. A "privileged" container is
244     # given access to all devices and able to run nested containers.
245     --privileged
246     # Publish all exposed ports to random ports on the host interfaces.
247     --publish-all
248     # Automatically remove the container when it exits.
249     --rm
250     # Size of /dev/shm.
251     --shm-size 512M
252     # Override access to PCI bus by attaching a filesystem mount to the
253     # container.
254     --mount type=tmpfs,destination=/sys/bus/pci/devices
255     # Mount vfio to be able to bind to see binded interfaces. We cannot use
256     # --device=/dev/vfio as this does not see newly binded interfaces.
257     --volume /dev/vfio:/dev/vfio
258     # Mount nested_vm image to be able to run VM tests.
259     --volume /var/lib/vm/vhost-nested.img:/var/lib/vm/vhost-nested.img
260     # Mount docker.sock to be able to use docker deamon of the host.
261     --volume /var/run/docker.sock:/var/run/docker.sock
262     # Image of csit-sut-dcr
263     snergster/csit-vpp-device-test:latest
264
265   Container name is catenated from **csit-** prefix and uuid generated uniquely
266   for each container instance.
267
268 - *Connectivity*: Over SSH only, using <host>[:<port>] format. Currently using
269   *root* user account as primary.
270   ::
271
272     ssh -p <port> root@10.30.51.<node>
273
274 Container required to run as ``--privileged`` due to ability to create nested
275 containers and have full read/write access to sysfs (for bind/unbind). Docker
276 automatically pick free network port (``--publish-all``) for ability to connect
277 over ssh. To be able to limit access to PCI bus, container is creating tmpfs
278 mount type in PCI bus tree. CSIT reservation script is dynamically linking only
279 PCI devices (NIC cards) that are reserved for particular container. This
280 way it is not colliding with other containers. To make vfio work, access to
281 ``/dev/vfio`` must be granted.
282
283 .. todo: Change default user to testuser with non-privileged and install sudo.
284
285 Environment initialization
286 --------------------------
287
288 All 1-node servers are to be managed and provisioned via the [ansiblelink]_ set
289 of playbooks with *vpp-device* role. Full playbooks can be found under
290 [fdiocsitansible]_ directory. This way we are able to track all configuration
291 changes of physical servers in gerrit (in structured yaml format) as well as we
292 are able to extend *vpp-device* to additional servers with less effort or
293 re-stage servers in case of failure.
294
295 SR-IOV VF initialization is done via ``systemd`` service during host system boot
296 up. Service with name *csit-initialize-vfs.service* is created under systemd
297 system context (``/etc/systemd/system/``). By default service is calling
298 ``/usr/local/bin/csit-initialize-vfs.sh`` with single parameter:
299
300 - **start**: Creates maximum number of :abbr:`virtual functions (VFs)` (detected
301   from ``sriov_totalvfs``) for each whitelisted PCI device.
302 - **stop**: Removes all :abbr:`VFs` for all whitelisted PCI device.
303
304 Service is considered active even when all of its processes exited successfully.
305 Stopping service will automatically remove :abbr:`VFs`.
306
307 ::
308
309     [Unit]
310     Description=CSIT Initialize SR-IOV VFs
311     After=network.target
312
313     [Service]
314     Type=one-shot
315     RemainAfterExit=True
316     ExecStart=/usr/local/bin/csit-initialize-vfs.sh start
317     ExecStop=/usr/local/bin/csit-initialize-vfs.sh stop
318
319     [Install]
320     WantedBy=default.target
321
322 Script is driven by two array variables ``pci_blacklist``/``pci_whitelist``.
323 They MUST store all PCI addresses in **<domain>:<bus>:<device>.<func>** format,
324 where:
325
326 - **pci_blacklist**: PCI addresses to be skipped from :abbr:`VFs`
327   initialization (usefull for e.g. excluding management network interfaces).
328 - **pci_whitelist**: PCI addresses to be included for :abbr:`VFs`
329   initialization.
330
331 VF reservation
332 --------------
333
334 During topology initialization phase of script, mutex is used to avoid multiple
335 instances of script to interact with each other during resources allocation.
336 Mutal exclusion ensure that no two distinct instances of script will get same
337 resource list.
338
339 Reservation function reads the list of all available virtual function network
340 devices in system:
341
342 ::
343
344     net_path="/sys/bus/pci/devices/*/net/*"
345
346     for netdev in \
347         $(find ${net_path} -type d -name . -o -prune -exec basename '{}' ';');
348     do
349         if grep -q "${pci_id}" "/sys/class/net/${netdev}/device/device"; then
350             # found VF
351         fi
352     done
353
354 Where ``${pci_id}`` is ID of white-listed VF PCI ID. For more information please
355 see [pciids]_. This act as security constraint to prevent taking other unwanted
356 interfaces.
357 The output list of all VF network devices is split into two lists for TG and
358 SUT side of connection. First two items from each TG or SUT network devices
359 list are taken to expose directly to namespace of container. This can be done
360 via commands:
361
362 ::
363
364     $ ip link set ${netdev} netns ${DCR_CPIDS[tg]}
365     $ ip link set ${netdev} netns ${DCR_CPIDS[dut1]}
366
367 In this stage also symbolic links to PCI devices under sysfs bus directory tree
368 are created in running containers. Once VF devices are assigned to container
369 namespace and PCI deivces are linked to running containers and mutex is exited.
370 Selected VF network device automatically dissapear from parent container
371 namespace, so another instance of script will not find device under that
372 namespace.
373
374 Once Docker container exits, network device is returned back into parent
375 namespace and can be reused.
376
377 Network traffic isolation - Intel i40evf
378 ----------------------------------------
379
380 In a virtualized environment, on Intel(R) Server Adapters that support SR-IOV,
381 the virtual function (VF) may be subject to malicious behavior. Software-
382 generated layer two frames, like IEEE 802.3x (link flow control), IEEE 802.1Qbb
383 (priority based flow-control), and others of this type, are not expected and
384 can throttle traffic between the host and the virtual switch, reducing
385 performance. To resolve this issue, configure all SR-IOV enabled ports for
386 VLAN tagging. This configuration allows unexpected, and potentially malicious,
387 frames to be dropped. [inteli40e]_
388
389 To configure VLAN tagging for the ports on an SR-IOV enabled adapter,
390 use the following command. The VLAN configuration SHOULD be done
391 before the VF driver is loaded or the VM is booted. [inteli40e]_
392
393 ::
394
395     $ ip link set dev <PF netdev id> vf <id> vlan <vlan id>
396
397 For example, the following instructions will configure PF eth0 and
398 the first VF on VLAN 10.
399
400 ::
401
402     $ ip link set dev eth0 vf 0 vlan 10
403
404 VLAN Tag Packet Steering allows to send all packets with a specific VLAN tag to
405 a particular SR-IOV virtual function (VF). Further, this feature allows to
406 designate a particular VF as trusted, and allows that trusted VF to request
407 selective promiscuous mode on the Physical Function (PF). [inteli40e]_
408
409 To set a VF as trusted or untrusted, enter the following command in the
410 Hypervisor:
411
412 ::
413
414   $ ip link set dev eth0 vf 1 trust [on|off]
415
416 Once the VF is designated as trusted, use the following commands in the VM
417 to set the VF to promiscuous mode. [inteli40e]_
418
419 - For promiscuous all:
420   ::
421
422       $ ip link set eth2 promisc on
423
424 - For promiscuous Multicast:
425   ::
426
427       $ ip link set eth2 allmulti on
428
429 .. note::
430
431     By default, the ethtool priv-flag vf-true-promisc-support is set to
432     *off*, meaning that promiscuous mode for the VF will be limited. To set the
433     promiscuous mode for the VF to true promiscuous and allow the VF to see
434     all ingress traffic, use the following command.
435     $ ethtool set-priv-flags p261p1 vf-true-promisc-support on
436     The vf-true-promisc-support priv-flag does not enable promiscuous mode;
437     rather, it designates which type of promiscuous mode (limited or true)
438     you will get when you enable promiscuous mode using the ip link commands
439     above. Note that this is a global setting that affects the entire device.
440     However,the vf-true-promisc-support priv-flag is only exposed to the first
441     PF of the device. The PF remains in limited promiscuous mode (unless it
442     is in MFP mode) regardless of the vf-true-promisc-support setting.
443     [inteli40e]_
444
445 Service described earlier *csit-initialize-vfs.service* is responsible for
446 assigning 802.1Q vlan tagging to each vitual function via physical function
447 from list of white-listed PCI addresses by following (simplified) code.
448
449 ::
450
451     pci_idx=0
452     for pci_addr in ${pci_whitelist[@]}; do
453         pci_path="/sys/bus/pci/devices/${pci_addr}"
454         pf=$(basename "${pci_path}"/net/*)
455         for vf in $(seq "${sriov_totalvfs}"); do
456             # PCI address index in array (pairing siblings).
457             vlan_pf_idx=$(( pci_idx % (${#pci_whitelist[@]} / 2) ))
458             # 802.1Q base offset.
459             vlan_bs_off=1100
460             # 802.1Q PF PCI address offset.
461             vlan_pf_off=$(( vlan_pf_idx * 100 + vlan_bs_off ))
462             # 802.1Q VF PCI address offset.
463             vlan_vf_off=$(( vlan_pf_off + vf - 1 ))
464             # VLAN string.
465             vlan_str="vlan ${vlan_vf_off}"
466             # MAC string.
467             mac5="$(printf '%x' ${pci_idx})"
468             mac6="$(printf '%x' $(( vf - 1 )))"
469             mac_str="mac ba:dc:0f:fe:${mac5}:${mac6}"
470             # Set 802.1Q VLAN id and MAC address
471             ip link set ${pf} vf $(( vf - 1 )) ${mac_str} ${vlan_str}
472             ip link set ${pf} vf $(( vf - 1 )) trust on
473             ip link set ${pf} vf $(( vf - 1 )) spoof off
474         done
475         pci_idx=$(( pci_idx + 1 ))
476     done
477
478 Assignment starts at VLAN 1100 and incrementing by 1 for each VF and by 100 for
479 each white-listed PCI address up to the middle of the PCI list. Second half of
480 the lists is assumed to be directly (cable) paired siblings and assigned with
481 same 802.1Q VLANs as its siblings.
482
483 Open tasks
484 ----------
485
486 Security
487 ~~~~~~~~
488
489 .. note::
490
491     Switch to non-privileged containers: As of now all three container
492     flavors are using privileged containers to make it working. Explore options
493     to switch containers to non-privileged with explicit rather implicit
494     privileges.
495
496 .. note::
497
498     Switch to testuser account intead of root.
499
500 Maintainability
501 ~~~~~~~~~~~~~~~
502
503 .. note::
504
505     Docker image distribution: Create jenkins jobs with full pipiline of
506     CI/CD for CSIT Docker images.
507
508 Stability
509 ~~~~~~~~~
510
511 .. note::
512
513     Implement queueing mechanism: Currently there is no mechanics that
514     would place starving jobs in queue in case of no resources available.
515
516 .. note::
517
518     Replace reservation script with Docker network plugin written in
519     GOLANG/SH/Python - platform independent.
520
521 Links
522 -----
523
524 .. [TWSLink] `TWS <https://wiki.fd.io/view/CSIT/TWS>`_
525 .. [dockerhub] `Docker hub <https://hub.docker.com/>`_
526 .. [fdiocsitgerrit] `FD.io/CSIT gerrit <https://gerrit.fd.io/r/CSIT>`_
527 .. [fdioregistry] `FD.io registy <registry.fdiopoc.net>`_
528 .. [JenkinsSlaveDcrFile] `jenkins-slave-dcr-file <https://github.com/snergfdio/multivppcache/blob/master/ubuntu18/Dockerfile>`_
529 .. [CsitShimDcrFile] `csit-shim-dcr-file <https://github.com/snergfdio/multivppcache/blob/master/csit-shim/Dockerfile>`_
530 .. [CsitSutDcrFile] `csit-sut-dcr-file <https://github.com/snergfdio/multivppcache/blob/master/csit-sut/Dockerfile>`_
531 .. [ansiblelink] `ansible <https://www.ansible.com/>`_
532 .. [fdiocsitansible] `Fd.io/CSIT ansible <https://git.fd.io/csit/tree/resources/tools/testbed-setup/ansible>`_
533 .. [inteli40e] `Intel i40e <https://downloadmirror.intel.com/26370/eng/readme.txt>`_
534 .. [pciids] `pci ids <http://pci-ids.ucw.cz/v2.2/pci.ids>`_