add securityContext and /proc/1/root tips for ephemeral containers

content/chainguard/chainguard-images/troubleshooting/debugging-distroless-images.md

@@ -187,6 +187,60 @@ curl http://localhost:8001/api/v1/namespaces/default/pods/<pod-name>/ephemeralco
 - Replace `<pod-name>` and `<container-name>` with your actual values.
 - Be sure to match the `volumeMounts` spec to those in your target container.
 
+#### Pods enforcing runAsNonRoot
+
+If the pod enforces `runAsNonRoot: true`, the ephemeral container will fail to start with a `CreateContainerConfigError` because `wolfi-base` runs as root by default. In this case, add a `securityContext` to the patch that matches the target container’s policy:
+
+```
+curl http://localhost:8001/api/v1/namespaces/default/pods/<pod-name>/ephemeralcontainers \
+-X PATCH \
+-H ‘Content-Type: application/strategic-merge-patch+json’ \
+-d ‘
+{
+  "spec": {
+    "ephemeralContainers": [
+      {
+        "name": "debugger",
+        "command": ["sh"],
+        "image": "cgr.dev/chainguard/wolfi-base",
+        "targetContainerName": "<container-name>",
+        "stdin": true,
+        "tty": true,
+        "securityContext": {
+          "runAsUser": 1001,
+          "runAsNonRoot": true,
+          "allowPrivilegeEscalation": false,
+          "capabilities": {
+            "drop": ["ALL"]
+          }
+        },
+        "volumeMounts": [
+          {
+            "mountPath": "/var/log",
+            "name": "varlog",
+            "readOnly": true
+          }
+        ]
+      }
+    ]
+  }
+}’
+```
+
+Set `runAsUser` to match the UID of the target container’s process. You can find this in the Pod spec’s `securityContext.runAsUser`, or by running `ps aux` in the ephemeral container before the `securityContext` constraint takes effect.
+
+#### Accessing the target container’s filesystem without volumeMounts
+
+As an alternative to replicating `volumeMounts`, you can access the target container’s filesystem directly via `/proc/1/root/<path>` in the ephemeral container. Because `targetContainerName` puts the ephemeral container in the same PID namespace as the target, PID 1 is the target container’s main process, and `/proc/1/root/` traverses its full mount namespace — including Kubernetes-backed volumes such as `emptyDir`, `configMap`, `secret`, and persistent volume claims.
+
+For example, to read a log file from the target container:
+
+```shell
+cat /proc/1/root/var/log/app/app.log
+```
+
+This requires the ephemeral container to run as the same UID as the target process, which is why the `securityContext` fix above is a prerequisite. If security policies in your environment block `/proc/<pid>/root` access (for example, strict seccomp or AppArmor profiles), use the explicit `volumeMounts` approach instead.
+
 Attach to the debug container:
 ```
 kubectl attach <pod-name> -c debugger -ti