From ce7681d21e4e2605ccf22e11479bda511bedce66 Mon Sep 17 00:00:00 2001 From: Daniel Chadwick Date: Mon, 31 Mar 2025 16:39:26 -0400 Subject: [PATCH] osdocs10269 fixing devfuse instructions --- ...nodes-containers-dev-fuse-configuring.adoc | 161 +++++++++++++----- .../containers/nodes-containers-dev-fuse.adoc | 2 +- 2 files changed, 117 insertions(+), 46 deletions(-) diff --git a/modules/nodes-containers-dev-fuse-configuring.adoc b/modules/nodes-containers-dev-fuse-configuring.adoc index f112573e1c..8564759d2b 100644 --- a/modules/nodes-containers-dev-fuse-configuring.adoc +++ b/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] ----- -$ oc exec -ti no-priv -- /bin/bash ----- -+ -[source,terminal] ----- -$ cat >> Dockerfile < spec: -  containers: -  - name: podman-container -    image: quay.io/podman/stable -    args: -    - sleep -    - "1000000" -    securityContext: -      runAsUser: 1000 + 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] +---- +$ oc apply -f fuse-builder-pod.yaml ---- +. Verify that the pod is running: ++ +[source,terminal] +---- +$ oc get pods fuse-builder-pod +---- +. Access the pod and prepare the build environment: ++ +After the `fuse-builder-pod` pod is in the `Running` state, open a shell session into the `build-container` environment: ++ +[source,terminal] +---- +$ oc exec -ti fuse-builder-pod -- /bin/bash +---- ++ +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,terminal] +---- +$ cd /tmp +$ pwd +/tmp +---- + +. Create a dockerfile and build an image using Podman: ++ +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] +---- +$ cat > Dockerfile < /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 +---- diff --git a/nodes/containers/nodes-containers-dev-fuse.adoc b/nodes/containers/nodes-containers-dev-fuse.adoc index 71d357cc52..290a1cded1 100644 --- a/nodes/containers/nodes-containers-dev-fuse.adoc +++ b/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] \ No newline at end of file