Why it matters
Choosing the right scheduler is one of the highest-leverage decisions for a multi-tenant cluster. Capacity Scheduler encodes ownership: each team owns a queue, budget conversations happen in terms of queue capacity, and elasticity means underused queues do not go to waste. This aligns cluster resources with organizational structure, which matters more than any technical characteristic in most enterprises.
The alternative, Fair Scheduler, treats users more equally regardless of queue. That is right for some organizations and wrong for others. Capacity Scheduler is the right pick when management sponsors ask hard questions about their team's share.
The architecture
The Capacity Scheduler organizes capacity into a tree rooted at 'root'. Under root live top-level queues (one per business unit typically). Under each of those can live sub-queues (one per team). The tree can go arbitrarily deep but three levels is common in practice.
Each queue has two capacity numbers: a minimum guaranteed capacity (as a percent of its parent) and a maximum capacity (also as a percent of parent). Sum of siblings' minimum capacities under a parent must equal 100 percent. Sum of siblings' maximum capacities can exceed 100 percent, expressing elasticity.
How it works end to end
When an application submits to a queue, the scheduler tries to allocate containers within the queue's current usage. If the queue is below its minimum guaranteed capacity and cluster capacity is available, the allocation succeeds immediately. If the queue is between minimum and maximum and there is unused capacity elsewhere in the tree, the queue can borrow that capacity up to its maximum.
Preemption keeps borrowing honest. When a queue that lent out capacity has new demand for its minimum guarantee, the scheduler can kill borrowing containers in other queues to reclaim the capacity. Preemption is configurable per queue and can be disabled for stability, but disabling it means minimum guarantees are aspirational rather than enforced.
User limits within a queue prevent one user from dominating. A queue's user limit percent caps how much of the queue any single user can consume. This is essential in queues serving multiple analysts to prevent one long-running job from starving everyone else.