Configuring fuse-overlayfs

By default, the Universal Developer Image (UDI) contains Podman and Buildah which you can use to build and push container images within a workspace. However, Podman and Buildah in the UDI are configured to use the vfs storage driver which does not provide copy-on-write support. For more efficient image management, use the fuse-overlayfs storage driver which supports copy-on-write in rootless environments.

Enabling container access to /dev/fuse for OpenShift

To use fuse-overlayfs, you must make /dev/fuse accessible to workspace containers first.

This procedure is not necessary for OpenShift versions 4.15 and later, since the /dev/fuse device is available by default. See Release Notes.

Creating MachineConfig resources on an OpenShift cluster is a potentially dangerous task, as you are making advanced, system-level changes to the cluster.

View the MachineConfig documentation for more details and possible risks.

Prerequisites

The Butane tool (butane) is installed in the operating system you are using.
An active kubectl session with administrative permissions to the destination OpenShift cluster. See Overview of kubectl.

Procedure

Set the environment variable based on the type of your OpenShift cluster: a single node cluster, or a multi node cluster with separate control plane and worker nodes.
- For a single node cluster, set:
  $ NODE_ROLE=master
- For a multi node cluster, set:
  $ NODE_ROLE=worker
Set the environment variable for the OpenShift Butane config version. This variable is the major and minor version of the OpenShift cluster. For example, 4.12.0, 4.13.0, or 4.14.0.
```
$ VERSION=4.12.0
```

Create a MachineConfig resource that creates a drop-in CRI-O configuration file named 99-podman-fuse in the NODE_ROLE nodes. This configuration file makes access to the /dev/fuse device possible for certain pods.

cat << EOF | butane | oc apply -f -
variant: openshift
version: ${VERSION}
metadata:
  labels:
    machineconfiguration.openshift.io/role: ${NODE_ROLE}
  name: 99-podman-dev-fuse-${NODE_ROLE}
storage:
  files:
  - path: /etc/crio/crio.conf.d/99-podman-fuse (1)
    mode: 0644
    overwrite: true
    contents: (2)
      inline: |
        [crio.runtime.workloads.podman-fuse] (3)
        activation_annotation = "io.openshift.podman-fuse" (4)
        allowed_annotations = [
          "io.kubernetes.cri-o.Devices" (5)
        ]
        [crio.runtime]
        allowed_devices = ["/dev/fuse"] (6)
EOF

1	The absolute file path to the new drop-in configuration file for CRI-O.
2	The content of the new drop-in configuration file.
3	Define a `podman-fuse` workload.
4	The pod annotation that activates the `podman-fuse` workload settings.
5	List of annotations the `podman-fuse` workload is allowed to process.
6	List of devices on the host that a user can specify with the `io.kubernetes.cri-o.Devices` annotation.

After applying the MachineConfig resource, scheduling will be temporarily disabled for each node with the worker role as changes are applied. View the nodes' statuses.

$ oc get nodes

Example output:

NAME                           STATUS                     ROLES    AGE   VERSION
ip-10-0-136-161.ec2.internal   Ready                      worker   28m   v1.27.9
ip-10-0-136-243.ec2.internal   Ready                      master   34m   v1.27.9
ip-10-0-141-105.ec2.internal   Ready,SchedulingDisabled   worker   28m   v1.27.9
ip-10-0-142-249.ec2.internal   Ready                      master   34m   v1.27.9
ip-10-0-153-11.ec2.internal    Ready                      worker   28m   v1.27.9
ip-10-0-153-150.ec2.internal   Ready                      master   34m   v1.27.9

Once all nodes with the worker role have a status Ready, /dev/fuse will be available to any pod with the following annotations.
```
io.openshift.podman-fuse: ''
io.kubernetes.cri-o.Devices: /dev/fuse
```

Verification steps

Get the name of a node with a worker role:
```
$ oc get nodes
```
Open an oc debug session to a worker node.
```
$ oc debug node/<nodename>
```
Verify that a new CRI-O config file named 99-podman-fuse exists.
```
sh-4.4# stat /host/etc/crio/crio.conf.d/99-podman-fuse
```

Using fuse-overlayfs for Podman and Buildah within a workspace

Users can follow Using the fuse-overlayfs storage driver for Podman and Buildah to update existing workspaces to use the fuse-overlayfs storage driver for Podman and Buildah.