github.com/inspektor-gadget/inspektor-gadget@v0.28.1/docs/core-concepts/architecture.md (about) 1 --- 2 title: Architecture 3 weight: 20 4 description: > 5 Understand how everything comes together. 6 --- 7 8 Inspektor Gadget comes with several tools which permit monitoring different 9 events related to specific kernel subsystems. 10 11 It is usually deployed by the `kubectl gadget` plugin. It interacts with the 12 kube-api server to create all the resources needed for Inspektor Gadget to work. 13 Another way of deploying Inspektor Gadget is to directly apply the manifests 14 using `kubectl`. 15 As a result, Inspektor Gadget is deployed on each node of the cluster as a 16 `DaemonSet`. 17 18  19 20 Inspektor Gadget provides a trace Custom Resource Definition (CRD) that is used 21 to control it. The user interacts with the `kubectl gadget` CLI to create 22 tracers in the cluster, this CLI uses the kubeapi-server to create the 23 corresponding trace CRs on each node. Then, the gadget pod implements a 24 Kubernetes controller that performs the actions indicated in the CR. 25 26  27 28 This trace CRD is, in turn, used to create tracers which are in charge of 29 installing eBPF program in the kernel. 30 31 The Linux kernel has an inbuilt virtual machine for eBPF bytecode, allowing 32 userspace to run small scripts in kernel space with limited impact. 33 The eBPF programs are supplied by userspace in a binary format. The kernel 34 then verifies the program through static analysis, so that no memory corruption 35 can happen and no out of bounds access can leak sensitive data. 36 In eBPF no loops are allowed and the maximum number of instructions is limited, 37 so that a eBPF program with logical bugs can not hang up the kernel. 38 Read more on eBPF [here](https://lwn.net/Articles/740157/) and [here](https://www.brendangregg.com/ebpf.html). 39 40 To trace pods, Inspektor Gadget attaches eBPF programs to kernel functions and 41 the kernel will run them always when the functions are executed. Therefore, the 42 eBPF programs need to detect if the syscall that triggered the function comes 43 from a pod that Inspektor Gadget should trace. To do that the program looks up 44 the current `mount` namespace id in a eBPF map containing the list of pods to 45 trace, if it's not found the program exits early. 46 Finally, the eBPF program gathers the information to trace, e.g., syscall 47 parameters, and writes them to a ring buffer or eBPF map. 48 49  50 51 The events gathered by the eBPF program are written to specific kernel buffers. 52 The userspace part of Inspektor Gadget reads this events from the buffer and 53 publishes them to a stream. 54 This stream is displayed on the developer laptop using, internally the 55 `kubectl exec` API. 56 57  58 59 60 The `Gadget Tracer Manager` keeps a list of running gadgets and containers. 61 Each running gadget has an associated eBPF map that is filled with the `mount` 62 namespace identifiers of the containers to be traced according to the namespace, 63 labels, pod name, etc. parameters passed to the gadget. 64 The `Gadget Tracer Manager` knows about the current running containers thanks to 65 `runc-fanotify` which adds or removes container to the `Gadget Tracer Manager` 66 collection. 67 68  69 70 Sometimes it is useful to run a eBPF program always in the background. It can trace 71 everything and save it into different ringbuffers per pod. 72 The userspace utility can then accesses a ring buffer retrospectively only if needed 73 for introspection or errors. This is currently done for [traceloop](https://github.com/kinvolk/traceloop) (not present in bcc), 74 which uses an [overwriteable ring buffer](https://lwn.net/Articles/694140/) to only log a small amount of recent events. 75 It uses a service per each node which provides a Unix Domain Socket accepting HTTP 76 requests to list the available traces and to dump them (this stops tracing even if the 77 pod did not already crash). 78 79  80 81 ## `ig` 82 83 The job of the [`ig`](../ig.md) can be divided into four main 84 tasks, each of them is managed by the following packages: 85 - [Tracers](https://pkg.go.dev/github.com/inspektor-gadget/inspektor-gadget@v0.22.0/pkg/gadgets): They are in charge of collecting events from the 86 host, like process creation, file access, etc. 87 - [Container-Collection](https://pkg.go.dev/github.com/inspektor-gadget/inspektor-gadget@v0.22.0/pkg/container-collection): It enriches the events 88 with the container information (e.g. Kubernetes metadata). To do it, it traces 89 the creation and removal of containers in the host. 90 - [Trace-Collection](https://pkg.go.dev/github.com/inspektor-gadget/inspektor-gadget@v0.22.0/pkg/tracer-collection): This package is used to filter 91 events by containers, using the information provided by the 92 Container-Collection package. 93 - [Columns](https://pkg.go.dev/github.com/inspektor-gadget/inspektor-gadget@v0.22.0/pkg/columns): It creates a columns representation of the events 94 generated by the tracers. 95 96 <p align="center"> 97 <img src="images/architecture/ig.svg"> 98 </p> 99 100 We wrote a 101 [blogpost](https://www.inspektor-gadget.io/blog/2022/09/using-inspektor-gadget-from-golang-applications/) 102 describing each of this modules, it also provides some examples to test them 103 together and separately. 104 105 ## Previous talks 106 107 - Introducing Flatcar Container Linux Edge, [Cloud Native Computing Meetup Berlin](https://www.meetup.com/Cloud-Native-Computing-Berlin/events/260143677/) ([slides](https://docs.google.com/presentation/d/1YF7R2b9HHYrcdpz2BuBznpISuVVZsXZEwD8a6SJoDwQ/edit))