All diagrams
Storage: Volumes & Claimsk8s 1.36

Filesystem vs Block

Two claims for identical disks, one field apart, so why does only one come back with a filesystem? The volumeMode field is Filesystem unless you say otherwise, so the CSI node service runs mkfs on a blank device, mounts it, and the container finds a directory. Set it to Block and the raw device is published instead, so fsGroup, subPath and file permissions stop applying. The field is immutable and must match on the claim and its volume.

Play the animation 6 steps, animated, best on a wide screen

Filesystem vs Block diagram: volumeMode decides what a Pod is handed

Filesystem vs Block, step by step

  1. Two claims ask for the same 20Gi from the same StorageClass, and each binds its own blank disk. Only one field differs: volumeMode is Filesystem for web-0, which is also what an absent field means, and Block for db-0.

    Play from step 1

  2. Pod web-0 is scheduled to Node-1, and the CSI node service stages its volume first. The device has no filesystem yet, so mkfs runs here and creates one, of the fsType set on the volume or else the driver default, often ext4. A disk that already holds a filesystem is left as it is.

    Play from step 2

  3. Still staging, the CSI node service mounts the new filesystem at a staging path on Node-1, once for the whole Node. Every Pod there that uses this volume is served from that one mount. A driver without the stage capability skips staging and formats and mounts per Pod at publish.

    Play from step 3

  4. Then it publishes the volume into Pod web-0 with a bind mount, and the container finds an ordinary directory at the mountPath from its volumeMounts, /data. Files, permissions, subPath and the fsGroup ownership change all have something to act on here, because there is a filesystem.

    Play from step 4

  5. Pod db-0 lands on the same Node and meets the same CSI node service, but Block skips both of those steps: no mkfs and no filesystem mount. The device itself is published into the container at the devicePath from volumeDevices, /dev/xvda, exactly as the backend delivered it.

    Play from step 5

  6. That is the trade. Pod db-0 gets the bare device and manages its own layout, while fsGroup and subPath have nothing to act on and there are no files inside it to set permissions on. The volumeMode field is fixed once the claim exists and must match the volume, so it is chosen up front.

    Play from step 6

Sources

Commands for this