Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update fuse docs for Podman 5.x #2842

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
+52 −33
Open

Update fuse docs for Podman 5.x #2842

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d140ef6
feat: update fuse docs for Podman 5.x
dkwon17 Jan 2, 2025
081bc8b
Address PR feedback
dkwon17 Jan 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 52 additions & 33 deletions modules/administration-guide/pages/enabling-fuse-for-all-workspaces.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,42 +7,19 @@
[id="enabling-fuse-overlayfs-for-all-workspaces"]
= Enabling fuse-overlayfs for all workspaces

For Podman 5.x, the `/home/user/.config` must be owned by the current user for Podman to function correctly.
The `storage.conf` file for Podman is typically stored in this folder.
This document explains how to configure the workspace's container entrypoint script for the workspace so that fuse-overlayfs is being used for all workspaces using that container.
The Universal Developer Image (UDI) already contains the necessary configuration by default.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

when you refer to the configuration already contained in UDI, what sort of configuration are you referring to? the one from the previous line (container entrypoint script)?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, the container entrypoint script, for example:
https://github.com/devfile/developer-images/blob/e24cbd7d58b8a744467db2e404314b63c30d8f85/base/ubi9/entrypoint.sh#L8-L16


.Prerequisites

* The xref:administration-guide:enabling-access-to-dev-fuse-for-openshift.adoc[] section has been completed. This is not required for OpenShift versions 4.15 and later.
* For OpenShift versions 4.14 and lower, the xref:administration-guide:enabling-access-to-dev-fuse-for-openshift.adoc[] section has been completed.

* An active `{orch-cli}` session with administrative permissions to the destination OpenShift cluster. See {orch-cli-link}.

.Procedure

. Create a ConfigMap that mounts the `storage.conf` file for all user workspaces.
+
====
[source,yaml,subs="+quotes,+attributes"]
----
kind: ConfigMap
apiVersion: v1
metadata:
name: fuse-overlay
namespace: {prod-namespace}
labels:
app.kubernetes.io/part-of: che.eclipse.org
app.kubernetes.io/component: workspaces-config
annotations:
controller.devfile.io/mount-as: subpath
controller.devfile.io/mount-path: /home/user/.config/containers/
data:
storage.conf: |
[storage]
driver = "overlay"

[storage.options.overlay]
mount_program="/usr/bin/fuse-overlayfs"
----
====
+
WARNING: Creating this ConfigMap will cause all running workspaces to restart.

. Set the necessary annotation in the `spec.devEnvironments.workspacesPodAnnotations` field of the CheCluster custom resource.
+
====
Expand All @@ -59,12 +36,54 @@ spec:
+
[NOTE]
====
For OpenShift versions before 4.15, the `io.openshift.podman-fuse: ""` annotation is also required.
For OpenShift versions 4.14 and lower, the `io.openshift.podman-fuse: ""` annotation is also required.
====

. Optional: If you are using a custom image for the workspace container, create the `/home/user/.config` folder and configure the `storage.conf` file on runtime via the entrypoint.
To do this, add the following to the workspace container image's entrypoint script before building the image.
+
====
[source,subs="+quotes,+macros"]
----
# Configure container builds to use vfs or fuse-overlayfs
if [ ! -d "${HOME}/.config/containers" ]; then
mkdir -p ${HOME}/.config/containers
if [ -c "/dev/fuse" ] && [ -f "/usr/bin/fuse-overlayfs" ]; then
(echo '[storage]';echo 'driver = "overlay"';echo '[storage.options.overlay]';echo 'mount_program = "/usr/bin/fuse-overlayfs"') > ${HOME}/.config/containers/storage.conf
else
(echo '[storage]';echo 'driver = "vfs"') > "${HOME}"/.config/containers/storage.conf
fi
fi
----
====
+
This ensures that if the `/home/user/.config` doesn't already exist, the folder is created and owned by `user`.
The `/home/user/.config` may already exist for example, if it was stored in a persistent volume.
+
[NOTE]
====
This is configured in the UDI by default. Therefore this step is only required if you are using a custom image for the workspace container.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe we could mark the whole step as [OPTIONAL] since it's only required for custom images

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've added an Optional: at the start of the sentence, does that work?

====

.Verification steps

. Start a workspace and verify that the storage driver is `overlay`.
. Start a workspace and verify that the owner for `/home/user/.config` is `user`.
+
[subs="+attributes,+quotes"]
----
$ ls -la /home/user
----

+
Example output:
+
[subs="+attributes,+quotes"]
----
...
drwxrwsr-x. 3 user 1000660000 24 Dec 24 15:40 .config
----

. Verify that the storage driver is `overlay`.
+
[subs="+attributes,+quotes"]
----
Expand All @@ -79,8 +98,8 @@ Example output:
graphDriverName: overlay
overlay.mount_program:
Executable: /usr/bin/fuse-overlayfs
Package: fuse-overlayfs-1.12-1.module+el8.9.0+20326+387084d0.x86_64
fuse-overlayfs: version 1.12
Package: fuse-overlayfs-1.14-1.el9.x86_64
fuse-overlayfs: version 1.13-dev
Backing Filesystem: overlayfs
----
+
Expand Down
Loading