RBD image features and kernel compatibility

Advanced⏱ ~17 minrbdkubectl

What you'll learn

State what each RBD feature provides
Determine client support for a feature set
Choose a set that works across the fleet
Diagnose feature-related mapping failures

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

An image feature the node kernel does not support causes mapping to fail with a message naming a bitmask rather than a feature.

What each feature provides

Feature	Provides	Cost
`layering`	clones and snapshots	none
`exclusive-lock`	one writer at a time	lock transfer overhead
`object-map`	tracks which objects exist	faster `du`, resize, delete
`fast-diff`	tracks changes since a snapshot	fast differential backup
`deep-flatten`	flatten works with snapshots present	none
`journaling`	RBD mirroring	significant write overhead
`data-pool`	data in a separate pool	required for EC

object-map and fast-diff both depend on exclusive-lock, and fast-diff depends on object-map.

IMAGE=vm-disk-01
rbd info k8s-rbd/${IMAGE} | grep features

Client support

Client	Feature support
librbd (rbd-nbd, QEMU)	all features
krbd, recent kernels	most features
krbd, older kernels	`layering` only, or a limited set

# what a kernel supports is version-dependent
uname -r
modinfo rbd | head -5

# the failure when a feature is unsupported
# dmesg on the node:
# rbd: image uses unsupported features: 0x38

The bitmask must be decoded against the feature bit values, which is why the error is unhelpful:

1   layering
2   striping
4   exclusive-lock
8   object-map
16  fast-diff
32  deep-flatten
64  journaling
128 data-pool

0x38 is 56, which is 32 + 16 + 8 — deep-flatten, fast-diff, and object-map.

Choosing a set that works everywhere

# conservative: works on any kernel
imageFeatures: layering

# modern kernels, full functionality
imageFeatures: layering,exclusive-lock,object-map,fast-diff,deep-flatten

# with fallback for mixed fleets
mounter: rbd
tryOtherMounters: "true"

# verify against the oldest kernel in the fleet
kubectl get nodes -o jsonpath='{range .items[*]}{.status.nodeInfo.kernelVersion}{"\n"}{end}' | sort -u

Testing against the oldest kernel present is what makes the choice safe, and the fleet’s kernel spread is not always known.

Diagnosing failures

# on the node where mapping failed
IMAGE=vm-disk-01
dmesg -T | grep -i rbd | tail -10

# the image's features
rbd info k8s-rbd/${IMAGE}

# disable the unsupported ones
rbd feature disable k8s-rbd/${IMAGE} object-map fast-diff deep-flatten

# SC is the StorageClass that provisioned the image, from `kubectl get sc`:
SC=ceph-rbd

# and prevent recurrence by changing the StorageClass
kubectl get sc "$SC" -o jsonpath='{.parameters.imageFeatures}'

Disabling features on an existing image fixes that image; changing the StorageClass fixes future ones.

Quiz

Knowledge check · 4 questions

Q1. An image fails to map with `unsupported features: 0x38`. Which features are involved?

layering (1), striping (2), and journaling (64) object-map (8), fast-diff (16), and deep-flatten (32) exclusive-lock (4), journaling (64), and data-pool (128) data-pool (128), striping (2), and layering (1)
Q2. Disabling unsupported features on an existing image prevents the problem recurring for new volumes.

True False
Q3. Resolve feature-related mapping failures across a fleet.

Pods using Ceph volumes start on newer nodes and fail on older ones with unsupported feature errors. The cluster has three kernel versions in use.
Q4. Why does `object-map` make image deletion so much faster?

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

Production discipline

Decode the feature bitmask from a mapping failure rather than disabling everything — the number identifies exactly which features to address. Verify the chosen feature set against the oldest kernel in the fleet, and use tryOtherMounters so newer nodes keep full functionality.

Cross-course references

Kubernetes: capability differences across node versions need explicit handling
Linux: filesystem feature flags produce the identical mount-failure pattern