CephXCI · Adding Storage NodesAdding Storage Nodes
Pre-check: capacity and impact for the backfill
What you'll learn
- Estimate the backfill the addition causes
- Verify the cluster can absorb it
- Plan the impact on clients
- Set the throttles before starting
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
The backfill from an addition is predictable in size and duration, and planning it is what makes the expansion a scheduled operation.
Estimating the backfill
ceph df
ceph osd df | awk 'NR>1 && $1 ~ /^[0-9]+$/ {n++} END {print n, "OSDs currently"}'
current OSDs: 96, adding 12
data: 180 TB
moved ≈ 180 × 12/108 ≈ 20 TB
# and the achievable rate, from a previous expansion or a measurement
# 20 TB at 400 MB/s ≈ 14 hours
Verifying the cluster can absorb it
# no OSD approaches backfillfull during the movement
ceph osd df | sort -k17 -rn | head -5
# and there is headroom for the transient increase
ceph df | grep -A2 'RAW STORAGE'
| Check | Why |
|---|---|
No OSD near backfillfull | backfill onto it would be blocked |
| Cluster healthy | overlapping with a recovery compounds it |
| No flags set | a stale flag would block the movement |
| Network has headroom | the backfill saturates the cluster network |
| No other expansion in progress | movements compound |
ceph -s
ceph osd dump | grep flags
Planning the client impact
# measure the current baseline
# Substitute your own pool before running:
POOL=rbd-vms
fio --name=base --ioengine=rbd --pool="$POOL" --rbdname=probe \
--rw=randwrite --bs=4k --iodepth=32 --runtime=120 --time_based \
--percentile_list=50:95:99
The plan states:
expected duration at the chosen throttle
expected client latency during it
the schedule if paced diurnally
the abort condition
The abort condition is what makes the plan actionable: a stated client
latency above which the backfill is paused with norebalance.
Setting throttles before starting
ceph config set osd osd_mclock_profile high_client_ops
ceph config set osd osd_max_backfills 2
ceph config get osd osd_max_backfills
# and a diurnal schedule if the duration warrants it
0 8 * * * ceph config set osd osd_max_backfills 1
0 20 * * * ceph config set osd osd_max_backfills 6
Setting the throttles before adding the OSDs means the movement starts at the intended rate rather than at the default and being corrected.
Quiz
Knowledge check · 4 questions
Q1. Why does total consumption rise transiently during an expansion backfill?
Q2. Throttles should be set after the backfill starts, once its impact is observed.
Q3. Plan an expansion backfill.
Twelve OSDs will be added to a 96-OSD cluster holding 180 TB. Client latency must stay within agreed limits.
Q4. What should an expansion plan state?
Passing score: 75%. Answers are checked in this browser.
Production discipline
Set the throttles and mClock profile before adding the OSDs so the movement starts at the intended rate rather than at the default. Define an abort condition on client latency before starting; deciding to pause during the impact is a decision made under pressure and made late.
Cross-course references
- Kubernetes: defining rollback criteria before a rollout is the same discipline
- Linux: any long-running operation benefits from a stated abort condition