docs: split Tracing Policy concept page into subpages

docs/assets/scss/page-info.scss

@@ -6,7 +6,7 @@
   margin: 2rem 0;
   padding: 20px 16px;
   padding-bottom: 20px;
-  border: none !important;
+  border: thin dashed lightgray;
 
   p {
     margin: 12px 0;

docs/content/en/docs/concepts/k8s-filtering.md

@@ -11,7 +11,7 @@ This is currently a beta feature.
 
 ## Motivation
 
-Tetragon is configured via [TracingPolicies]({{< ref "docs/concepts/tracing-policy" >}}). Broadly
+Tetragon is configured via [TracingPolicies]({{< ref "/docs/concepts/tracing-policy" >}}). Broadly
 speaking, TracingPolicies define _what_ situations Tetragon should react to and _how_. The _what_
 can be, for example, specific system calls with specific argument values. The _how_ defines what
 action the Tetragon agent should perform when the specified situation occurs. The most common action

docs/content/en/docs/concepts/tracing-policy/_index.md

@@ -0,0 +1,35 @@
+---
+title: "Tracing Policy"
+icon: "overview"
+weight: 3
+description: "Documentation for the TracingPolicy custom resource"
+---
+
+Tetragon's `TracingPolicy` is a user-configurable Kubernetes custom resource (CR) that
+allows users to trace arbitrary events in the kernel and optionally define
+actions to take on a match. Policies consist of a hook point (kprobes,
+tracepoints, and uprobes are supported), and selectors for in-kernel filtering
+and specifying actions. For more details, see
+[hook points page]({{< ref "/docs/concepts/tracing-policy/hooks" >}}) and the
+[selectors page]({{< ref "/docs/concepts/tracing-policy/selectors" >}}).
+
+{{< caution >}}
+`TracingPolicy` allows for powerful, yet low-level configuration and, as such,
+requires knowledge about the Linux kernel and containers to avoid unexpected
+issues such as TOCTU bugs.
+{{< /caution >}}
+
+For the complete custom resource definition (CRD) refer to the YAML file
+[`cilium.io_tracingpolicies.yaml`](https://github.com/cilium/tetragon/blob/main/pkg/k8s/apis/cilium.io/client/crds/v1alpha1/cilium.io_tracingpolicies.yaml).
+One practical way to explore the CRD is to use `kubectl explain` against a
+Kubernetes API server on which it is installed, for example `kubectl explain
+tracingpolicy.spec.kprobes` provides field-specific documentation and details
+on kprobe spec.
+
+Tracing Policies can be loaded and unloaded at runtime in Tetragon, or on
+startup using flags.
+- With Kubernetes, you can use `kubectl` to add and remove a `TracingPolicy`.
+- You can use `tetra` gRPC CLI to add and remove a `TracingPolicy`.
+- You can use the `--tracing-policy` and `--tracing-policy-dir` flags, see more
+  in the [daemon configuration page]({{< ref "/docs/reference/tetragon-configuration#configure-tracing-policies-location" >}}).
+

docs/content/en/docs/concepts/tracing-policy/example.md

@@ -0,0 +1,153 @@
+---
+title: "Example"
+icon: "tutorials"
+weight: 1
+description: "Learn the basics of Tracing Policy via an example"
+---
+
+
+To discover `TracingPolicy`, let's understand via an example that will be
+explained, part by part, in this document:
+
+{{< warning >}}
+This policy is for illustration purposes only and should not be used to
+restrict access to certain files. It can be easily bypassed by, for example,
+using hard links.
+{{< /warning >}}
+
+```yaml
+apiVersion: cilium.io/v1alpha1
+kind: TracingPolicy
+metadata:
+  name: "fd-install"
+spec:
+  kprobes:
+  - call: "fd_install"
+    syscall: false
+    args:
+    - index: 0
+      type: "int"
+    - index: 1
+      type: "file"
+    selectors:
+    - matchArgs:
+      - index: 1
+        operator: "Equal"
+        values:
+        - "/tmp/tetragon"
+      matchActions:
+      - action: Sigkill
+```
+
+## Required fields
+
+```yaml
+apiVersion: cilium.io/v1alpha1
+kind: TracingPolicy
+metadata:
+  name: "fd-install"
+```
+
+The first part follows a common pattern among all Cilium Policies or more
+widely [Kubernetes object](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/).
+It first declares the Kubernetes API used, then the kind of Kubernetes object
+it is in this API and an arbitrary name for the object, that has to comply with
+[Kubernetes naming convention](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/).
+
+## Hook point
+
+```yaml
+spec:
+  kprobes:
+  - call: "fd_install"
+    syscall: false
+    args:
+    - index: 0
+      type: "int"
+    - index: 1
+      type: "file"
+```
+
+The beginning of the specification describe the hook point to use, here we are
+using a kprobe, hooking on the kernel function `fd_install`. That's the kernel
+function that gets called when a new file descriptor needs to be created. We
+indicate that it's not a syscall, but a regular kernel function. Then we
+specify the argument of the specified function symbol to be able to extract
+them, and optionally perform filtering on them.
+
+See the [hook points page]({{< ref "/docs/concepts/tracing-policy/hooks" >}})
+for further information on the various hook points available and arguments.
+
+## Selectors
+
+```yaml
+    selectors:
+    - matchArgs:
+      - index: 1
+        operator: "Equal"
+        values:
+        - "/tmp/tetragon"
+      matchActions:
+      - action: Sigkill
+```
+
+Selectors allow you to filter on the events to extract only a subset of the
+events based on different properties and optionally take an enforcement action.
+
+In the example, we filter on the argument at index 1, passing a `file` struct
+to the function. Tetragon has the knowledge on how to apply the `Equal`
+operator over a Linux kernel `file` struct and you can basically match on the
+path of the file.
+
+Then we add the `Sigkill` action, meaning, that any match of the selector
+should send a SIGKILL signal to the process that initiated the event.
+
+Learn more about the various selectors in the dedicated
+[selectors page]({{< ref "/docs/concepts/tracing-policy/selectors" >}}).
+
+## Policy effect
+
+First, let's create the `/tmp/tetragon` file with some content:
+```shell-session
+echo eBPF! > /tmp/tetragon
+```
+
+Starting Tetragon with the above `TracingPolicy`, for example putting the
+policy in the `example.yaml` file, compiling the project locally and starting
+Tetragon with (you can do similar things with container image releases, see the
+docker run command in the [Try Tetragon on Linux guide]({{< ref
+"/docs/getting-started/try-tetragon-linux#observability-with-tracingpolicy" >}}):
+```shell-session
+sudo ./tetragon --bpf-lib bpf/objs --tracing-policy example.yaml
+```
+
+{{< note >}}
+Stop tetragon with <kbd>Ctrl</kbd>+<kbd>C</kbd> to disable the policy and
+remove the BPF programs.
+{{< /note >}}
+
+Reading the `/tmp/tetragon` file with `cat`:
+```shell-session
+cat /tmp/tetragon
+```
+
+Should result in the following events:
+```
+🚀 process  /usr/bin/cat /tmp/tetragon
+📬 open     /usr/bin/cat /tmp/tetragon
+💥 exit     /usr/bin/cat /tmp/tetragon SIGKILL
+```
+
+And the shell will return:
+```
+Killed
+```
+
+## See more
+
+For more examples of tracing policies, take a look at the
+[examples/tracingpolicy](https://github.com/cilium/tetragon/tree/main/examples/tracingpolicy)
+folder in the Tetragon repository. Also read the following sections on
+[hook points]({{< ref "/docs/concepts/tracing-policy/hooks" >}}) and
+[selectors]({{< ref "/docs/concepts/tracing-policy/selectors" >}}).
+