Enable fuse-overlayfs with a ConfigMap

Enable fuse-overlayfs as the storage driver for Podman and Buildah by mounting a storage.conf ConfigMap into all workspaces in your namespace.

Here are the default contents of the /home/user/.config/containers/storage.conf file in the UDI container:

# storage.conf
[storage]
driver = "vfs"

To use fuse-overlayfs, storage.conf can be set to the following:

# storage.conf
[storage]
driver = "overlay"

[storage.options.overlay]
mount_program="/usr/bin/fuse-overlayfs"

where:

mount_program: The absolute path to the fuse-overlayfs binary. The /usr/bin/fuse-overlayfs path is the default for the UDI.

You can do this manually after starting a workspace. Another option is to build a new image based on the UDI with changes to storage.conf and use the new image for workspaces.

Otherwise, you can update the /home/user/.config/containers/storage.conf for all workspaces in your namespace by creating a ConfigMap that mounts the updated file. See Mount ConfigMaps.

Prerequisites

For Kubernetes versions older than 4.15, the administrator has enabled access to /dev/fuse. See Configuring fuse-overlayfs.

You have a workspace with the required annotations as described in Access /dev/fuse in workspace containers.

ConfigMaps mounted by following this guide apply to all workspaces and set the storage driver to fuse-overlayfs globally. Verify that your workspaces contain the required annotations to use fuse-overlayfs as described in Access /dev/fuse in workspace containers.

Procedure

Create a ConfigMap that mounts a /home/user/.config/containers/storage.conf file:

kind: ConfigMap
apiVersion: v1
metadata:
  name: fuse-overlay
  labels:
    controller.devfile.io/mount-to-devworkspace: 'true'
    controller.devfile.io/watch-configmap: 'true'
  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"

Apply the ConfigMap to your namespace:

Applying this ConfigMap causes all running workspaces in the namespace to restart.
```
$ kubectl apply -f fuse-overlay.yaml -n <your_namespace>
```
Start or restart your workspace.

Verification

Verify that the storage driver is overlay:

$ podman info | grep overlay

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
  Backing Filesystem: overlayfs

The following error might occur for existing workspaces:

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 shown in the error message.

Additional resources