CephCXV · Cluster-Wide Capacity IncidentCluster-Wide Capacity Incident
The first thirty minutes
What you'll learn
- Stop or throttle the writes that are consuming the remaining space
- Split the response into workstreams that can run concurrently
- Order actions by time to effect rather than by preference
- Establish a measurement cadence that shows the trend
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
Everything you can do about a full cluster is a race against whatever is still writing to it. Winning that race first turns an emergency into a task; losing it means every remedy is overtaken before it lands.
Stop the inflow first
ceph osd pool stats | head -20
ceph df detail | awk '/POOL|rbd|cephfs|rgw/'
# a hard ceiling on the pool that is growing, slightly above current usage
ceph osd pool get-quota rbd-vms
ceph osd pool set-quota rbd-vms max_bytes 34359738368000
# for an RGW tenant filling the cluster
radosgw-admin quota set --quota-scope=user --uid=analytics --max-size=2T
radosgw-admin quota enable --quota-scope=user --uid=analytics
# stop the cluster moving data while you measure and delete
ceph osd set nobackfill
ceph osd set norebalance
Halting backfill removes the one source of usage change you do not control, so the only things moving the number are client writes and your own deletions. Unset both once the cluster has headroom again.
Three workstreams, run concurrently
| Workstream | Owner | First action |
|---|---|---|
| Inflow | whoever can reach the application owners | stop or quota the largest writer |
| Reclamation | the storage on-call | enumerate deletable data before deleting any |
| Capacity | whoever can touch hardware | find out what disks exist on site today |
One person decides. Nobody deletes anything without telling that person,
because two people freeing space independently will both under-report
what they removed and the arithmetic afterwards will not close.
Order by time to effect
| Action | Time to effect | Reversible | Yields space |
|---|---|---|---|
| Stop the writing application | minutes | yes | no — stops growth |
| Pool or user quota | minutes, approximately | yes | no — stops growth |
| Halt backfill and rebalance | immediate | yes | no — stops transient growth |
| Raise the ratios | seconds | yes | no — grants permission only |
| Delete snapshots or scratch pools | minutes to hours | no | yes, often substantially |
| Reweight the fullest OSDs | tens of minutes | yes | no — moves it |
| Add OSDs to existing hosts | hours | yes | yes |
| Add a host | days | yes | yes |
Only two rows create space. Everything else buys time, and buying time
comes first precisely because it is fast.
Knowing whether you are winning
# the two numbers that matter, refreshed: cluster total and the fullest OSD
watch -n 60 'ceph df | head -6; ceph osd df | sort -k17 -n | tail -3'
# a five-minute sample is the trend that matters, not the level
for i in $(seq 1 6); do
date +%H:%M:%S
ceph df | awk '/TOTAL/{print $NF}'
sleep 300
done | paste - -
The number to report upward is the derivative: still climbing, flat, or falling, and at what rate. A cluster at 96% and falling is under control. A cluster at 89% and climbing is not.
Quiz
Knowledge check · 4 questions
Q1. What is the first calculation to make in a capacity incident?
Q2. A pool quota guarantees the pool cannot exceed the configured size.
Q3. Take command of a capacity incident in progress.
The cluster is at 93% on its fullest OSD with 2.4 TiB usable free, ingesting roughly 400 GiB per hour from a batch analytics job that started overnight. Three engineers are online.
Q4. Which incident actions actually create free space, and which only buy time?
Passing score: 75%. Answers are checked in this browser.
Production discipline
Calculate headroom in hours before doing anything else, and lead with the actions that stop the number moving rather than the ones that reduce it. Route every deletion through one decision maker: two people freeing space independently will both under-report what they removed, and the reconciliation afterwards is how a second incident starts.
Cross-course references
- Kubernetes: rate-limiting the admission of new workloads before evicting existing ones
- Linux: killing the writer before running the cleanup, or the cleanup never catches up