Why it matters
Queue hierarchy design encodes cluster policy. A cluster with one flat queue per team encodes a policy of hard team isolation. A cluster with a two-level hierarchy (business unit, then team) encodes shared capacity within each business unit. A three-level hierarchy (BU, team, workload class) adds SLA differentiation within each team.
The right depth depends on organizational complexity. Start simple, add depth only when you can identify a specific problem it would solve.
The architecture
The queue hierarchy is a tree rooted at 'root'. Only leaf queues (those without children) can receive application submissions. Parent queues are for aggregation, ACL enforcement, and capacity roll-up. A three-level tree has root, then business-unit queues, then team queues underneath.
Each queue has ACLs controlling who can submit applications and who can administer the queue. Submission ACLs typically list specific users or groups. Admin ACLs allow queue manipulation like killing running applications. Both are inheritable — a user with submission access to a parent queue can submit to any child queue by default.
How it works end to end
The scheduler evaluates capacity from the root down. A leaf queue with a 25 percent guaranteed capacity of its parent, when the parent has 40 percent of root, gets 10 percent of the cluster as guaranteed. Elastic borrowing works the same way top-down: a queue can only borrow up to its own configured maximum multiplied through its ancestors' maximums.
Submissions are routed by queue name in the application request. Placement policies can override this: the fair-scheduler has a rules engine that assigns applications to queues based on user, group, or job properties without the client specifying explicitly. Capacity Scheduler adds this in newer versions.
User limits inside a queue enforce fairness within that queue. A queue with a 25 percent user limit ensures no single user consumes more than a quarter of the queue's current usage, even if others are idle. This prevents single-user domination in shared queues.