☸️ Kubernetes Error Guide: 'mount propagation not supported' Volume Failure

Overview

When a pod requests a volume with a mountPropagation mode the container runtime or host cannot honor, the kubelet refuses to start the container and surfaces a message like mount propagation ... not supported. You will typically see this on pods that share host mounts (CSI node plugins, storage agents, log collectors) using Bidirectional or HostToContainer propagation.

Mount propagation controls whether mounts created inside a container are visible on the host (and vice versa). It maps directly onto Linux shared-subtree flags (shared, slave, private). If the runtime’s rootfs mount, the host mount, or the runtime configuration does not expose the required propagation, Kubernetes cannot wire the volume and the pod stays stuck in ContainerCreating.

This is a configuration and host-state problem, not a broken image. It is common when a DaemonSet designed for one runtime lands on a node with a different runtime or a host directory mounted private.

Symptoms

Warning  FailedMount  kubelet  MountVolume.SetUp failed for volume "plugin-dir":
mount propagation for volume plugin-dir is not supported by the container runtime

Other variants include path ... is mounted on ... but it is not a shared mount and pods wedged in ContainerCreating. kubectl get pods shows the pod never reaching Running, and kubectl describe pod lists repeated FailedMount events referencing propagation.

Common Root Causes

1. Bidirectional propagation on an unshared host path

A container requests mountPropagation: Bidirectional, but the host directory it mounts is a private mount. The kernel cannot propagate mounts out of the container, so the runtime rejects it.

2. Container runtime not configured for shared propagation

Older or misconfigured containerd/CRI-O setups mount the container rootfs as private or rslave, which cannot support Bidirectional. The runtime then reports propagation as unsupported.

3. DaemonSet assuming a runtime it does not have

CSI node plugins and storage agents ship manifests that require Bidirectional. If the node runs a runtime or kernel that does not expose shared subtrees for that path, the volume fails.

4. Host /var/lib/kubelet or plugin dir mounted private

If the systemd mount for the plugin registration directory is not shared, propagation cannot cross the boundary and every CSI pod that needs it fails.

Diagnostic Workflow

Step 1: Read the exact failure

kubectl describe pod <pod> -n <namespace>

Look for the FailedMount event and note which volume and which propagation mode it names.

Step 2: Inspect the pod’s propagation request

kubectl get pod <pod> -n <namespace> -o yaml | grep -A3 mountPropagation

Confirm whether the container asks for Bidirectional or HostToContainer.

Step 3: Check how the host path is mounted

On the node:

findmnt -o TARGET,PROPAGATION /var/lib/kubelet

PROPAGATION should read shared for Bidirectional to work. private confirms the root cause.

Step 4: Confirm the runtime and its rootfs propagation

kubectl get node <node> -o wide
cat /etc/containerd/config.toml | grep -i propagation

Step-by-Step Resolution

1. Decide whether the pod truly needs Bidirectional. Most workloads only need to read a host mount and can use HostToContainer, which has far weaker host requirements. Change the volume mount:

   volumeMounts:
     - name: plugin-dir
       mountPath: /var/lib/kubelet/plugins
       mountPropagation: HostToContainer

2. If Bidirectional is genuinely required (real CSI node plugins are), make the host path a shared mount on every affected node:

   sudo mount --make-rshared /var/lib/kubelet

3. Persist the shared mount so it survives reboot. Add a systemd unit or an entry that runs mount --make-rshared /var/lib/kubelet at boot, or set the mount propagation in the mount unit.

4. Verify the container runtime supports shared propagation. For containerd, ensure it runs with a modern version and that the rootfs is not forced private:

   containerd --version
   systemctl status containerd

5. Recreate the pod so the kubelet retries the mount:

   kubectl delete pod <pod> -n <namespace>

6. Confirm it reaches Running:

   kubectl get pod <pod> -n <namespace> -w

   NAME             READY   STATUS    RESTARTS   AGE
   csi-node-abcde   2/2     Running   0          22s

Prevention

• Default to HostToContainer unless a component explicitly documents that it needs Bidirectional; it removes the host shared-mount requirement entirely.
• Bake mount --make-rshared /var/lib/kubelet into node bootstrap (cloud-init, kubeadm preflight, or your image build) so every node is ready for CSI plugins.
• Keep container runtimes uniform across the cluster; mixed runtimes make propagation behavior inconsistent and hard to debug.
• Test CSI DaemonSets on a canary node pool before rolling them cluster-wide, since propagation support is a per-node property.
• When authoring a Helm chart with host mounts, expose mountPropagation as a value so operators can adjust it per environment. The DevOps AI prompt library has prompts for generating and reviewing these manifests.

Related Errors

• MountVolume.SetUp failed ... permission denied — a filesystem permission issue on the volume, not propagation.
• path ... is not a shared mount — the same root cause phrased by the runtime rather than the kubelet.
• FailedMount ... timed out waiting for the condition — the CSI attach/mount stalled for a different reason.
• driver name ... not found in the list of registered CSI drivers — the CSI plugin never registered, often downstream of this very failure.

Frequently Asked Questions

What is mount propagation in Kubernetes? It controls whether mounts created inside a container become visible on the host and vice versa, mapping to Linux shared-subtree flags. The modes are None, HostToContainer, and Bidirectional.

Why does Bidirectional fail when HostToContainer works? Bidirectional requires the host path to be a shared mount and the runtime rootfs to support shared propagation. HostToContainer only needs the host to propagate into the container, which most setups already allow.

How do I make /var/lib/kubelet a shared mount? Run sudo mount --make-rshared /var/lib/kubelet on the node and persist it at boot. Verify with findmnt -o TARGET,PROPAGATION /var/lib/kubelet.

Is this a bug in my CSI driver? Usually not. The driver correctly requests Bidirectional; the node simply is not configured with a shared mount, which is a host-provisioning gap.

Can I fix this without node access? If you can switch the workload to HostToContainer you can avoid host changes, but true CSI node plugins need the shared mount, which requires node-level configuration. For more patterns, see the Kubernetes & Helm guides.