Merge pull request #91362 from DCChadwick/osdocs10269

OSDOCS-10269: Updating dev/fuse instructions

Author: mburke5678

modules/nodes-containers-dev-fuse-configuring.adoc

@@ -4,63 +4,134 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="nodes-containers-dev-fuse-configuring_{context}"]
-= Configuring /dev/fuse on unprivileged pods
+= Configuring /dev/fuse for unprivileged builds in pods
 
-As an alternative to the virtual filesystem, you can configure the `/dev/fuse` device to the `io.kubernetes.cri-o.Devices` annotation to access faster builds within unprivileged pods. Using `/dev/fuse` is secure, efficient, and scalable, and allows unprivileged users to mount an overlay filesystem as if the unprivileged pod was privileged. 
+By exposing the `/dev/fuse` device to an unprivileged pod, you grant it the capability to perform Filesystem in Userspace (FUSE) mounts. This is achieved by adding the `io.kubernetes.cri-o.Devices: "/dev/fuse"` annotation to your pod definition. This setup allows an unprivileged user within the pod to use tools like `podman` with storage drivers such as `fuse-overlayfs` by mimicking privileged build capabilities in a secure and efficient manner without granting full privileged access to the pod.
 
 .Procedure
 
-. Create the pod.
+. Define the pod with `/dev/fuse` access:
 +
-[source,terminal]
+* Create a YAML file named `fuse-builder-pod.yaml` with the following content: 
++
+[source,yaml]
 ----
-$ oc exec -ti no-priv -- /bin/bash
+apiVersion: v1
+kind: Pod
+metadata:
+  name: fuse-builder-pod
+  annotations:
+    io.kubernetes.cri-o.Devices: "/dev/fuse" <1>
+spec:
+  containers:
+  - name: build-container
+    image: quay.io/podman/stable <2>
+    command: ["/bin/sh", "-c"]
+    args: ["echo 'Container is running. Use oc exec to get a shell.'; sleep infinity"] <3>
+    securityContext: <4>
+      runAsUser: 1000
 ----
 +
+<1> The `io.kubernetes.cri-o.Devices: "/dev/fuse"` annotation makes the FUSE device available.
+<2> This annotation specifies a container that uses an image that includes `podman` (for example, `quay.io/podman/stable`).
+<3> This command keeps the container running so you can `exec` into it.
+<4> This annotation specifies a `securityContext` that runs the container as an unprivileged user (for example, `runAsUser: 1000`).
+* 
++
+[NOTE]
+====
+Depending on your cluster's Security Context Constraints (SCCs) or other policies, you might need to further adjust the `securityContext` specification, for example, by allowing specific capabilities if `/dev/fuse` alone is not sufficient for `fuse-overlayfs` to operate.
+====
++
+* Create the pod  by running the following command:
++
 [source,terminal]
 ----
-$ cat >> Dockerfile <<EOF
-FROM registry.access.redhat.com/ubi9
-EOF
+$ oc apply -f fuse-builder-pod.yaml
 ----
+
+. Verify that the pod is running:
 +
 [source,terminal]
 ----
-$ podman build .
+$ oc get pods fuse-builder-pod
 ----
 
-. Implement `/dev/fuse` by adding the `/dev/fuse` device to the `io.kubernetes.cri-o.Devices` annotation.
+. Access the pod and prepare the build environment:
 +
-[source,yaml]
+After the `fuse-builder-pod` pod is in the `Running` state, open a shell session into the `build-container` environment:
++
+[source,terminal]
 ----
-io.kubernetes.cri-o.Devices: "/dev/fuse"
+$ oc exec -ti fuse-builder-pod -- /bin/bash
 ----
 +
-For example:
+You are now inside the container. Because the default working directory might not be writable by the unprivileged user, change to a writable directory like `/tmp`:
 +
-[source,yaml]
+[source,terminal]
 ----
-apiVersion: v1
-kind: Pod
-metadata:
-  name: podman-pod
-  annotations:
-    io.kubernetes.cri-o.Devices: "/dev/fuse"
+$ cd /tmp
+$ pwd
+/tmp
 ----
 
-. Configure the `/dev/fuse` device in your pod specifications.
+. Create a dockerfile and build an image using Podman:
 +
-[source,yaml]
+Inside the pod's shell and within the `/tmp` directory, you can now create a `Dockerfile` and use `podman` to build a container image. If `fuse-overlayfs` is the default or configured storage driver, Podman is able to leverage `fuse-overlayfs` because of the available `/dev/fuse` device.
++
+.. Create a sample `Dockerfile`:
++
+[source,terminal]
 ----
-spec:
-  containers:
-  - name: podman-container
-    image: quay.io/podman/stable
-    args:
-    - sleep
-    - "1000000"
-    securityContext:
-      runAsUser: 1000
+$ cat > Dockerfile <<EOF
+FROM registry.access.redhat.com/ubi9/ubi-minimal
+RUN microdnf install -y findutils && microdnf clean all
+RUN echo "This image was built inside a pod with /dev/fuse by user $(id -u)" > /app/build_info.txt
+COPY Dockerfile /app/Dockerfile_copied
+WORKDIR /app
+CMD ["sh", "-c", "cat /app/build_info.txt && echo '--- Copied Dockerfile ---' && cat /app/Dockerfile_copied"]
+EOF
 ----
++
+.. Build the image using `podman`. The `-t` flag tags the image:
++
+[source,terminal]
+----
+$ podman build -t my-fuse-built-image:latest .
+----
++
+You should see Podman executing the build steps.
 
+. Optional: Test the built image:
++
+Still inside the `fuse-builder-pod`, you can run a container from the image you just built to test it:
++
+[source,terminal]
+----
+$ podman run --rm my-fuse-built-image:latest
+----
++
+This should output the content of the `/app/build_info.txt` file and the copied Dockerfile.
 
+. Exit the pod and clean up:
++
+* After you are done, exit the shell session in the pod:
++
+[source,terminal]
+----
+$ exit
+----
++
+* You can then delete the pod if it's no longer needed:
++
+[source,terminal]
+----
+$ oc delete pod fuse-builder-pod
+----
++
+* Remove the local YAML file:
++
+[source,terminal]
+----
+$ rm fuse-builder-pod.yaml
+----

nodes/containers/nodes-containers-dev-fuse.adoc

@@ -6,6 +6,6 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-You can configure your pods with the `/dev/fuse` device to access faster builds.
+You can configure your pods with the `/dev/fuse` device to enable faster and more efficient container image builds, particularly for unprivileged users. This device allows unprivileged pods to mount overlay filesystems, which can be leveraged by tools like Podman.
 
 include::modules/nodes-containers-dev-fuse-configuring.adoc[leveloffset=+1]