Choosing a feature set per image class

Intermediate⏱ ~16 minrbd

What you'll learn

Define feature sets for common image classes
Configure per-pool or per-class defaults
Change features on existing images safely
Validate feature choices against client capability

Prerequisites

None — start here.

Verified against Ceph Tentacle 20.2.x · Ceph Squid 19.2.x (supported previous) · cephadm matches the verified Ceph release · podman 4.x · csi-rbd and csi-cephfs current · RBD / CephFS / RGW current (matches Ceph release) · Linux kernel 5.15+ (5.10 minimum) · Ubuntu 24.04 LTS (Ceph host baseline) · Debian 12 (Bookworm) (Ceph host baseline) · Rocky Linux / RHEL / AlmaLinux 9.x (Ceph host baseline) · Proxmox VE 9.x (cross-course integration) · Kubernetes 1.31+ (cross-course integration) · 2026-08-18

Why this matters in production

Feature decisions made per image are decisions made inconsistently. Making them per class — VM disk, kernel-mounted volume, mirrored volume — turns a recurring judgment call into a lookup, and makes the resulting configuration explicable.

The classes and their sets

Class	Features	Reason
QEMU/KVM VM disk	full default set	librbd supports everything
Kubernetes CSI (kernel RBD)	`layering, exclusive-lock, object-map, fast-diff, deep-flatten` if the kernel allows, otherwise `layering`	kernel support varies
Bare-metal kernel mount, older kernel	`layering`	maximum compatibility
Mirrored volume (journal-based)	default set plus `journaling`	required for that mirroring mode
Mirrored volume (snapshot-based)	default set	journaling not needed
Shared-access volume (cluster filesystem)	no `exclusive-lock`	multiple writers required

The last row is the exception that matters: a volume mounted read-write by several hosts under a cluster filesystem such as OCFS2 or GFS2 cannot use exclusive-lock, since the whole point is concurrent access. Such volumes also cannot use object-map, which depends on it.

Setting defaults

# cluster-wide
ceph config set global rbd_default_features 61

# per client class, if your deployment separates them
ceph config set client.kubernetes rbd_default_features 1

The bitmask values:

Feature	Bit
`layering`	1
`exclusive-lock`	4
`object-map`	8
`fast-diff`	16
`deep-flatten`	32
`journaling`	64

61 = 1 + 4 + 8 + 16 + 32, the standard set.

Changing features on an existing image

rbd feature disable rbd-vms/vm-disk-01 fast-diff object-map
rbd feature enable  rbd-vms/vm-disk-01 exclusive-lock object-map fast-diff

Enabling object-map on an existing image builds the map, which requires scanning the image:

rbd object-map rebuild rbd-vms/vm-disk-01

On a large image this takes time and should be done during a quiet period. Until the rebuild completes, rbd du and diff operations use the slow path.

Validating against the client

# on the client host, before relying on a feature set
rbd map rbd-vms/test-image
rbd showmapped
rbd unmap /dev/rbd0

Test the actual map on the actual host. Kernel feature support varies with distribution backports and cannot be determined from the version number alone.

Quiz

Knowledge check · 4 questions

Q1. Which image class must not have exclusive-lock enabled?

QEMU/KVM VM disks, because librbd already takes the lock on the host's behalf Kubernetes CSI volumes, because the kernel client cannot hold the lock Mirrored volumes, because the journal writer needs the header left unlocked A volume mounted read-write by multiple hosts under a cluster filesystem
Q2. Enabling object-map on an existing image makes rbd du immediately fast.

True False
Q3. Establish per-class feature policy.

A platform serves QEMU VMs, a Kubernetes cluster using kernel RBD on a modern kernel, several bare-metal hosts on an older enterprise kernel, and one legacy application using a shared volume with GFS2.
Q4. How does an RBD client take over an image whose previous holder crashed?

Passing score: 75%. Answers are checked in this browser.

Production discipline

Define feature sets per image class rather than per image, and document the exceptions — particularly any volume without exclusive-lock, which otherwise looks like a mistake someone will fix. Test kernel feature support on the actual hosts, since distribution backports make version numbers an unreliable guide.

Cross-course references

Kubernetes: StorageClass parameters encode this per-class decision naturally
Linux: filesystem mount options chosen per workload class follow the same pattern