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 <[email protected]>

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 >}}
@@ -44,6 +44,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
@@ -258,3 +262,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)
+Killed
+```