The emit operation and reading a complete rule

Intermediate⏱ ~15 mincephcrushtool

What you'll learn

Explain what emit does and when multiple emits are used
Read a complete CRUSH rule and predict its placement
Identify rules that are satisfiable but not what was intended
Document a rule so its intent is recoverable

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

A rule is three or four lines and completely determines what a pool survives. Being able to read one accurately is a small skill with a large payoff.

What emit does

emit takes the current working selection and appends it to the result. Most rules have one:

rule replicated_rule {
  id 0
  type replicated
  step take default
  step chooseleaf firstn 0 type host
  step emit
}

Read it as: enter at default, pick as many distinct hosts as the pool needs, take one OSD in each, return them.

Reading rules accurately

Work through each in turn.

A rack-level replicated rule:

step take default
step chooseleaf firstn 0 type rack
step emit

Three replicas in three distinct racks. Requires at least three racks with usable OSDs.

A device-class rule:

step take default class nvme
step chooseleaf firstn 0 type host
step emit

Three replicas on NVMe OSDs, in three distinct hosts. Requires at least three hosts that each have at least one NVMe OSD — a subtlety worth noting, since a host with no NVMe does not count.

An EC rule across racks:

step take default
step choose indep 3 type rack
step chooseleaf indep 2 type host
step emit

Six chunks: two in each of three racks. A rack failure loses two chunks, so m must be at least 2 to survive one, and at least 3 to survive one with margin.

A rule can be satisfiable and still wrong

crushtool --test reports whether a rule can place the required number of items. It does not report whether that placement means what you intended.

The example above places two chunks per rack. If the EC profile is k=4 m=2, that is exactly on the edge: a rack failure loses two chunks and the pool is at min_size with no margin. Satisfiable, and not what most people mean by “survives a rack failure”.

So validation has two parts:

crushtool -i /tmp/cm.new --test --rule 2 --num-rep 6 --show-bad-mappings
crushtool -i /tmp/cm.new --test --rule 2 --num-rep 6 --show-mappings | head

The first proves it can place. The second lets you read where, and check the arrangement against the failure you intend to survive.

Multiple emits

step take rack-a
step chooseleaf firstn 2 type host
step emit
step take rack-b
step chooseleaf firstn 1 type host
step emit

Two OSDs in rack-a, one in rack-b. Asymmetric by design.

The costs are real: capacity utilisation will be uneven and the balancer cannot correct it, because the imbalance is the rule’s intent. Reserve this for cases where a symmetric rule genuinely cannot express the requirement.

Why rule ids matter and why renumbering moves data

Pools reference rules by id, not by name:

ceph osd pool get rbd-vms crush_rule
ceph osd crush rule dump

Renumbering a rule — which is easy to do accidentally when hand-editing a map, since ids are written explicitly — changes which rule a pool uses. If the new rule at that id has a different failure domain or takes from a different root, the pool’s placement changes entirely and the cluster rebalances.

The result is a large unexplained data movement following a map edit that “only tidied up the rules”.

Two protections: never renumber existing rules when editing a map, and verify crush_rule for every pool after any map change:

for p in $(ceph osd pool ls); do
  printf '%s -> %s\n' "$p" "$(ceph osd pool get $p crush_rule -f json | jq -r .crush_rule)"
done

Documenting intent

A rule’s name should say what it protects:

rule rack_replicated_nvme { ... }

and the design document should record, per pool, the failure it survives and the rule that implements it. The rule syntax states the mechanism; nothing in the cluster states the intent.

Quiz

Knowledge check · 4 questions

Q1. A pool suddenly rebalances after a CRUSH map edit that "only tidied the rules". What is the likely cause?

The tunables were reset to the optimal profile as a side effect of recompiling the map Recompiling and injecting a map always triggers a full rebalance regardless of what changed A rule was renumbered, so the pool referencing that id now uses a different rule The shadow trees for each device class were rebuilt with new weights during the edit
Q2. crushtool --test confirming a rule is satisfiable is sufficient validation.

True False
Q3. Audit a cluster with 9 pools and 5 CRUSH rules to confirm each pool has the protection its design document claims.

Cluster grown over three years with several operators. The design document states which failure each pool should survive, but nobody has verified it against the live map. Five rules exist with names like replicated_rule, rule-1, ssd, rack_rule, and ec_rule. Some pool-to-rule assignments were made during incidents.
Q4. Read this rule and state exactly what it provides: take default class nvme, chooseleaf firstn 0 type host, emit — for a size 3 pool.

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

Production discipline

Validate rules twice: --show-bad-mappings proves they can place, and --show-mappings lets you check the arrangement against the failure you intend to survive — a rule can be satisfiable and still wrong. Never renumber rules when editing a map, since pools reference ids, and verify crush_rule for every pool after any map work. And name rules for the protection they provide, because nothing in the cluster records intent.

Cross-course references

Ceph: Part XV (CRUSH Maps and Rules) for the complete syntax.
Ceph: Part XIII lesson on select for the step arguments.
Ceph: Part XVI (Device Classes) for class-aware rules.