contrib: add example for enabling per-container RDT monitoring

contrib/kustomize/samples/rdt-monitoring/README.md

@@ -0,0 +1,63 @@
+# Per-container RDT monitoring with NRI hook-injector
+
+This example demonstrates how to enable per-container RDT monitoring using OCI
+hooks. It works as a bridge-gap solution until native support
+(`linux.intelRdt.enableMonitoring` of OCI runtime-spec) is available.
+
+References:
+
+- https://github.com/opencontainers/runtime-spec/blob/main/config-linux.md#intelrdt
+- https://github.com/opencontainers/runc/pull/4832
+- https://github.com/containerd/nri/pull/215
+
+## Design
+
+The sample leverages the [hook-injector](../../../../plugins/hook-injector)
+sample plugin to inject OCI hooks that manage the per-container monitoring
+groups. It deploys a DaemonSet and consists of the following parts:
+
+1. A custom location on the host (/etc/containers/nri/rdt-hook) is used to
+   store the OCI hook binary and configuration.
+2. An init container creates the OCI hook binary on the host.
+3. A second init container creates the OCI hook configuration on the host.
+4. The hook-injector NRI plugin is run in the main container. The hook injector
+   is configured to only watch for OCI hooks in the custom location.
+5. The hook is injected into all containers created after this.
+
+> [!NOTE] The setup enables RDT monitoring for all new containers on the node.
+> The hook is injected into every container and the hook binary does not
+> provide any means to skip creation of the per-container monitoring group. In
+> most scenarios this shouldn't be a problem as the number of available
+> monitoring groups is high (in the order of hundreds).
+
+## Deployment
+
+Deploy the sample kustomize overlay:
+
+```bash
+kubectl apply -k https://github.com/containerd/nri/contrib/kustomize/samples/rdt-monitoring
+```
+
+The functionality can be verified by creating a new pod and checking the
+`/sys/fs/resctrl/<container-id>` directory on the node where the pod is
+deployed. An example:
+
+```bash
+$ kubectl run --image registry.k8s.io/pause rdt-test
+
+$ kubectl get pod rdt-test -o go-template='{{.spec.nodeName}}{{"\n"}}{{(index .status.containerStatuses 0).containerID}}{{"\n"}}'
+node-1
+containerd://477ba96b86e0f7756790d5c52ffa94feab0028f0785a23d143fd9390f09e35f6
+```
+
+Then check the node:
+
+```bash
+$ ssh node-1
+
+$ cat /sys/fs/resctrl/mon_groups/477ba96b86e0f7756790d5c52ffa94feab0028f0785a23d143fd9390f09e35f6/tasks
+1817117
+1817149
+1817150
+1817151
+```

contrib/kustomize/samples/rdt-monitoring/initcontainers-patch.yaml

@@ -0,0 +1,119 @@
+apiVersion: apps/v1
+kind: DaemonSet
+metadata:
+  name: nri-plugin-hook-injector
+spec:
+  template:
+    spec:
+      initContainers:
+      - name: deploy-hook-binary
+        image: busybox:latest
+        command:
+          - sh
+          - -c
+          - |
+            echo "Creating OCI hook binary"
+            cat > "$HOOKS_DIR/hook.sh" <<'EOF'
+            #!/bin/sh
+            fatal() {
+                echo $@ >&2
+                exit 1
+            }
+
+            state=$(</dev/stdin)
+
+            resctrl_root_path="$(awk '$3 == "resctrl" {print $2; exit}' /proc/mounts)"
+            if [ "$resctrl_root_path" = "" ]; then
+                echo "resctrl mount point not found"
+                exit 0
+            fi
+
+            id=$(echo $state | jq -er .id) || fatal "failed to get container id"
+            bundle=$(echo $state | jq -er .bundle) || fatal "failed to get container bundle path"
+
+            clos=""
+            intel_rdt_config=$(jq -r .linux.intelRdt "$bundle/config.json")
+            if [ "$intel_rdt_config" != "null" ]; then
+                # If linux.intelRdt is non-null the container is assigned to a clos by the runtime
+                clos=$(echo "$intel_rdt_config" | jq -er .closID) || clos="$id"
+            fi
+
+            mon_group_path="$resctrl_root_path/$clos/mon_groups/$id"
+
+            create() {
+                pid=$(echo $state | jq -er .pid) || fatal "failed to get container pid"
+
+                echo "creating monintoring group $mon_group_path"
+                mkdir "$mon_group_path" || fatal "failed to create monitoring group for container $id"
+                echo writing $pid to $mon_group_path/tasks
+
+                if ! echo $pid > "$mon_group_path/tasks"; then
+                    rmdir "$mon_group_path" || echo "failed to remove $mon_group_path" >&2
+                    fatal "failed to assign pid $pid to $mon_group_path"
+                fi
+            }
+
+            delete() {
+                # MON group is reaped as part of the CLOS (by the runtime) if it was under
+                # a dedicated CLOS created for this container
+                if [ "$clos" != "$id" ]; then
+                    echo "deleting monintoring group $mon_group_path"
+                    rmdir "$mon_group_path" || fatal "failed to delete monitoring group of container $id"
+                fi
+            }
+
+            case "$1" in
+                create)
+                    create
+                    ;;
+                delete)
+                    delete
+                    ;;
+                auto)
+                    status=$(echo $state | jq -er .status) || fatal "failed to get container status"
+                    case "$status" in
+                        creating)
+                            create
+                            ;;
+                        stopped)
+                            delete
+                            ;;
+                    esac
+                    ;;
+                *) fatal "unknown operation '$1'"
+            esac
+            EOF
+            chmod +x "$HOOKS_DIR/hook.sh"
+        env:
+        - name: HOOKS_DIR
+          value: /hooks
+        volumeMounts:
+        - name: etc-hooks-d
+          mountPath: /hooks
+
+      - name: deploy-hook-config
+        image: busybox:latest
+        command:
+          - sh
+          - -c
+          - |
+            echo "Creating OCI hook config"
+            cat > "$HOOKS_DIR/hook.json" <<'EOF'
+            {
+              "version": "1.0.0",
+              "hook": {
+                  "path": "/etc/containers/nri/rdt-hook/hook.sh",
+                  "args": ["", "auto"]
+              },
+              "when": {
+                  "always": true
+              },
+              "stages": ["createRuntime", "poststop"]
+            }
+            EOF
+        env:
+        - name: HOOKS_DIR
+          value: /hooks
+        volumeMounts:
+        - name: etc-hooks-d
+          mountPath: /hooks

contrib/kustomize/samples/rdt-monitoring/kustomization.yaml

@@ -0,0 +1,7 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - ../../hook-injector/unstable
+patches:
+  - path: initcontainers-patch.yaml
+  - path: volumes-patch.yaml

contrib/kustomize/samples/rdt-monitoring/volumes-patch.yaml

@@ -0,0 +1,27 @@
+apiVersion: apps/v1
+kind: DaemonSet
+metadata:
+  name: nri-plugin-hook-injector
+spec:
+  template:
+    spec:
+      containers:
+        - name: plugin
+          volumeMounts:
+            - name: etc-hooks-d
+              mountPath: /etc/containers/nri/rdt-hook
+            # Remove unwanted mounts
+            - $patch: delete
+              mountPath: /usr/share/containers/oci/hooks.d
+            - $patch: delete
+              mountPath: /usr/libexec/oci/hooks.d
+      volumes:
+        # Replace the default hooks directory with a custom one
+        - name: etc-hooks-d
+          hostPath:
+            path: /etc/containers/nri/rdt-hook
+            type: DirectoryOrCreate
+        - $patch: delete
+          name: usr-share-hooks-d
+        - $patch: delete
+          name: libexec-hooks-d