Skip to main content
RunBook Academy

CephXCI · Adding Storage NodesAdding Storage Nodes

Pre-check: capacity and impact for the backfill

Intermediate⏱ ~17 minceph

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

Not yet marked complete on this device.

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'
CheckWhy
No OSD near backfillfullbackfill onto it would be blocked
Cluster healthyoverlapping with a recovery compounds it
No flags seta stale flag would block the movement
Network has headroomthe backfill saturates the cluster network
No other expansion in progressmovements 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

  1. Q1. Why does total consumption rise transiently during an expansion backfill?

  2. Q2. Throttles should be set after the backfill starts, once its impact is observed.

  3. 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.

  4. 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