Subvolumes as the operational unit

Why this matters in production

Doing the four things a subvolume does — directory, quota, placement, credential — by hand is four opportunities to get something subtly wrong. The managed interface does them together and is what CSI drivers use, so adopting it also aligns manual operations with automated ones.

The hierarchy

ceph fs volume ls
ceph fs subvolumegroup create cephfs research
ceph fs subvolumegroup ls cephfs

ceph fs subvolume create cephfs project-alpha \
    --group_name research \
    --size 5497558138880 \
    --pool_layout cephfs-data-nvme
ceph fs subvolume ls cephfs --group_name research
ceph fs subvolume info cephfs project-alpha --group_name research

Getting the mount path

ceph fs subvolume getpath cephfs project-alpha --group_name research
# /volumes/research/project-alpha/8f3a2b1c-...

Always resolve the path through this command rather than constructing it — the UUID component is generated and is what prevents a recreated subvolume reusing a previous one’s path.

Credentials

ceph fs subvolume authorize cephfs project-alpha client.alpha \
    --group_name research --access_level=rw
ceph fs subvolume authorized_list cephfs project-alpha --group_name research
ceph fs subvolume deauthorize cephfs project-alpha client.alpha --group_name research

This generates the path-restricted MDS capability and the tag-based OSD capability correctly, which is the part most often got wrong by hand.

Snapshots and clones

ceph fs subvolume snapshot create cephfs project-alpha snap-1 --group_name research

# clone the snapshot into a new subvolume
ceph fs subvolume snapshot clone cephfs project-alpha snap-1 project-alpha-copy \
    --group_name research
ceph fs clone status cephfs project-alpha-copy

CephFS subvolume cloning copies data rather than referencing it, so it is not instantaneous — clone status reports progress. This differs from RBD cloning and is worth knowing before promising a fast copy.

Removal

ceph fs subvolume rm cephfs project-alpha --group_name research
ceph fs subvolume rm cephfs project-alpha --group_name research --retain-snapshots

Removal is asynchronous: the subvolume moves to a trash location and its contents are purged in the background, so the capacity is not returned immediately.

Quiz

Production discipline

Adopt the subvolume interface for manual provisioning as well as automated, so there is one model rather than two — and because it generates the capability and path correctly. Resolve mount paths with getpath rather than by convention; the UUID is a protection that constructed paths discard.

Cross-course references

• Kubernetes: the CSI driver uses this exact interface, so manual and automated provisioning converge
• Linux: managed dataset abstractions such as ZFS datasets serve the same bundling purpose