|
| 1 | +:_content-type: PROCEDURE |
| 2 | +:description: Configuring fuse-overlayfs |
| 3 | +:keywords: administration-guide, configuring, fuse |
| 4 | +:navtitle: Configuring fuse-overlayfs |
| 5 | +:page-aliases: |
| 6 | + |
| 7 | +[id="configuring-fuse-overlayfs"] |
| 8 | += Configuring fuse-overlayfs |
| 9 | + |
| 10 | +By default, the Universal Developer Image (UDI) contains Podman and Buildah which you can use to build and push container images within a workspace. |
| 11 | +However, Podman and Buildah in the UDI are configured to use the `vfs` storage driver which does not provide copy-on-write support. |
| 12 | +For more efficient image management, use the fuse-overlayfs storage driver which supports copy-on-write in rootless environments. |
| 13 | + |
| 14 | + |
| 15 | +== Enabling container access to /dev/fuse for OpenShift |
| 16 | + |
| 17 | +To use fuse-overlayfs, you must make `/dev/fuse` accessible to workspace containers first. |
| 18 | + |
| 19 | +[WARNING] |
| 20 | +==== |
| 21 | +Creating `MachineConfig` resources on an OpenShift cluster is a potentially dangerous task, as you are making advanced, system-level changes to the cluster. |
| 22 | +
|
| 23 | +View the link:https://docs.openshift.com/container-platform/{ocp4-ver}/post_installation_configuration/machine-configuration-tasks.html#machine-config-overview-post-install-machine-configuration-tasks[MachineConfig documentation] for more details and possible risks. |
| 24 | +
|
| 25 | +==== |
| 26 | + |
| 27 | +.Prerequisites |
| 28 | + |
| 29 | +* The link:https://docs.openshift.com/container-platform/{ocp4-ver}/installing/install_config/installing-customizing.html#installation-special-config-butane-install_installing-customizing[Butane] tool (`butane`) is installed in the operating system you are using. |
| 30 | + |
| 31 | +* An active `{orch-cli}` session with administrative permissions to the destination OpenShift cluster. See {orch-cli-link}. |
| 32 | + |
| 33 | +.Procedure |
| 34 | + |
| 35 | +. 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. |
| 36 | ++ |
| 37 | +* For a single node cluster, set: |
| 38 | ++ |
| 39 | +[subs="+quotes,+attributes,+macros"] |
| 40 | +---- |
| 41 | +$ NODE_ROLE=master |
| 42 | +---- |
| 43 | ++ |
| 44 | +* For a multi node cluster, set: |
| 45 | +[subs="+quotes,+attributes,+macros"] |
| 46 | ++ |
| 47 | +---- |
| 48 | +$ NODE_ROLE=worker |
| 49 | +---- |
| 50 | + |
| 51 | +. 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`. |
| 52 | ++ |
| 53 | +[subs="+quotes,+attributes,+macros"] |
| 54 | +---- |
| 55 | +$ VERSION=4.12.0 |
| 56 | +---- |
| 57 | ++ |
| 58 | +. 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. |
| 59 | ++ |
| 60 | +[source,subs="+quotes,+macros"] |
| 61 | +---- |
| 62 | +cat << EOF | butane | oc apply -f - |
| 63 | +variant: openshift |
| 64 | +version: ${VERSION} |
| 65 | +metadata: |
| 66 | + labels: |
| 67 | + machineconfiguration.openshift.io/role: ${NODE_ROLE} |
| 68 | + name: 99-podman-dev-fuse-${NODE_ROLE} |
| 69 | +storage: |
| 70 | + files: |
| 71 | + - path: /etc/crio/crio.conf.d/99-podman-fuse <1> |
| 72 | + mode: 0644 |
| 73 | + overwrite: true |
| 74 | + contents: <2> |
| 75 | + inline: | |
| 76 | + [crio.runtime.workloads.podman-fuse] <3> |
| 77 | + activation_annotation = "io.openshift.podman-fuse" <4> |
| 78 | + allowed_annotations = [ |
| 79 | + "io.kubernetes.cri-o.Devices" <5> |
| 80 | + ] |
| 81 | + [crio.runtime] |
| 82 | + allowed_devices = ["/dev/fuse"] <6> |
| 83 | +EOF |
| 84 | +---- |
| 85 | +<1> The absolute file path to the new drop-in configuration file for CRI-O. |
| 86 | +<2> The content of the new drop-in configuration file. |
| 87 | +<3> Define a `podman-fuse` workload. |
| 88 | +<4> The pod annotation that activates the `podman-fuse` workload settings. |
| 89 | +<5> List of annotations the `podman-fuse` workload is allowed to process. |
| 90 | +<6> List of devices on the host that a user can specify with the `io.kubernetes.cri-o.Devices` annotation. |
| 91 | ++ |
| 92 | +. 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. |
| 93 | ++ |
| 94 | +[subs="+quotes,+attributes,+macros"] |
| 95 | +---- |
| 96 | +$ oc get nodes |
| 97 | +---- |
| 98 | ++ |
| 99 | +Example output: |
| 100 | ++ |
| 101 | +[subs="+quotes,+attributes,+macros"] |
| 102 | +---- |
| 103 | +NAME STATUS ROLES AGE VERSION |
| 104 | +ip-10-0-136-161.ec2.internal Ready worker 28m v1.27.9 |
| 105 | +ip-10-0-136-243.ec2.internal Ready master 34m v1.27.9 |
| 106 | +ip-10-0-141-105.ec2.internal Ready,SchedulingDisabled worker 28m v1.27.9 |
| 107 | +ip-10-0-142-249.ec2.internal Ready master 34m v1.27.9 |
| 108 | +ip-10-0-153-11.ec2.internal Ready worker 28m v1.27.9 |
| 109 | +ip-10-0-153-150.ec2.internal Ready master 34m v1.27.9 |
| 110 | +---- |
| 111 | ++ |
| 112 | +. Once all nodes with the `worker` role have a status `Ready`, `/dev/fuse` will be available to any pod with the following annotations. |
| 113 | ++ |
| 114 | +[source,yaml,subs="+quotes,+attributes"] |
| 115 | +---- |
| 116 | +io.openshift.podman-fuse: '' |
| 117 | +io.kubernetes.cri-o.Devices: /dev/fuse |
| 118 | +---- |
| 119 | + |
| 120 | +.Verification steps |
| 121 | + |
| 122 | +. Get the name of a node with a `worker` role: |
| 123 | ++ |
| 124 | +[subs="+attributes,+quotes"] |
| 125 | +---- |
| 126 | +$ oc get nodes |
| 127 | +---- |
| 128 | + |
| 129 | +. Open an `oc debug` session to a worker node. |
| 130 | ++ |
| 131 | +[subs="+attributes,+quotes"] |
| 132 | +---- |
| 133 | +$ oc debug node/__<nodename>__ |
| 134 | +---- |
| 135 | + |
| 136 | +. Verify that a new CRI-O config file named `99-podman-fuse` exists. |
| 137 | ++ |
| 138 | +[subs="+attributes,+quotes"] |
| 139 | +---- |
| 140 | +sh-4.4# stat /host/etc/crio/crio.conf.d/99-podman-fuse |
| 141 | +---- |
| 142 | + |
| 143 | +== Using fuse-overlayfs for Podman and Buildah within a workspace |
| 144 | +Users can follow xref:end-user-guide:using-the-fuse-overlay-storage-driver.adoc[] to update existing workspaces to use the fuse-overlayfs storage driver for Podman and Buildah. |
0 commit comments