Skip to content

Commit 91d7f6b

Browse files
dkwon17dkwon17
committed
feat: add fuse docs for Podman 5
Signed-off-by: dkwon17 <dakwon@redhat.com>
1 parent a2fe463 commit 91d7f6b

File tree

4 files changed

+223
-87
lines changed

4 files changed

+223
-87
lines changed

‎modules/administration-guide/nav.adoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,8 @@
102102
** xref:configuring-fuse.adoc[]
103103
*** xref:enabling-access-to-dev-fuse-for-openshift.adoc[]
104104
*** xref:enabling-fuse-for-all-workspaces.adoc[]
105+
**** xref:enabling-fuse-for-podman-4.adoc[]
106+
**** xref:enabling-fuse-for-podman-5.adoc[]
105107
* xref:managing-ide-extensions.adoc[]
106108
** xref:extensions-for-microsoft-visual-studio-code-open-source.adoc[]
107109
** xref:configuring-the-open-vsx-registry-url.adoc[]

‎modules/administration-guide/pages/enabling-fuse-for-all-workspaces.adoc

Lines changed: 6 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
:_content-type: PROCEDURE
1+
:_content-type: CONCEPT
22
:description: Enabling fuse-overlayfs for all workspaces
33
:keywords: administration-guide, enable, fuse, all, workspaces
44
:navtitle: Enabling fuse-overlayfs for all workspaces
@@ -7,91 +7,10 @@
77
[id="enabling-fuse-overlayfs-for-all-workspaces"]
88
= Enabling fuse-overlayfs for all workspaces
99

10-
.Prerequisites
10+
Podman's storage driver is configured in the `/home/user/.config/containers/storage.conf` file.
1111

12-
* 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.
12+
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.
13+
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.
1314

14-
* An active `{orch-cli}` session with administrative permissions to the destination OpenShift cluster. See {orch-cli-link}.
15-
16-
.Procedure
17-
18-
. Create a ConfigMap that mounts the `storage.conf` file for all user workspaces.
19-
+
20-
====
21-
[source,yaml,subs="+quotes,+attributes"]
22-
----
23-
kind: ConfigMap
24-
apiVersion: v1
25-
metadata:
26-
name: fuse-overlay
27-
namespace: {prod-namespace}
28-
labels:
29-
app.kubernetes.io/part-of: che.eclipse.org
30-
app.kubernetes.io/component: workspaces-config
31-
annotations:
32-
controller.devfile.io/mount-as: subpath
33-
controller.devfile.io/mount-path: /home/user/.config/containers/
34-
data:
35-
storage.conf: |
36-
[storage]
37-
driver = "overlay"
38-
39-
[storage.options.overlay]
40-
mount_program="/usr/bin/fuse-overlayfs"
41-
----
42-
====
43-
+
44-
WARNING: Creating this ConfigMap will cause all running workspaces to restart.
45-
46-
. Set the necessary annotation in the `spec.devEnvironments.workspacesPodAnnotations` field of the CheCluster custom resource.
47-
+
48-
====
49-
[source,yaml,subs="+quotes,+attributes"]
50-
----
51-
kind: CheCluster
52-
apiVersion: org.eclipse.che/v2
53-
spec:
54-
devEnvironments:
55-
workspacesPodAnnotations:
56-
io.kubernetes.cri-o.Devices: /dev/fuse
57-
----
58-
====
59-
+
60-
[NOTE]
61-
====
62-
For OpenShift versions before 4.15, the `io.openshift.podman-fuse: ""` annotation is also required.
63-
====
64-
65-
.Verification steps
66-
67-
. Start a workspace and verify that the storage driver is `overlay`.
68-
+
69-
[subs="+attributes,+quotes"]
70-
----
71-
$ podman info | grep overlay
72-
----
73-
74-
+
75-
Example output:
76-
+
77-
[subs="+attributes,+quotes"]
78-
----
79-
graphDriverName: overlay
80-
overlay.mount_program:
81-
Executable: /usr/bin/fuse-overlayfs
82-
Package: fuse-overlayfs-1.12-1.module+el8.9.0+20326+387084d0.x86_64
83-
fuse-overlayfs: version 1.12
84-
Backing Filesystem: overlayfs
85-
----
86-
+
87-
[NOTE]
88-
====
89-
The following error might occur for existing workspaces:
90-
91-
[source]
92-
----
93-
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
94-
----
95-
96-
In this case, delete the libpod local files as mentioned in the error message.
97-
====
15+
* xref:enabling-fuse-for-podman-4.adoc[]
16+
* xref:enabling-fuse-for-podman-5.adoc[]

‎modules/administration-guide/pages/enabling-fuse-for-podman-4.adoc

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
:_content-type: PROCEDURE
2+
:description: Enabling fuse-overlayfs for Podman 4
3+
:keywords: administration-guide, enable, fuse, all, workspaces, podman
4+
:navtitle: Enabling fuse-overlayfs for Podman 4
5+
:page-aliases:
6+
7+
[id="enabling-fuse-overlayfs-for-podman-4"]
8+
= Enabling fuse-overlayfs for all workspaces for Podman 4
9+
10+
.Prerequisites
11+
12+
* 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.
13+
14+
* An active `{orch-cli}` session with administrative permissions to the destination OpenShift cluster. See {orch-cli-link}.
15+
16+
* All workspaces that contain Podman are using Podman version 4.x.
17+
18+
.Procedure
19+
20+
. Create a ConfigMap that mounts the `storage.conf` file for all user workspaces.
21+
+
22+
====
23+
[source,yaml,subs="+quotes,+attributes"]
24+
----
25+
kind: ConfigMap
26+
apiVersion: v1
27+
metadata:
28+
name: fuse-overlay
29+
namespace: {prod-namespace}
30+
labels:
31+
app.kubernetes.io/part-of: che.eclipse.org
32+
app.kubernetes.io/component: workspaces-config
33+
annotations:
34+
controller.devfile.io/mount-as: subpath
35+
controller.devfile.io/mount-path: /home/user/.config/containers/
36+
data:
37+
storage.conf: |
38+
[storage]
39+
driver = "overlay"
40+
41+
[storage.options.overlay]
42+
mount_program="/usr/bin/fuse-overlayfs"
43+
----
44+
====
45+
+
46+
WARNING: Creating this ConfigMap will cause all running workspaces to restart.
47+
48+
. Set the necessary annotation in the `spec.devEnvironments.workspacesPodAnnotations` field of the CheCluster custom resource.
49+
+
50+
====
51+
[source,yaml,subs="+quotes,+attributes"]
52+
----
53+
kind: CheCluster
54+
apiVersion: org.eclipse.che/v2
55+
spec:
56+
devEnvironments:
57+
workspacesPodAnnotations:
58+
io.kubernetes.cri-o.Devices: /dev/fuse
59+
----
60+
====
61+
+
62+
[NOTE]
63+
====
64+
For OpenShift versions before 4.15, the `io.openshift.podman-fuse: ""` annotation is also required.
65+
====
66+
67+
.Verification steps
68+
69+
. Start a workspace and verify that the storage driver is `overlay`.
70+
+
71+
[subs="+attributes,+quotes"]
72+
----
73+
$ podman info | grep overlay
74+
----
75+
76+
+
77+
Example output:
78+
+
79+
[subs="+attributes,+quotes"]
80+
----
81+
graphDriverName: overlay
82+
overlay.mount_program:
83+
Executable: /usr/bin/fuse-overlayfs
84+
Package: fuse-overlayfs-1.12-1.module+el8.9.0+20326+387084d0.x86_64
85+
fuse-overlayfs: version 1.12
86+
Backing Filesystem: overlayfs
87+
----
88+
+
89+
[NOTE]
90+
====
91+
The following error might occur for existing workspaces:
92+
93+
[source]
94+
----
95+
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
96+
----
97+
98+
In this case, delete the libpod local files as mentioned in the error message.
99+
====

‎modules/administration-guide/pages/enabling-fuse-for-podman-5.adoc

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
:_content-type: PROCEDURE
2+
:description: Enabling fuse-overlayfs for Podman 5
3+
:keywords: administration-guide, enable, fuse, all, workspaces, podman
4+
:navtitle: Enabling fuse-overlayfs for Podman 5
5+
:page-aliases:
6+
7+
[id="enabling-fuse-overlayfs-for-podman-5"]
8+
= Enabling fuse-overlayfs for all workspaces for Podman 5
9+
10+
For Podman 5, the `/home/user/.config` must be owned by the current user for Podman to function correctly.
11+
The `storage.conf` file for Podman is typically stored in this folder.
12+
This document explains how to configure the container entrypoint script for the workspace so that fuse-overlayfs is being used.
13+
The Universal Developer Image (UDI) already contains the necessary configuration by default.
14+
15+
.Prerequisites
16+
17+
* 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.
18+
19+
* An active `{orch-cli}` session with administrative permissions to the destination OpenShift cluster. See {orch-cli-link}.
20+
21+
.Procedure
22+
23+
. Set the necessary annotation in the `spec.devEnvironments.workspacesPodAnnotations` field of the CheCluster custom resource.
24+
+
25+
====
26+
[source,yaml,subs="+quotes,+attributes"]
27+
----
28+
kind: CheCluster
29+
apiVersion: org.eclipse.che/v2
30+
spec:
31+
devEnvironments:
32+
workspacesPodAnnotations:
33+
io.kubernetes.cri-o.Devices: /dev/fuse
34+
----
35+
====
36+
+
37+
[NOTE]
38+
====
39+
For OpenShift versions before 4.15, the `io.openshift.podman-fuse: ""` annotation is also required.
40+
====
41+
42+
. 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.
43+
To do this, create add the following to the workspace container image's entrypoint script before building the image.
44+
+
45+
====
46+
[source,bash,subs="+attributes,+quotes"]
47+
----
48+
# Configure container builds to use vfs or fuse-overlayfs
49+
if [ ! -d "${HOME}/.config/containers" ]; then
50+
mkdir -p ${HOME}/.config/containers
51+
if [ -c "/dev/fuse" ] && [ -f "/usr/bin/fuse-overlayfs" ]; then
52+
(echo '[storage]';echo 'driver = "overlay"';echo '[storage.options.overlay]';echo 'mount_program = "/usr/bin/fuse-overlayfs"') > ${HOME}/.config/containers/storage.conf
53+
else
54+
(echo '[storage]';echo 'driver = "vfs"') > "${HOME}"/.config/containers/storage.conf
55+
fi
56+
fi
57+
----
58+
====
59+
+
60+
This ensures that if the `/home/user/.config` doesn't already exist, the folder is created and owned by `user`.
61+
The `/home/user/.config` may already exist for example, if it was stored in a persistent volume.
62+
+
63+
[NOTE]
64+
====
65+
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.
66+
====
67+
68+
.Verification steps
69+
70+
. Start a workspace and verify that the owner for `/home/user/.config` is `user`.
71+
+
72+
[subs="+attributes,+quotes"]
73+
----
74+
$ ls -la /home/user
75+
----
76+
77+
+
78+
Example output:
79+
+
80+
[subs="+attributes,+quotes"]
81+
----
82+
...
83+
drwxrwsr-x. 3 user 1000660000 24 Dec 24 15:40 .config
84+
----
85+
86+
. Verify that the storage driver is `overlay`.
87+
+
88+
[subs="+attributes,+quotes"]
89+
----
90+
$ podman info | grep overlay
91+
----
92+
93+
+
94+
Example output:
95+
+
96+
[subs="+attributes,+quotes"]
97+
----
98+
graphDriverName: overlay
99+
overlay.mount_program:
100+
Executable: /usr/bin/fuse-overlayfs
101+
Package: fuse-overlayfs-1.14-1.el9.x86_64
102+
fuse-overlayfs: version 1.13-dev
103+
Backing Filesystem: overlayfs
104+
----
105+
+
106+
[NOTE]
107+
====
108+
The following error might occur for existing workspaces:
109+
110+
[source]
111+
----
112+
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
113+
----
114+
115+
In this case, delete the libpod local files as mentioned in the error message.
116+
====

0 commit comments

Comments
 (0)