a61738653a648cbf2a952f414e18f6b6d40046c5
[csit.git] / docs / report / vpp_performance_tests / documentation / containers.rst
1
2 .. _containter_orchestration_in_csit:
3
4 Container Orchestration in CSIT
5 ===============================
6
7 Overview
8 --------
9
10 Linux Containers
11 ~~~~~~~~~~~~~~~~
12
13 Linux Containers is an OS-level virtualization method for running
14 multiple isolated Linux systems (containers) on a compute host using a
15 single Linux kernel. Containers rely on Linux kernel cgroups
16 functionality for controlling usage of shared system resources (i.e.
17 CPU, memory, block I/O, network) and for namespace isolation. The latter
18 enables complete isolation of applications' view of operating
19 environment, including process trees, networking, user IDs and mounted
20 file systems.
21
22 :abbr:`LXC (Linux Containers)` combine kernel's cgroups and support for isolated
23 namespaces to provide an isolated environment for applications. Docker
24 does use LXC as one of its execution drivers, enabling image management
25 and providing deployment services. More information in [lxc]_, [lxc-namespace]_
26 and [stgraber]_.
27
28 Linux containers can be of two kinds: privileged containers and
29 unprivileged containers.
30
31 Unprivileged Containers
32 ~~~~~~~~~~~~~~~~~~~~~~~
33
34 Running unprivileged containers is the safest way to run containers in a
35 production environment. From LXC 1.0 one can start a full system
36 container entirely as a user, allowing to map a range of UIDs on the
37 host into a namespace inside of which a user with UID 0 can exist again.
38 In other words an unprivileged container does mask the userid from the
39 host, making it impossible to gain a root access on the host even if a
40 user gets root in a container. With unprivileged containers, non-root
41 users can create containers and will appear in the container as the
42 root, but will appear as userid <non-zero> on the host. Unprivileged
43 containers are also better suited to supporting multi-tenancy operating
44 environments. More information in [lxc-security]_ and [stgraber]_.
45
46 Privileged Containers
47 ~~~~~~~~~~~~~~~~~~~~~
48
49 Privileged containers do not mask UIDs, and container UID 0 is mapped to
50 the host UID 0. Security and isolation is controlled by a good
51 configuration of cgroup access, extensive AppArmor profile preventing
52 the known attacks as well as container capabilities and SELinux. Here a
53 list of applicable security control mechanisms:
54
55 - Capabilities - keep (whitelist) or drop (blacklist) Linux capabilities,
56   [capabilities]_.
57 - Control groups - cgroups, resource bean counting, resource quotas, access
58   restrictions, [cgroup1]_, [cgroup2]_.
59 - AppArmor - apparmor profiles aim to prevent any of the known ways of
60   escaping a container or cause harm to the host, [apparmor]_.
61 - SELinux - Security Enhanced Linux is a Linux kernel security module
62   that provides similar function to AppArmor, supporting access control
63   security policies including United States Department of Defense–style
64   mandatory access controls. Mandatory access controls allow an
65   administrator of a system to define how applications and users can
66   access different resources such as files, devices, networks and inter-
67   process communication, [selinux]_.
68 - Seccomp - secure computing mode, enables filtering of system calls,
69   [seccomp]_.
70
71 More information in [lxc-security]_ and [lxc-sec-features]_.
72
73 **Linux Containers in CSIT**
74
75 CSIT is using Privileged Containers as the ``sysfs`` is mounted with RW
76 access. Sysfs is required to be mounted as RW due to VPP accessing
77 :command:`/sys/bus/pci/drivers/uio_pci_generic/unbind`. This is not the case of
78 unprivileged containers where ``sysfs`` is mounted as read-only.
79
80
81 Orchestrating Container Lifecycle Events
82 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
83
84 Following Linux container lifecycle events need to be addressed by an
85 orchestration system:
86
87 1. Acquire - acquiring/downloading existing container images via
88    :command:`docker pull` or :command:`lxc-create -t download`.
89
90 2. Build - building a container image from scratch or another
91    container image via :command:`docker build <dockerfile/composefile>` or
92    customizing LXC templates in
93    `https://github.com/lxc/lxc/tree/master/templates`_
94
95 3. (Re-)Create - creating a running instance of a container application
96    from anew, or re-creating one that failed. A.k.a. (re-)deploy via
97    :command:`docker run` or :command:`lxc-start`
98
99 4. Execute - execute system operations within the container by attaching to
100    running container. THis is done by :command:`lxc-attach` or
101    :command:`docker exec`
102
103 5. Distribute - distributing pre-built container images to the compute
104    nodes. Currently not implemented in CSIT.
105
106
107 Container Orchestration Systems Used in CSIT
108 --------------------------------------------
109
110 Current CSIT testing framework integrates following Linux container
111 orchestration mechanisms:
112
113 - LXC/Docker for complete VPP container lifecycle control.
114 - Combination of Kubernetes (container orchestration), Docker (container
115   images) and Ligato (container networking).
116
117 LXC
118 ~~~
119
120 LXC is the well-known and heavily tested low-level Linux container
121 runtime [lxc-source]_, that provides a userspace interface for the Linux kernel
122 containment features. With a powerful API and simple tools, LXC enables
123 Linux users to easily create and manage system or application
124 containers. LXC uses following kernel features to contain processes:
125
126 - Kernel namespaces: ipc, uts, mount, pid, network and user.
127 - AppArmor and SELinux security profiles.
128 - Seccomp policies.
129 - Chroot.
130 - Cgroups.
131
132 CSIT uses LXC runtime and LXC usertools to test VPP data plane performance in
133 a range of virtual networking topologies.
134
135 **Known Issues**
136
137 - Current CSIT restriction: only single instance of lxc runtime due to
138   the cgroup policies used in CSIT. There is plan to add the capability into
139   code to create cgroups per container instance to address this issue. This sort
140   of functionality is better supported in LXC 2.1 but can be done is current
141   version as well.
142
143 - CSIT code is currently using cgroup control the range of CPU cores the
144   container must run on. VPP thread pinning defined vpp startup.conf.
145
146 Docker
147 ~~~~~~
148
149 Docker builds on top of Linux kernel containment features, and
150 offers a high-level tool for wrapping the processes, maintaining and
151 executing them in containers [docker]_. Currently it using *runc* a CLI tool for
152 spawning and running containers according to the `OCI specification
153 <https://www.opencontainers.org/>`_
154
155 A Docker container image is a lightweight, stand-alone, executable
156 package of a piece of software that includes everything needed to run
157 it: code, runtime, system tools, system libraries, settings.
158
159 CSIT uses Docker to manage the maintenance and execution of
160 containerized applications used in CSIT performance tests.
161
162 - Data plane thread pinning to CPU cores - Docker CLI and/or Docker
163   configuration file controls the range of CPU cores the Docker image
164   must run on. VPP thread pinning defined vpp startup.conf.
165
166 Kubernetes
167 ~~~~~~~~~~
168
169 Kubernetes [k8s-doc]_, or K8s, is a production-grade container orchestration
170 platform for automating the deployment, scaling and operating
171 application containers. Kubernetes groups containers that make up an
172 application into logical units, pods, for easy management and discovery.
173 K8s pod definitions including compute resource allocation is provided in
174 .yaml files.
175
176 CSIT uses K8s and its infrastructure components like etcd to control all
177 phases of container based virtualized network topologies.
178
179 **Open Questions**
180
181 - Clarify the functions provided by Contiv and Calico in Ligato system?
182
183 Ligato
184 ~~~~~~
185
186 Ligato [ligato]_ is an open-source project developing a set of cloud-native
187 tools for orchestrating container networking. Ligato integrates with FD.io VPP
188 using goVPP [govpp]_ and vpp-agent [vpp-agent]_.
189
190 **Known Issues**
191
192 **Open Questions**
193
194 - Currently using a separate LF Jenkins job for building csit-centric
195   prod_vpp_agent docker images vs. dockerhub/ligato ones.
196
197 Implementation
198 --------------
199
200 CSIT container orchestration is implemented in CSIT Level-1 keyword
201 Python libraries following the Builder design pattern. Builder design
202 pattern separates the construction of a complex object from its
203 representation, so that the same construction process can create
204 different representations e.g. LXC, Docker, other.
205
206 CSIT Robot Framework keywords are then responsible for higher level
207 lifecycle control of of the named container groups. One can have
208 multiple named groups, with 1..N containers in a group performing
209 different role/functionality e.g. NFs, Switch, Kafka bus, ETCD
210 datastore, etc. ContainerManager class acts as a Director and uses
211 ContainerEngine class that encapsulate container control.
212
213 Current CSIT implementation is illustrated using UML Class diagram:
214
215 1. Acquire
216 2. Build
217 3. (Re-)Create
218 4. Execute
219
220 ::
221
222  +-----------------------------------------------------------------------+
223  |              RF Keywords (high level lifecycle control)               |
224  +-----------------------------------------------------------------------+
225  | Construct VNF containers on all DUTs                                  |
226  | Acquire all '${group}' containers                                     |
227  | Create all '${group}' containers                                      |
228  | Install all '${group}' containers                                     |
229  | Configure all '${group}' containers                                   |
230  | Stop all '${group}' containers                                        |
231  | Destroy all '${group}' containers                                     |
232  +-----------------+-----------------------------------------------------+
233                    |  1
234                    |
235                    |  1..N
236  +-----------------v-----------------+        +--------------------------+
237  |          ContainerManager         |        |  ContainerEngine         |
238  +-----------------------------------+        +--------------------------+
239  | __init()__                        |        | __init(node)__           |
240  | construct_container()             |        | acquire(force)           |
241  | construct_containers()            |        | create()                 |
242  | acquire_all_containers()          |        | stop()                   |
243  | create_all_containers()           | 1    1 | destroy()                |
244  | execute_on_container()            <>-------| info()                   |
245  | execute_on_all_containers()       |        | execute(command)         |
246  | install_vpp_in_all_containers()   |        | system_info()            |
247  | configure_vpp_in_all_containers() |        | install_supervisor()     |
248  | stop_all_containers()             |        | install_vpp()            |
249  | destroy_all_containers()          |        | restart_vpp()            |
250  +-----------------------------------+        | create_vpp_exec_config() |
251                                               | create_vpp_startup_config|
252                                               | is_container_running()   |
253                                               | is_container_present()   |
254                                               | _configure_cgroup()      |
255                                               +-------------^------------+
256                                                             |
257                                                             |
258                                                             |
259                                                  +----------+---------+
260                                                  |                    |
261                                           +------+-------+     +------+-------+
262                                           |     LXC      |     |    Docker    |
263                                           +--------------+     +--------------+
264                                           | (inherinted) |     | (inherinted) |
265                                           +------+-------+     +------+-------+
266                                                   |                   |
267                                                   +---------+---------+
268                                                             |
269                                                             | constructs
270                                                             |
271                                                   +---------v---------+
272                                                   |     Container     |
273                                                   +-------------------+
274                                                   | __getattr__(a)    |
275                                                   | __setattr__(a, v) |
276                                                   +-------------------+
277
278 Sequentional diagram that illustrates the creation of a single container.
279
280 ::
281
282  Legend:
283     e  = engine [Docker|LXC]
284     .. = kwargs (variable number of keyword argument)
285
286  +-------+                  +------------------+       +-----------------+
287  | RF KW |                  | ContainerManager |       | ContainerEngine |
288  +---+---+                  +--------+---------+       +--------+--------+
289      |                               |                          |
290      |  1: new ContainerManager(e)   |                          |
291     +-+---------------------------->+-+                         |
292     |-|                             |-| 2: new ContainerEngine  |
293     |-|                             |-+----------------------->+-+
294     |-|                             |-|                        |-|
295     |-|                             +-+                        +-+
296     |-|                              |                          |
297     |-| 3: construct_container(..)   |                          |
298     |-+---------------------------->+-+                         |
299     |-|                             |-| 4: init()               |
300     |-|                             |-+----------------------->+-+
301     |-|                             |-|                        |-| 5: new  +-------------+
302     |-|                             |-|                        |-+-------->| Container A |
303     |-|                             |-|                        |-|         +-------------+
304     |-|                             |-|<-----------------------+-|
305     |-|                             +-+                        +-+
306     |-|                              |                          |
307     |-| 6: acquire_all_containers()  |                          |
308     |-+---------------------------->+-+                         |
309     |-|                             |-| 7: acquire()            |
310     |-|                             |-+----------------------->+-+
311     |-|                             |-|                        |-|
312     |-|                             |-|                        |-+--+
313     |-|                             |-|                        |-|  | 8: is_container_present()
314     |-|                             |-|             True/False |-|<-+
315     |-|                             |-|                        |-|
316     |-|                             |-|                        |-|
317  +---------------------------------------------------------------------------------------------+
318  |  |-| ALT [isRunning & force]     |-|                        |-|--+                          |
319  |  |-|                             |-|                        |-|  | 8a: destroy()            |
320  |  |-|                             |-|                        |-<--+                          |
321  +---------------------------------------------------------------------------------------------+
322     |-|                             |-|                        |-|
323     |-|                             +-+                        +-+
324     |-|                              |                          |
325     |-| 9: create_all_containers()   |                          |
326     |-+---------------------------->+-+                         |
327     |-|                             |-| 10: create()            |
328     |-|                             |-+----------------------->+-+
329     |-|                             |-|                        |-+--+
330     |-|                             |-|                        |-|  | 11: wait('RUNNING')
331     |-|                             |-|                        |-<--+
332     |-|                             +-+                        +-+
333     |-|                              |                          |
334  +---------------------------------------------------------------------------------------------+
335  |  |-| ALT                          |                          |                              |
336  |  |-| (install_vpp, configure_vpp) |                          |                              |
337  |  |-|                              |                          |                              |
338  +---------------------------------------------------------------------------------------------+
339     |-|                              |                          |
340     |-| 12: destroy_all_containers() |                          |
341     |-+---------------------------->+-+                         |
342     |-|                             |-| 13: destroy()           |
343     |-|                             |-+----------------------->+-+
344     |-|                             |-|                        |-|
345     |-|                             +-+                        +-+
346     |-|                              |                          |
347     +++                              |                          |
348      |                               |                          |
349      +                               +                          +
350
351 Container Data Structure
352 ~~~~~~~~~~~~~~~~~~~~~~~~
353
354 Container is represented in Python L1 library as a separate Class with instance
355 variables and no methods except overriden ``__getattr__`` and ``__setattr__``.
356 Instance variables are assigned to container dynamically during the
357 ``construct_container(**kwargs)`` call and are passed down from the RF keyword.
358
359 Usage example:
360
361 .. code-block:: robotframework
362
363   | Construct VNF containers on all DUTs
364   | | [Arguments] | ${technology} | ${image} | ${cpu_count}=${1} | ${count}=${1}
365   | | ...
366   | | ${group}= | Set Variable | VNF
367   | | ${guest_dir}= | Set Variable | /mnt/host
368   | | ${host_dir}= | Set Variable | /tmp
369   | | ${skip_cpus}= | Evaluate | ${vpp_cpus}+${system_cpus}
370   | | Import Library | resources.libraries.python.ContainerUtils.ContainerManager
371   | | ... | engine=${technology} | WITH NAME | ${group}
372   | | ${duts}= | Get Matches | ${nodes} | DUT*
373   | | :FOR | ${dut} | IN | @{duts}
374   | | | {env}= | Create List | LC_ALL="en_US.UTF-8"
375   | | | ... | DEBIAN_FRONTEND=noninteractive | ETCDV3_ENDPOINTS=172.17.0.1:2379
376   | | | ${cpu_node}= | Get interfaces numa node | ${nodes['${dut}']}
377   | | | ... | ${dut1_if1} | ${dut1_if2}
378   | | | Run Keyword | ${group}.Construct containers
379   | | | ... | name=${dut}_${group}
380   | | | ... | node=${nodes['${dut}']}
381   | | | ... | host_dir=${host_dir}
382   | | | ... | guest_dir=${guest_dir}
383   | | | ... | image=${image}
384   | | | ... | cpu_count=${cpu_count}
385   | | | ... | cpu_skip=${skip_cpus}
386   | | | ... | smt_used=${False}
387   | | | ... | cpuset_mems=${cpu_node}
388   | | | ... | cpu_shared=${False}
389   | | | ... | env=${env}
390
391 Mandatory parameters to create standalone container are: ``node``, ``name``,
392 ``image`` [image-var]_, ``cpu_count``, ``cpu_skip``, ``smt_used``,
393 ``cpuset_mems``, ``cpu_shared``.
394
395 There is no parameters check functionality. Passing required arguments is in
396 coder responsibility. All the above parameters are required to calculate the
397 correct cpu placement. See documentation for the full reference.
398
399 Kubernetes
400 ~~~~~~~~~~
401
402 Kubernetes is implemented as separate library ``KubernetesUtils.py``,
403 with a class with the same name. This utility provides an API for L2
404 Robot Keywords to control ``kubectl`` installed on each of DUTs. One
405 time initialization script, ``resources/libraries/bash/k8s_setup.sh``
406 does reset/init kubectl, applies Calico v2.6.3 and initializes the
407 ``csit`` namespace. CSIT namespace is required to not to interfere with
408 existing setups and it further simplifies apply/get/delete
409 Pod/ConfigMap operations on SUTs.
410
411 Kubernetes utility is based on YAML templates to avoid crafting the huge
412 YAML configuration files, what would lower the readability of code and
413 requires complicated algorithms. The templates can be found in
414 ``resources/templates/kubernetes`` and can be leveraged in the future
415 for other separate tasks.
416
417 Two types of YAML templates are defined:
418
419 - Static - do not change between deployments, that is infrastructure
420   containers like Kafka, Calico, ETCD.
421
422 - Dynamic - per test suite/case topology YAML files e.g. SFC_controller,
423   VNF, VSWITCH.
424
425 Making own python wrapper library of ``kubectl`` instead of using the
426 official Python package allows to control and deploy environment over
427 the SSH library without the need of using isolated driver running on
428 each of DUTs.
429
430 Ligato
431 ~~~~~~
432
433 Ligato integration does require to compile the ``vpp-agent`` tool and build the
434 bundled Docker image. Compilation of ``vpp-agent`` depends on specific VPP. In
435 ``ligato/vpp-agent`` repository there are well prepared scripts for building the
436 Docker image. Building docker image is possible via series of commands:
437
438 ::
439
440   git clone https://github.com/ligato/vpp-agent
441   cd vpp_agent/docker/dev_vpp_agent
442   sudo docker build -t dev_vpp_agent --build-arg AGENT_COMMIT=<agent commit id>\
443       --build-arg VPP_COMMIT=<vpp commit id> --no-cache .
444   sudo ./shrink.sh
445   cd ../prod_vpp_agent
446   sudo ./build.sh
447   sudo ./shrink.sh
448
449 CSIT requires Docker image to include the desired VPP version (per patch
450 testing, nightly testing, on demand testing).
451
452 The entire build process of building ``dev_vpp_agent`` image heavily depends
453 on internet connectivity and also takes a significant amount of time (~1-1.5h
454 based on internet bandwidth and allocated resources). The optimal solution would
455 be to build the image on jenkins slave, transfer the Docker image to DUTs and
456 execute separate suite of tests.
457
458 To adress the amount of time required to build ``dev_vpp_agent`` image, we can
459 pull existing specific version of ```dev_vpp_agent``` and exctract the
460 ```vpp-agent``` from it.
461
462 We created separate sets of Jenkins jobs, that will be executing following:
463
464 1. Clone latest CSIT and Ligato repositaries.
465 2. Pull specific version of ``dev_vpp_agent`` image from Dockerhub.
466 3. Extract VPP API (from ``.deb`` package) and copy into ``dev_vpp_agent``
467    image
468 4. Rebuild vpp-agent and extract outside image.
469 5. Build ``prod_vpp_image`` Docker image from ``dev_vpp_agent`` image.
470 6. Transfer ``prod_vpp_agent`` image to DUTs.
471 7. Execute subset of performance tests designed for Ligato testing.
472
473 ::
474
475  +-----------------------------------------------+
476  |                  ubuntu:16.04                 <-----| Base image on Dockerhub
477  +------------------------^----------------------+
478                           |
479                           |
480  +------------------------+----------------------+
481  |               ligato/dev_vpp_agent            <------| Pull this image from
482  +------------------------^----------------------+      | Dockerhub ligato/dev_vpp_agent:<version>
483                           |
484                           | Rebuild and extract agent.tar.gz from dev_vpp_agent
485  +------------------------+----------------------+
486  |                 prod_vpp_agent                <------| Build by passing own
487  +-----------------------------------------------+      | vpp.tar.gz (from nexus
488                                                         | or built by JJB) and
489                                                         | agent.tar.gz extracted
490                                                         | from ligato/dev_vpp_agent
491
492
493 Approximate size of vnf-agent docker images:
494
495 ::
496
497   REPOSITORY            TAG       IMAGE ID        CREATED        SIZE
498   dev-vpp-agent         latest    78c53bd57e2     6 weeks ago    9.79GB
499   prod_vpp_agent        latest    f68af5afe601    5 weeks ago    443MB
500
501 In CSIT we need to create separate performance suite under
502 ``tests/kubernetes/perf`` which contains modified Suite setup in comparison
503 to standard perf tests. This is due to reason that VPP will act as vswitch in
504 Docker image and not as standalone installed service.
505
506 Tested Topologies
507 ~~~~~~~~~~~~~~~~~
508
509 Listed CSIT container networking test topologies are defined with DUT
510 containerized VPP switch forwarding packets between NF containers. Each
511 NF container runs their own instance of VPP in L2XC configuration.
512
513 Following container networking topologies are tested in CSIT |release|:
514
515 - LXC topologies:
516
517   - eth-l2xcbase-eth-2memif-1lxc.
518   - eth-l2bdbasemaclrn-eth-2memif-1lxc.
519
520 - Docker topologies:
521
522   - eth-l2xcbase-eth-2memif-1docker.
523
524 - Kubernetes/Ligato topologies:
525
526   - eth-1drcl2xcbase-eth-2memif-1drcl2xc.
527   - eth-1drcl2xcbase-eth-4memif-2drcl2xc.
528   - eth-1drcl2bdbasemaclrn-eth-2memif-1drcl2xc.
529   - eth-1drcl2bdbasemaclrn-eth-4memif-2drcl2xc.
530
531
532 References
533 ----------
534
535 .. [lxc] `Linux Containers <https://linuxcontainers.org/>`_
536 .. [lxc-namespace] `Resource management: Linux kernel Namespaces and cgroups <https://www.cs.ucsb.edu/~rich/class/cs293b-cloud/papers/lxc-namespace.pdf>`_.
537 .. [stgraber] `LXC 1.0: Blog post series <https://stgraber.org/2013/12/20/lxc-1-0-blog-post-series/>`_.
538 .. [lxc-security] `Linux Containers Security <https://linuxcontainers.org/lxc/security/>`_.
539 .. [capabilities] `Linux manual - capabilities - overview of Linux capabilities http://man7.org/linux/man-pages/man7/capabilities.7.html`_.
540 .. [cgroup1] `Linux kernel documentation: cgroups <https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt>`_.
541 .. [cgroup2] `Linux kernel documentation: Control Group v2 <https://www.kernel.org/doc/Documentation/cgroup-v2.txt>`_.
542 .. [selinux] `SELinux Project Wiki <http://selinuxproject.org/page/Main_Page>`_.
543 .. [lxc-sec-features] `LXC 1.0: Security features <https://stgraber.org/2014/01/01/lxc-1-0-security-features/>`_.
544 .. [lxc-source] `Linux Containers source <https://github.com/lxc/lxc>`_.
545 .. [apparmor] `Ubuntu AppArmor <https://wiki.ubuntu.com/AppArmor>`_.
546 .. [seccomp] `SECure COMPuting with filters <https://www.kernel.org/doc/Documentation/prctl/seccomp_filter.txt>`_.
547 .. [docker] `Docker <https://www.docker.com/what-docker>`_.
548 .. [k8s-doc] `Kubernetes documentation <https://kubernetes.io/docs/home/>`_.
549 .. [ligato] `Ligato <https://github.com/ligato>`_.
550 .. [govpp] `FD.io goVPP project <https://wiki.fd.io/view/GoVPP>`_.
551 .. [vpp-agent] `Ligato vpp-agent <https://github.com/ligato/vpp-agent>`_.
552 .. [image-var] Image parameter is required in initial commit version. There is plan to implement container build class to build Docker/LXC image.

©2016 FD.io a Linux Foundation Collaborative Project. All Rights Reserved.
Linux Foundation is a registered trademark of The Linux Foundation. Linux is a registered trademark of Linus Torvalds.
Please see our privacy policy and terms of use.