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.

  • 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.

  1. 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
  2. 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
  3. 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}
      labels: ${NODE_ROLE}
      name: 99-podman-dev-fuse-${NODE_ROLE}
      - 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)
            allowed_devices = ["/dev/fuse"] (6)
    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.
  4. 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
  5. 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
  1. Get the name of a node with a worker role:

    $ oc get nodes
  2. Open an oc debug session to a worker node.

    $ oc debug node/<nodename>
  3. 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.