doc: document how to use the container selector

This change describes how to use the container selector in tracing
policies. Also, this change renames the "K8s namespace and pod label
filtering" page to "K8s Policy Filtering" to make the name more generic.

Fixes: #1879

Signed-off-by: Oleh Neichev <oleg.neichev@gmail.com>

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

@@ -1,7 +1,7 @@
 ---
-title: "K8s namespace and pod label filtering"
+title: "K8s Policy Filtering"
 weight: 4
-description: "Tetragon in-kernel filtering based on Kubernetes namespaces and pod label filters"
+description: "Tetragon in-kernel filtering based on Kubernetes namespaces, pod labels, and container fields"
 ---
 
 {{< caution >}}
@@ -17,10 +17,15 @@ action the Tetragon agent should perform when the specified situation occurs. Th
 is generating an event, but there are others (e.g., returning an error without executing the function,
 or killing the corresponding process).
 
-Here we discuss how to  apply tracing policies only on a subset of pods running on the system via
-two mechanisms: namespaced policies, and pod-label filters. Tetragon implements both mechanisms
-in-kernel via eBPF. This is important for both observability and enforcement use-cases. For
-observability, copying only the relevant events from kernel- to user-space reduces overhead. For
+Here we discuss how to apply tracing policies only on a subset of pods running on the system via
+the followings mechanisms:
+- namespaced policies
+- pod-label filters
+- container field filters
+
+Tetragon implements these mechanisms in-kernel via eBPF. This is important for both observability
+and enforcement use-cases.
+For observability, copying only the relevant events from kernel- to user-space reduces overhead. For
 enforcement, performing the enforcement action in the kernel avoids the race-condition of doing it
 in user-space. For example, let us consider the case where we want to block an application from
 performing a system call. Performing the filtering in-kernel means that the application will never
@@ -44,6 +49,10 @@ namespace.
 For pod label filters, we use the `PodSelector` field of tracing policies to select the pods that
 the policy is applied to.
 
+## Container field filters
+
+For container field filters, we use the `containerSelector` field of tracing policies to select the containers that the policy is applied to. At the moment, the only supported field is `name`.
+
 ## Demo
 
 ### Setup
@@ -257,3 +266,82 @@ If you don't see a command prompt, try pressing enter.
 pod "test" deleted
 pod default/test terminated (Error)
 ```
+
+### Container field filters
+
+Let's install a tracing policy with a container field filter.
+
+```shell
+cat << EOF | kubectl apply -f -
+apiVersion: cilium.io/v1alpha1
+kind: TracingPolicy
+metadata:
+  name: "lseek-podfilter"
+spec:
+  containerSelector:
+    matchExpressions:
+      - key: name
+        operator: In
+        values:
+        - main
+  kprobes:
+  - call: "sys_lseek"
+    syscall: true
+    args:
+    - index: 0
+      type: "int"
+    selectors:
+    - matchArgs:
+      - index: 0
+        operator: "Equal"
+        values:
+        - "-1"
+      matchActions:
+      - action: Sigkill
+EOF
+```
+
+Let's create a pod with 2 containers:
+
+```shell
+cat << EOF | kubectl apply -f -
+apiVersion: v1
+kind: Pod
+metadata:
+  name: lseek-pod
+spec:
+  containers:
+  - name: main
+    image: python
+    command: ['sh', '-c', 'sleep infinity']
+  - name: sidecar
+    image: python
+    command: ['sh', '-c', 'sleep infinity']
+EOF
+```
+
+Containers that don't match the name `main` will not be affected:
+
+```shell
+kubectl exec -it lseek-pod -c sidecar -- python3
+```
+
+```
+>>> import os
+>>> os.lseek(-1, 0, 0)
+Traceback (most recent call last):
+  File "<stdin>", line 1, in <module>
+  OSError: [Errno 9] Bad file descriptor
+>>>
+```
+
+But containers matching the name `main` will:
+```shell
+kubectl exec -it lseek-pod -c main -- python3
+```
+
+```
+>>> import os
+>>> os.lseek(-1, 0, 0)
+command terminated with exit code 137
+```