How an OSD gets its device class

Foundation⏱ ~15 mincephceph-volumelsblk

What you'll learn

Explain how device classes are assigned automatically
Identify situations where automatic classification is wrong
Audit device classes across a cluster
Correct a misclassified OSD safely

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

Device class determines which pools an OSD can serve. A wrong class is silent — the OSD works perfectly and simply serves the wrong tier, which is discovered later as unexplained latency or as a class rule that cannot be satisfied.

How the assignment works

At OSD creation, ceph-volume inspects the device and sets a class:

kernel rotational flag = 1        →  hdd
rotational = 0, not NVMe          →  ssd
device is NVMe                    →  nvme

lsblk -d -o NAME,ROTA,TRAN,MODEL
cat /sys/block/sdb/queue/rotational
ceph osd crush class ls
ceph osd crush class ls-osd nvme

For directly attached devices this is almost always right.

Where it goes wrong

RAID controllers. A controller presenting SSDs as virtual disks often reports rotational = 1, so the OSDs are classed hdd.
HBA firmware. Some HBAs normalise the rotational flag.
NVMe presented through an enclosure may appear as ssd.
Virtualised OSD nodes. A hypervisor’s virtual disk reports whatever the hypervisor decides, often unrelated to the underlying media.

Audit device classes after every OSD addition

for o in $(ceph osd ls); do
  cls=$(ceph osd crush get-device-class osd.$o 2>/dev/null)
  host=$(ceph osd find $o -f json | jq -r '.crush_location.host')
  printf '%-6s %-6s %s\n' "osd.$o" "$cls" "$host"
done | sort -k2,2 -k3,3

Group the output by class and host and look for anomalies: a host with NVMe hardware whose OSDs are classed ssd, or a single hdd among a host of ssd.

This is a five-minute check that prevents the two failure modes — fast devices serving slow pools, and class rules that cannot find enough hosts.

Correcting a class

ceph osd crush rm-device-class osd.12
ceph osd crush set-device-class nvme osd.12
ceph osd crush get-device-class osd.12

Both steps are needed: an OSD can only have one class, and setting a new one requires removing the old.

This moves data. The OSD leaves one shadow tree and joins another, so every pool using either class recomputes placement.

Why classes are strings and what custom classes are for

Device class is an arbitrary string. hdd, ssd, and nvme are conventions that ceph-volume sets automatically, not a fixed enumeration.

Custom classes are occasionally useful:

ceph osd crush set-device-class nvme-high-endurance osd.12
ceph osd crush rule create-replicated wal_rule default host nvme-high-endurance

Legitimate uses include separating two grades of the same media — write-intensive NVMe reserved for a heavy-ingest pool, read-intensive NVMe for everything else — or marking a subset of devices for a specific workload without building a separate subtree.

The caution is that custom classes are not set automatically, so every new OSD needs manual assignment, which reintroduces the manual-step fragility device classes were designed to remove. Use them only when the separation genuinely cannot be expressed with the standard three, and script the assignment so it is not remembered.

Verifying after correction

ceph osd crush class ls-osd nvme
ceph osd crush tree --show-shadow | head -30
ceph -s

Confirm the OSD appears in the intended class list, that the shadow tree reflects it, and that the resulting data movement completes.

Quiz

Knowledge check · 4 questions

Q1. A host with SSDs behind a RAID controller has its OSDs classed as hdd. Why?

ceph-volume classes any device behind a controller as hdd, since it cannot see the media underneath The SSDs are members of a RAID set, and Ceph classes every composite device as rotational media The controller presents virtual disks reporting rotational = 1, which is what ceph-volume reads The class falls back to hdd whenever ceph-volume cannot match the device model against its table
Q2. Device class is a fixed enumeration of hdd, ssd, and nvme.

True False
Q3. An audit finds 16 of 24 SSD-based OSDs classed as hdd across two hosts. Plan the correction.

Two hosts each with 12 SATA SSDs behind a RAID controller in passthrough mode, plus 8 correctly classed SSD OSDs on two other hosts with direct attachment. A pool using an ssd class rule with host separation is currently limited to the two correctly classed hosts, which is why it has been showing undersized PGs intermittently. The cluster holds 200 TB.
Q4. Explain how ceph-volume assigns a device class and give two situations where it gets it wrong.

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

Production discipline

Audit device classes after every OSD addition — grouping OSDs by class and host makes anomalies obvious in five minutes, and the two failure modes it prevents are fast devices serving slow pools and class rules that cannot find enough hosts. Correct misclassifications in throttled batches, since a class change moves the OSD between shadow trees and recomputes placement for both tiers. And prefer the standard three classes, because custom ones are never assigned automatically.

Cross-course references

Ceph: Part XV (CRUSH Maps and Rules) for class-aware rules.
Ceph: Part XVI lesson on wrong class placement for the diagnosis.
Ceph: Part XI (OSD Architecture) for ceph-volume at OSD creation.