From 91d7f6b5092fe86cb7d8028ab5db37957af3d9af Mon Sep 17 00:00:00 2001 From: dkwon17 Date: Thu, 2 Jan 2025 16:27:26 +0000 Subject: [PATCH] feat: add fuse docs for Podman 5 Signed-off-by: dkwon17 --- modules/administration-guide/nav.adoc | 2 + .../enabling-fuse-for-all-workspaces.adoc | 93 +------------- .../pages/enabling-fuse-for-podman-4.adoc | 99 +++++++++++++++ .../pages/enabling-fuse-for-podman-5.adoc | 116 ++++++++++++++++++ 4 files changed, 223 insertions(+), 87 deletions(-) create mode 100644 modules/administration-guide/pages/enabling-fuse-for-podman-4.adoc create mode 100644 modules/administration-guide/pages/enabling-fuse-for-podman-5.adoc diff --git a/modules/administration-guide/nav.adoc b/modules/administration-guide/nav.adoc index 2b1529feec..fd0a433671 100644 --- a/modules/administration-guide/nav.adoc +++ b/modules/administration-guide/nav.adoc @@ -102,6 +102,8 @@ ** xref:configuring-fuse.adoc[] *** xref:enabling-access-to-dev-fuse-for-openshift.adoc[] *** xref:enabling-fuse-for-all-workspaces.adoc[] +**** xref:enabling-fuse-for-podman-4.adoc[] +**** xref:enabling-fuse-for-podman-5.adoc[] * xref:managing-ide-extensions.adoc[] ** xref:extensions-for-microsoft-visual-studio-code-open-source.adoc[] ** xref:configuring-the-open-vsx-registry-url.adoc[] diff --git a/modules/administration-guide/pages/enabling-fuse-for-all-workspaces.adoc b/modules/administration-guide/pages/enabling-fuse-for-all-workspaces.adoc index 4f8379ae23..656edaedd7 100644 --- a/modules/administration-guide/pages/enabling-fuse-for-all-workspaces.adoc +++ b/modules/administration-guide/pages/enabling-fuse-for-all-workspaces.adoc @@ -1,4 +1,4 @@ -:_content-type: PROCEDURE +:_content-type: CONCEPT :description: Enabling fuse-overlayfs for all workspaces :keywords: administration-guide, enable, fuse, all, workspaces :navtitle: Enabling fuse-overlayfs for all workspaces @@ -7,91 +7,10 @@ [id="enabling-fuse-overlayfs-for-all-workspaces"] = Enabling fuse-overlayfs for all workspaces -.Prerequisites +Podman's storage driver is configured in the `/home/user/.config/containers/storage.conf` file. -* 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 workspaces running Podman version 4.x, the fuse-overlayfs config can be applied to all user workspaces globally by creating a ConfigMap that defines the `storage.conf` file. +However for Podman version 5.x, this method will not work since version 5.x requires that `/home/user/.config` is owned by the current user. -* 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. -+ -==== -[source,yaml,subs="+quotes,+attributes"] ----- -kind: CheCluster -apiVersion: org.eclipse.che/v2 -spec: - devEnvironments: - workspacesPodAnnotations: - io.kubernetes.cri-o.Devices: /dev/fuse ----- -==== -+ -[NOTE] -==== -For OpenShift versions before 4.15, the `io.openshift.podman-fuse: ""` annotation is also required. -==== - -.Verification steps - -. Start a workspace and verify that the storage driver is `overlay`. -+ -[subs="+attributes,+quotes"] ----- -$ podman info | grep overlay ----- - -+ -Example output: -+ -[subs="+attributes,+quotes"] ----- -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 - Backing Filesystem: overlayfs ----- -+ -[NOTE] -==== -The following error might occur for existing workspaces: - -[source] ----- -ERRO[0000] User-selected graph driver "overlay" overwritten by graph driver "vfs" from database - delete libpod local files ("/home/user/.local/share/containers/storage") to resolve. May prevent use of images created by other tools ----- - -In this case, delete the libpod local files as mentioned in the error message. -==== +* xref:enabling-fuse-for-podman-4.adoc[] +* xref:enabling-fuse-for-podman-5.adoc[] diff --git a/modules/administration-guide/pages/enabling-fuse-for-podman-4.adoc b/modules/administration-guide/pages/enabling-fuse-for-podman-4.adoc new file mode 100644 index 0000000000..f414619391 --- /dev/null +++ b/modules/administration-guide/pages/enabling-fuse-for-podman-4.adoc @@ -0,0 +1,99 @@ +:_content-type: PROCEDURE +:description: Enabling fuse-overlayfs for Podman 4 +:keywords: administration-guide, enable, fuse, all, workspaces, podman +:navtitle: Enabling fuse-overlayfs for Podman 4 +:page-aliases: + +[id="enabling-fuse-overlayfs-for-podman-4"] += Enabling fuse-overlayfs for all workspaces for Podman 4 + +.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. + +* An active `{orch-cli}` session with administrative permissions to the destination OpenShift cluster. See {orch-cli-link}. + +* All workspaces that contain Podman are using Podman version 4.x. + +.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. ++ +==== +[source,yaml,subs="+quotes,+attributes"] +---- +kind: CheCluster +apiVersion: org.eclipse.che/v2 +spec: + devEnvironments: + workspacesPodAnnotations: + io.kubernetes.cri-o.Devices: /dev/fuse +---- +==== ++ +[NOTE] +==== +For OpenShift versions before 4.15, the `io.openshift.podman-fuse: ""` annotation is also required. +==== + +.Verification steps + +. Start a workspace and verify that the storage driver is `overlay`. ++ +[subs="+attributes,+quotes"] +---- +$ podman info | grep overlay +---- + ++ +Example output: ++ +[subs="+attributes,+quotes"] +---- +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 + Backing Filesystem: overlayfs +---- ++ +[NOTE] +==== +The following error might occur for existing workspaces: + +[source] +---- +ERRO[0000] User-selected graph driver "overlay" overwritten by graph driver "vfs" from database - delete libpod local files ("/home/user/.local/share/containers/storage") to resolve. May prevent use of images created by other tools +---- + +In this case, delete the libpod local files as mentioned in the error message. +==== diff --git a/modules/administration-guide/pages/enabling-fuse-for-podman-5.adoc b/modules/administration-guide/pages/enabling-fuse-for-podman-5.adoc new file mode 100644 index 0000000000..0038656ebe --- /dev/null +++ b/modules/administration-guide/pages/enabling-fuse-for-podman-5.adoc @@ -0,0 +1,116 @@ +:_content-type: PROCEDURE +:description: Enabling fuse-overlayfs for Podman 5 +:keywords: administration-guide, enable, fuse, all, workspaces, podman +:navtitle: Enabling fuse-overlayfs for Podman 5 +:page-aliases: + +[id="enabling-fuse-overlayfs-for-podman-5"] += Enabling fuse-overlayfs for all workspaces for Podman 5 + +For Podman 5, 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 container entrypoint script for the workspace so that fuse-overlayfs is being used. +The Universal Developer Image (UDI) already contains the necessary configuration by default. + +.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. + +* An active `{orch-cli}` session with administrative permissions to the destination OpenShift cluster. See {orch-cli-link}. + +.Procedure + +. Set the necessary annotation in the `spec.devEnvironments.workspacesPodAnnotations` field of the CheCluster custom resource. ++ +==== +[source,yaml,subs="+quotes,+attributes"] +---- +kind: CheCluster +apiVersion: org.eclipse.che/v2 +spec: + devEnvironments: + workspacesPodAnnotations: + io.kubernetes.cri-o.Devices: /dev/fuse +---- +==== ++ +[NOTE] +==== +For OpenShift versions before 4.15, the `io.openshift.podman-fuse: ""` annotation is also required. +==== + +. 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, create add the following to the workspace container image's entrypoint script before building the image. ++ +==== +[source,bash,subs="+attributes,+quotes"] +---- +# 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. +==== + +.Verification steps + +. 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"] +---- +$ podman info | grep overlay +---- + ++ +Example output: ++ +[subs="+attributes,+quotes"] +---- +graphDriverName: overlay + overlay.mount_program: + Executable: /usr/bin/fuse-overlayfs + Package: fuse-overlayfs-1.14-1.el9.x86_64 + fuse-overlayfs: version 1.13-dev + Backing Filesystem: overlayfs +---- ++ +[NOTE] +==== +The following error might occur for existing workspaces: + +[source] +---- +ERRO[0000] User-selected graph driver "overlay" overwritten by graph driver "vfs" from database - delete libpod local files ("/home/user/.local/share/containers/storage") to resolve. May prevent use of images created by other tools +---- + +In this case, delete the libpod local files as mentioned in the error message. +====